Back to Details

onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Onboarding

新成员引导

onboarding documentationは「READMEがある」ことではなく、fresh contributor / fresh agentがproject truthへ自力で到達できることを目的とする。
新成员引导文档的目的不是“存在 README”，而是让 fresh contributor / fresh agent 能够自行找到 project truth。

1. Onboarding completion target

1. 新成员引导完成目标

新規参入者が会話履歴・個人memory・既存memberの口頭説明なしで最低限次を行える状態にする。
  1. projectの目的とscopeを理解
  2. architecture / major boundariesを把握
  3. local environmentをbootstrap
  4. application / serviceを起動
  5. test / validationを実行
  6. weekly sprint / target release / Issue dependencyを確認
  7. Issueを選びticket branchを作成
  8. first meaningful commitをremoteへpublishし、remote head SHA一致を確認した直後にPRを作成し、作業状態に応じてDraft/Readyを設定したうえでassignee / reviewer / labels / Issue linkage / target release / stack contextを設定
  9. independent ticketかstacked dependent ticketかを判断
  10. decision / design / ADR / Skillの参照先を発見
  11. common failureを切り分け
  12. 中断されたticketをIssue / PR / Git / checkpointから復旧
让新加入者无需依赖对话历史、个人 memory 或现有成员的当面说明，至少能够完成以下事项。
  1. 理解 project 的目的和 scope
  2. 掌握 architecture / 主要边界
  3. bootstrap local environment
  4. 启动 application / service
  5. 执行 test / validation
  6. 确认 weekly sprint / target release / Issue dependency
  7. 选择 Issue 并创建 ticket branch
  8. 将首个有意义的 commit 发布到 remote，并在确认 remote head SHA 一致后立即创建 PR；根据工作状态设置 Draft/Ready，然后设置 assignee / reviewer / labels / Issue linkage / target release / stack context
  9. 判断是 independent ticket 还是 stacked dependent ticket
  10. 找到 decision / design / ADR / Skill 的参考位置
  11. 排查常见 failure
  12. 从 Issue / PR / Git / checkpoint 恢复中断的 ticket

2. Document structure

2. 文档结构

project規模に合わせて最小限に構成する。
候補:
  • README.md
    : project overview / first entry point
  • CONTRIBUTING.md
    : development workflow / GitHub workflow
  • docs/architecture.md
    : system boundaries / dependency direction / data flow
  • docs/development.md
    : bootstrap / run / test / validation
  • docs/troubleshooting.md
    : recurring failure / diagnosis
  • docs/release.md
    : planning / release batching / deployment
  • docs/security.md
    : security maintenance / reporting when appropriate
  • docs/recovery.md
    : checkpoint / recovery / external side-effect workflow when complexity justifies it
  • ADR directory
  • design/specification directory
  • project-local Agent Skills
巨大な1 documentへ全て詰め込まない。入口から必要なdetailへprogressive disclosureできるようにする。
documentationは作業contextの保存先ではなくreader-facing artifactとして扱う。新規作成・更新時は 
writing-discipline
に従い、Select -> Compose -> Rereadで独立した文章へ整える。
根据 project 规模，以最小必要方式组织。
候选项：
  • README.md
    ：project overview / 首个入口
  • CONTRIBUTING.md
    ：development workflow / GitHub workflow
  • docs/architecture.md
    ：system boundaries / dependency direction / data flow
  • docs/development.md
    ：bootstrap / run / test / validation
  • docs/troubleshooting.md
    ：recurring failure / diagnosis
  • docs/release.md
    ：planning / release batching / deployment
  • docs/security.md
    ：security maintenance / reporting（适用时）
  • docs/recovery.md
    ：checkpoint / recovery / external side-effect workflow（复杂度确有需要时）
  • ADR 目录
  • design/specification 目录
  • project-local Agent Skills
不要将所有内容塞进一个巨型文档。应采用渐进式披露，让读者能够从入口逐步找到所需的 detail。
documentation 应被视为面向读者的产物（reader-facing artifact），而不是工作上下文的存放地。新建或更新时，应遵循 
writing-discipline
，通过 Select -> Compose -> Reread 整理成可独立阅读的文字。

3. README minimum

3. README 最低要求

READMEにはprojectに応じて最低限:
  • 何を作るprojectか
  • support/target platform
  • architecture overviewへのlink
  • prerequisites
  • canonical bootstrap command
  • canonical run command
  • canonical validation entry point
  • internal docs index
  • contribution entry point
  • recovery entry point / 
    agent-recovery
    Skillへの導線
を置く。
READMEへ内部実装detailを過剰に置かない。
README 应根据 project 情况至少包含：
  • project 的用途
  • 支持及目标 platform
  • architecture overview 链接
  • prerequisites
  • canonical bootstrap command
  • canonical run command
  • canonical validation entry point
  • internal docs index
  • contribution entry point
  • recovery entry point / 
    agent-recovery
    Skill 导流
不要在 README 中过度放入内部实现 detail。

Public README badges

Public README 徽章

public repositoryでは、README冒頭のbadgeが読者の判断を速くする場合は積極的に採用する。
badgeは装飾ではなく、projectの現在状態・配布情報・信頼性・主要actionへの短い導線として扱う。候補:
  • CI / build / test status
  • release / package version
  • license
  • package downloadsやGitHub Stars等のadoption signal
  • deploy / demo / documentation等のaction badge
選定原則:
  • projectに実在し、現在も維持されている情報だけを表示する
  • GitHub Actionsやhosting/package provider等が公式badge/buttonを提供する場合はそれを優先する
  • 汎用badgeが必要な場合はShields.io等のmaintained serviceを使用してよい
  • badgeのlink先はstatus details、release/package page、license、deploy target等、表示内容に対応するcanonical destinationへ向ける
  • 同じ情報をREADME本文やGitHub UIと重複表示するだけで判断価値が低いbadgeは省く
  • private repositoryや、外部読者向けのsignal/actionが不要なrepositoryでは無理に追加しない
  • badge数を増やすことを目的にせず、README title直下の可読性と情報hierarchyを維持する
在 public repository 中，如果 README 开头的 badge 能帮助读者更快判断，应积极采用。
badge 不是装饰，而应作为通往 project 当前状态、分发信息、可靠性及主要 action 的简短导流。候选项：
  • CI / build / test status
  • release / package version
  • license
  • package downloads 或 GitHub Stars 等 adoption signal
  • deploy / demo / documentation 等 action badge
选择原则：
  • 只显示 project 中真实存在且目前仍在维护的信息
  • 如果 GitHub Actions、hosting 或 package provider 等提供官方 badge/button，应优先使用
  • 如需通用 badge，可以使用 Shields.io 等仍在维护的服务
  • badge 的链接应指向与显示内容对应的 canonical destination，例如 status details、release/package page、license 或 deploy target
  • 如果只是在 README 正文或 GitHub UI 中重复同一信息，且对判断没有明显帮助，则应省略该 badge
  • 对于 private repository，或无需向外部读者提供 signal/action 的 repository，不要强行添加
  • 不要以增加 badge 数量为目的，应保持 README title 正下方的可读性和信息层级

4. Development guide

4. 开发指南

最低限:
  • supported host: macOS / WSL/Linux等
  • project-local toolchain bootstrap: mise採用時は 
    mise.toml
    / version authority / lock strategyを記述し、lockfile運用なら 
    mise install --locked
    をcanonical bootstrapにする
  • runtime/sandbox bootstrap
  • dependency install
  • env setup
  • DB migration/seed
  • app/service startup
  • local preview / port access
  • worker/integration/release validation commands
  • generated code handling
  • common cache/reset operations
を実repoのcommandから記述する。
存在しないcommandや古いsetupを推測で書かない。
mise採用projectはshell activationへ依存せず 
mise exec -- ...
/ 
mise run <task>
を使える形にし、native canonical version sourceとの二重pinを避ける。external/untrusted PRではmise command実行前にtrust reviewまたはbounded sandboxを必須とし、mise自体をisolation boundaryにしない。
最低要求：
  • supported host：macOS / WSL/Linux 等
  • project-local toolchain bootstrap：采用 mise 时，说明 
    mise.toml
    / version authority / lock strategy；如果采用 lockfile 管理，则将 
    mise install --locked
    设为 canonical bootstrap
  • runtime/sandbox bootstrap
  • dependency install
  • env setup
  • DB migration/seed
  • app/service startup
  • local preview / port access
  • worker/integration/release validation command
  • generated code handling
  • common cache/reset operations
这些内容都应根据实际 repo 中的 command 编写。
不要猜测不存在的 command，也不要记录过时的 setup。
对于采用 mise 的 project，不应依赖 shell activation，而应做到可以使用 
mise exec -- ...
/ 
mise run <task>
，并避免与 native canonical version source 形成双重 pin。执行 external/untrusted PR 中的 mise command 之前，必须进行 trust review 或使用 bounded sandbox；不得把 mise 本身当作 isolation boundary。

5. Architecture guide

5. 架构指南

visual/structuralに把握できるよう、必要ならMermaid等で次を示す。
  • major components/services
  • dependency direction
  • data flow
  • external systems
  • persistence boundaries
  • trust/security boundaries
  • build/deploy/runtime boundaries
  • Supervisor / sandbox / checkpoint boundary when agent infrastructure is non-trivial
詳細なdecision historyはADRへ分離する。
为了能够从视觉和结构上把握，必要时使用 Mermaid 等方式展示：
  • major components/services
  • dependency direction
  • data flow
  • external systems
  • persistence boundaries
  • trust/security boundaries
  • build/deploy/runtime boundaries
  • 当 Agent 基础设施较为复杂时，展示 Supervisor / sandbox / checkpoint boundary
详细的 decision history 应与本指南分离并放入 ADR。

6. Development decision discovery

6. 开发决策发现机制

新規参入者が次の優先順位を発見できるようにする。
project-wide policy > design/spec/task instruction > existing implementation majority
root agent instruction / CONTRIBUTING / development docsから、canonical policy・design・ADR・Skillsへの導線を明示する。
让新加入者能够按以下 priority 发现决策依据：
project-wide policy > design/spec/task instruction > existing implementation majority
从 root agent instruction / CONTRIBUTING / development docs 中，明确给出通往 canonical policy / design / ADR / Skills 的导流。

7. GitHub workflow guide

7. GitHub 工作流指南

週次planningと可変releaseを区別し、1 release train = 1 version = 1 branch、candidate freeze、明示的release承認を説明する。
independent ticket:
text
main
└─ release-x-y-z
   └─ <issue-number>
stacked hard dependency:
text
main
└─ release-x-y-z
   └─ 123
      └─ 124
         └─ 125
明示する:
  • Issue/PRは日本語
  • commitは英語
  • ticket branchはIssue番号のみ
  • Issue dependency graphがcanonical dependency SoT
  • independent ticket PR baseはtarget release branch
  • stacked dependent ticket PR baseはimmediate predecessor ticket branch
  • stack membersは同じtarget release trunkを共有
  • branch作成→commit→remote publish/head確認→PR作成・state設定までを一手順にする
  • active branchにremote headとPRを必須とし、作業中はDraft、readyならReadyにする
  • readyなPRは最初からReadyにする
  • subagent/workerにも同じ公開・PR lifecycleを適用
  • PRにIssue・assignee・reviewer・labels・release/stackを紐づけ、mappingを永続化
  • predecessor変更後はdownstreamのbaseとcurrent-SHA validationを再確認
  • ticket PRはquality gate後にdependency順で自律landing（追加のmerge許可は不要）
  • stacked ticketはrelease trunk到達後にIssue closeする（predecessor landingだけではDoneにしない）
  • landing後はdependent PRを調整し、安全なticket branchを削除する
  • release差分が生じたらDraft release PRを作成し、readinessでReadyへ進める
  • release PRは
    release-* -> main
    のみ。bulk ticket landingから除外する
  • release mergeはcurrent interactionでのexplicit authorizationを必須とする
  • public repositoryの
    main
    はrulesetで保護し、release PR経由でのみ変更する
  • merge commitのみ許容（squash/rebaseは禁止）。repo設定とPR landing methodは
    merge
    で統一する
  • Draft -> Ready -> target release-trunk landing -> Issue close / Project Doneの条件
意味のあるreviewerがいないrepositoryでは、形式的な自己reviewerを設定するのではなく、その事実と代替review pathを文書化する。
区分 weekly planning 与 variable release，并说明 1 release train = 1 version = 1 branch、candidate freeze，以及明确的 release approval。
independent ticket：
text
main
└─ release-x-y-z
   └─ <issue-number>
stacked hard dependency：
text
main
└─ release-x-y-z
   └─ 123
      └─ 124
         └─ 125
明确规定：
  • Issue/PR 使用日语，commit 使用英语
  • ticket branch 仅使用 Issue 编号
  • Issue dependency graph 是 canonical dependency SoT
  • independent ticket 的 PR base 为 target release branch
  • stacked dependent ticket 的 PR base 为紧邻的 predecessor ticket branch
  • stack members 共享同一 target release trunk
  • 将 branch 创建 → commit → remote publish/head 确认 → PR 创建与 state 设置视为一个连续步骤
  • active branch 必须有 remote head 和 PR；处理中设为 Draft，可以提交 review 时设为 Ready
  • ready 的 PR 从一开始就设为 Ready
  • 对 subagent/worker 同样应用相同的发布 / PR lifecycle
  • 在 PR 中关联 Issue、assignee、reviewer、labels、release/stack，并持久化 mapping
  • predecessor 变更后，重新确认 downstream 的 base 与 current-SHA validation
  • ticket PR 在通过 quality gate 后，按 dependency 顺序自主 landing，无需额外的 merge 授权
  • stacked ticket 在到达 release trunk 后才关闭 Issue；仅 predecessor landing 不应视为 Done
  • landing 后调整 dependent PR，并删除安全的 ticket branch
  • 如果出现 release 差异，创建 Draft release PR，并根据 readiness 转为 Ready
  • release PR 仅允许 
    release-* -> main
    ；排除在 bulk ticket landing 之外
  • release merge 必须在当前交互中获得 explicit authorization
  • 通过 ruleset 保护 public repository 的 
    main
    ，且仅允许通过 release PR 修改
  • 只允许 merge commit（禁止 squash/rebase）。repo 设置和 PR landing method 均统一为 
    merge
  • Draft -> Ready -> target release-trunk landing -> Issue close / Project Done
    的状态条件
在缺少有意义 reviewer 的 repository 中，不要形式化地设置 self-reviewer，而应记录这一事实以及替代 review path。

8. Recovery discovery

8. 恢复信息发现

fresh agentが以前のchatを読めなくても、次を発見できるようにする。
  • current Issue / PR / target release
  • immediate stack predecessor / pinned predecessor SHA when applicable
  • ticket branch / checkpointの見つけ方
  • agent-recovery
    Skill
  • current/next validation command
  • active child/subagentの確認方法
  • external side-effect journalの場所
  • recovery時にuserへ確認すべき条件
PR欠落・state driftはdurable Issue/branch/baseから修復。Ready ticketはlanding・Issue close・safe cleanupまで行う。release PRはzero-diff例外以外で保持し、explicit authorizationなしにmergeしない。詳細は
github-delivery
・
agent-recovery
。
native session resumeの手順だけを書いてrecovery guideとしない。sessionが失われても復旧できるdurable pathを記載する。
即使 fresh agent 无法读取之前的 chat，也必须能够发现以下信息：
  • current Issue / PR / target release
  • 适用时的 immediate stack predecessor / pinned predecessor SHA
  • ticket branch / checkpoint 的查找方式
  • agent-recovery
    Skill
  • current/next validation command
  • active child/subagent 的确认方式
  • external side-effect journal 的位置
  • recovery 时需要向 user 确认的条件
PR 缺失或 state drift 时，应从 durable Issue/branch/base 修复。Ready ticket 要完成 landing、Issue close 和 safe cleanup。release PR 除 zero-diff 例外外应予保留，未经 explicit authorization 不得 merge。详情参见 
github-delivery
、
agent-recovery
。
不要只把 native session resume 的步骤写成 recovery guide。必须记录即使 session 丢失也能恢复的 durable path。

9. Documentation verification

9. 文档验证

docsもquality gateの対象にする。
可能なら:
  • documented commandsをCI/fresh sandboxで実行
  • broken links検出
  • setup pathをfresh environmentで確認
  • GitHub workflow exampleがcurrent delivery policyと一致するか検証
  • public repositoryの
    main
    protection/rulesetが実際に有効か確認
  • repositoryのPR merge method設定がmerge commit onlyになっているか確認し、変更権限がなければ差分をblocker/limitationとして明示
  • recovery pathをfresh agent/sandboxでdrill
  • version-sensitive instructionsをupgrade時にreview
  • conversation / task / execution contextなしで文章単体を理解できるかreader視点でreread
  • chronology dump、不要なcurrent-state記述、context-dependent referent、重複を編集
「READMEには書いてあるがfresh cloneでは動かない」「recovery guideはあるがcheckpointから復旧できない」「CONTRIBUTINGだけ古いPR lifecycleのまま」を許容しない。
docs 也应纳入 quality gate。
尽可能做到：
  • 在 CI/fresh sandbox 中执行已记录的 command
  • 检测 broken links
  • 在 fresh environment 中确认 setup path
  • 验证 GitHub workflow example 是否符合当前 delivery policy
  • 确认 public repository 的 
    main
    protection/ruleset 是否实际生效
  • 确认 repository 的 PR merge method 设置为仅允许 merge commit；如果没有修改权限，应将差异明确标为 blocker/limitation
  • 使用 fresh agent/sandbox 对 recovery path 进行 drill
  • 在升级时 review 对版本敏感的 instruction
  • 以 reader 视角重新阅读，在没有 conversation / task / execution context 的情况下确认文字可以独立理解
  • 编辑 chronology dump、不必要的 current-state 描述、依赖上下文的 referent 和重复内容
不允许出现“README 中写了但在 fresh clone 中无法运行”“存在 recovery guide 却无法从 checkpoint 恢复”“CONTRIBUTING 仍保留旧 PR lifecycle”等情况。

10. Update triggers

10. 更新触发条件

次の場合はonboarding docsを更新する。
  • bootstrap/run/validation command変更
  • architecture boundary変更
  • framework/runtime migration
  • mise / toolchain bootstrap / version authority / lock strategy変更
  • environment/host support変更
  • sprint cadence / release workflow変更
  • stacked PR / dependency workflow変更
  • branch / PR state / PR metadata lifecycle変更
  • public repositoryのmain protection/ruleset変更
  • PR merge method / repository merge settings変更
  • Supervisor/sandbox/recovery model変更
  • recurring troubleshooting knowledgeが増えた
  • security/dependency maintenance workflow変更
実装変更でdocsがstaleになるなら同じticket/PR内で更新する。
出现以下情况时，应更新 onboarding docs：
  • bootstrap/run/validation command 发生变化
  • architecture boundary 发生变化
  • framework/runtime migration
  • mise / toolchain bootstrap / version authority / lock strategy 发生变化
  • environment/host support 发生变化
  • sprint cadence / release workflow 发生变化
  • stacked PR / dependency workflow 发生变化
  • branch / PR state / PR metadata lifecycle 发生变化
  • public repository 的 main protection/ruleset 发生变化
  • PR merge method / repository merge settings 发生变化
  • Supervisor/sandbox/recovery model 发生变化
  • recurring troubleshooting knowledge 增加
  • security/dependency maintenance workflow 发生变化
如果实现变更导致 docs 过期，应在同一个 ticket/PR 中更新文档。

11. Temporary artifact contract

11. 临时产物约定

一時的な検証・調査artifactはrepository root直下の 
.tmp/
以下へ集約する。
対象例:
  • test result / report
  • 一次log
  • screenshot
  • trace
  • diagnostic file
  • generated verification artifact
  • temporary fixture
  • one-off investigation output
禁止:
  • repository rootへ一時fileを直接散らす
  • .tmp/
    artifactを通常sourceとして参照する
  • 正式なdocumentation/test fixture等へ明示的に昇格していない一時artifactをcommitする
.tmp/
はGit ignoreする。正式artifactへ昇格する場合はcanonical locationへ移し、temporary originへ依存しない状態にする。
临时验证与调查 artifact 应统一放在 repository root 直属的 
.tmp/
目录下。
对象示例：
  • test result / report
  • 一次生成的 log
  • screenshot
  • trace
  • diagnostic file
  • generated verification artifact
  • temporary fixture
  • 一次性调查输出
禁止：
  • 在 repository root 中直接散落临时 file
  • 将 
    .tmp/
    artifact 作为常规 source 引用
  • commit 尚未明确升级为正式 documentation/test fixture 等内容的临时 artifact
应将 
.tmp/
加入 Git ignore。升级为正式 artifact 时，将其移至 canonical location，并确保不依赖 temporary origin。

12. External reference repository contract

12. 外部参考仓库约定

外部repositoryをsource/design/referenceとして調査する必要がある場合、target project root直下の 
.reference/
以下へcloneできる。
.reference/
はGit ignoreし、reference repositoryをproject本体の一部として扱わない。
禁止:
  • project source treeへ直接組み込む
  • implicit build dependencyにする
  • implicit runtime dependencyにする
  • reference repository内の変更をtarget projectの成果物としてcommitする
  • .reference/
    の存在をfresh clone / build / test / runの必須条件にする
必要な時だけcloneし、削除してもprojectが正常にbootstrap/build/test/runできる状態を維持する。
source/code/designをcopyする場合は事前にlicense / redistribution / attribution / copied-source restrictionを確認する。
如果需要将 external repository 作为 source/design/reference 进行调查，可以将其 clone 到 target project root 直属的 
.reference/
目录下。
应将 
.reference/
加入 Git ignore，并且不要将 reference repository 视为 project 本体的一部分。
禁止：
  • 直接将其整合进 project source tree
  • 将其设为 implicit build dependency
  • 将其设为 implicit runtime dependency
  • 将 reference repository 内的更改作为 target project 的成果物 commit
  • 将 
    .reference/
    的存在作为 fresh clone / build / test / run 的必要条件
仅在需要时 clone，并确保删除后 project 仍可正常 bootstrap/build/test/run。
如果复制 source/code/design，应事先确认 license / redistribution / attribution / copied-source restriction。

13. Environment / 
.gitignore
hygiene

13. 环境 / 
.gitignore
卫生

actual dotenvのcanonical policy:
  • .env
  • .env.development
  • .env.production
を実値用として扱いGit ignoreする。
committed schema/example:
  • .env.example
  • .env.development.example
  • .env.production.example
を許可する。
example filesはenvironment variable schemaとして維持し、GitHub Actions / GitHub Secretsで使用するvariable名も対応するexampleへ反映する。secretにはvalueを書かず 
SECRET_NAME=
のようにnameだけを残す。public configurationだけsafe example valueを置ける。
GitHubのstored secret valueを後から読み戻せることをbootstrap/recovery前提にしない。localとCIで同じ概念のvariable名を不必要に変えない。
.gitignore
はstackを調査して最低限次を検討する。
  • .tmp/
  • .reference/
  • actual dotenv files
  • dependencies
  • build outputs
  • generated caches
  • test / coverage outputs
  • tool caches
  • OS/editor temporary files
  • local secret artifacts
一方、次を誤ってignoreしない。
  • source
  • lockfile
  • reproducibility configuration
  • Agent Skills / project agent config
  • CI/CD configuration
  • committed env examples
重複・相互矛盾するignore ruleを無秩序に追加しない。
このpolicyのためだけにpre-commit hookを新設しない。必要なvalidationはproject scriptとCIから再現可能にする。
actual dotenv 的 canonical policy：
  • .env
  • .env.development
  • .env.production
这些文件作为实际值使用，并加入 Git ignore。
允许 committed schema/example：
  • .env.example
  • .env.development.example
  • .env.production.example
example file 应作为 environment variable schema 维护，并将 GitHub Actions / GitHub Secrets 使用的 variable 名同步到对应 example。secret 中不得写入 value，只保留 
SECRET_NAME=
这样的名称。只有 public configuration 可以放入安全的示例值。
不要将“之后能够读回 GitHub stored secret value”作为 bootstrap/recovery 的前提。local 与 CI 中同一概念的 variable 名不要无谓改变。
应调查 stack，并至少考虑将以下内容加入 
.gitignore
：
  • .tmp/
  • .reference/
  • actual dotenv file
  • dependencies
  • build outputs
  • generated caches
  • test / coverage outputs
  • tool caches
  • OS/editor temporary file
  • local secret artifact
另一方面，不要错误地 ignore 以下内容：
  • source
  • lockfile
  • reproducibility configuration
  • Agent Skills / project agent config
  • CI/CD configuration
  • committed env example
不要无序添加重复或相互矛盾的 ignore rule。
不要仅为此 policy 新设 pre-commit hook。必要的 validation 应能够通过 project script 和 CI 复现。

14. Fresh-clone audit

14. Fresh-clone 审计

初期化完了前に、既存machine stateを一度忘れたfresh cloneの視点で確認する。
最低限:
  • agent behaviorを定義するcanonical fileは何か
  • Skills / adapters / plugin configはどこか
  • required binariesとprovision方法は何か
  • undocumented global software/configを暗黙要求していないか
  • environment variablesとexample schemaは何か
  • secrets/trust/authenticationはどう供給されるか
  • supported host/runtimeでbootstrapできるか
  • home directory config / implicit persistent memoryに依存していないか
  • .tmp/
    / 
    .reference/
    / actual envがignoredか
  • env examples / lock/reproducibility configがcommittedか
  • mise等のrepository-controlled bootstrap pathとcanonical 
    mise exec
    / 
    mise run
    entry pointをfresh environmentで再現できるか
  • mise lockfile運用ならbounded request + 
    mise install --locked
    で不足entryを検出できるか
  • external/untrusted PRでmise実行前のtrust review / bounded sandbox gateがあるか
  • native canonical version sourceとmiseに競合する二重pinがないか
  • .reference/
    がなくてもbuild/test/runできるか
  • local validationとCIが同じcanonical semanticsを呼ぶか
  • documented bootstrap/run/validation commandをfresh environmentで実行できるか
hidden dependencyが見つかった場合はdocumentationだけで正当化せず、可能ならrepository-controlled reproducibilityへ移す。
初始化完成前，应从暂时忘记现有 machine state 的 fresh clone 视角进行检查。
最低要求：
  • 定义 agent behavior 的 canonical file 是哪一个
  • Skills / adapters / plugin config 位于何处
  • required binaries 及其 provision method 是什么
  • 是否隐式要求 undocumented global software/config
  • environment variables 与 example schema 是什么
  • secrets/trust/authentication 如何提供
  • 能否在 supported host/runtime 上完成 bootstrap
  • 是否依赖 home directory config / implicit persistent memory
  • .tmp/
    / 
    .reference/
    / actual env 是否已 ignored
  • env example / lock/reproducibility config 是否已 committed
  • 能否在 fresh environment 中复现 mise 等 repository-controlled bootstrap path，以及 canonical 
    mise exec
    / 
    mise run
    entry point
  • 如果采用 mise lockfile 管理，能否通过 bounded request + 
    mise install --locked
    检测缺失的 entry
  • 在 external/untrusted PR 中，是否存在 mise 执行前的 trust review / bounded sandbox gate
  • 是否存在 native canonical version source 与 mise 冲突的 double pin
  • 没有 
    .reference/
    时能否完成 build/test/run
  • local validation 与 CI 是否调用相同的 canonical semantics
  • 已记录的 bootstrap/run/validation command 能否在 fresh environment 中执行
如果发现 hidden dependency，不要仅通过 documentation 加以合理化；如有可能，应将其迁移到 repository-controlled reproducibility。

15. Initialization completion report

15. 初始化完成报告

初期化終了時は、単に「完了」と報告せず最低限次を簡潔にexternalizeする。
  • detected stack / architecture / target platform
  • official guidance investigated
  • existing agent configuration
  • files created/changed
  • Skillsとactivation conditions
  • plugins/tools considered
  • selected toolsとselection reason
  • rejected meaningful candidatesとrejection reason
  • ADRs created/updated
  • canonical bootstrap/run/validation entry points
  • test / quality / CI configuration
  • environment / secret schema configuration
  • remaining trust/authentication/user gates
  • existing quality/dependency debt
  • known limitations / unreproducible items
report内容がconversationにしか残らないlong-lived decisionを含む場合は、先にrepository-controlled docs/ADRへ永続化する。
初始化结束时，不要只报告“完成”，至少应简洁 externalize 以下内容。
  • 检测到的 stack / architecture / target platform
  • 已调查的 official guidance
  • 现有 agent configuration
  • 创建或修改的文件
  • Skills 及其 activation conditions
  • 已考虑的 plugins/tools
  • 选定的 tools 及选择原因
  • 被排除的合理候选项及排除原因
  • 创建或更新的 ADR
  • canonical bootstrap/run/validation entry point
  • test / quality / CI configuration
  • environment / secret schema configuration
  • 尚存的 trust/authentication/user gate
  • 现有 quality/dependency debt
  • 已知 limitation / 无法复现的内容
如果报告中包含仅存在于 conversation 中的 long-lived decision，应先将相关内容持久化到 repository-controlled docs/ADR。