08 第二篇 · 准备：每个项目做一次

项目初始化

环境装好之后，每个项目还要做一次初始化：把项目事实、约定和工作流程立起来，让 Agent 能找到可靠依据。全新项目主要向前定义；存量项目先建立代码事实基线，再根据每份 steering 的实际状态选择建立或审计。两条路最后都要初始化 spec-kit、生成 constitution，并用一个结果已知的小任务校准流程。

初始化不是把文件复制进去就结束。完成时，适用的 steering 已填成项目真实内容，不适用的可选文件已经移除，命令能够运行，入口没有失效链接，也没有覆盖项目原有材料。

8.1 获取方法骨架

方法骨架位于公开仓库的 template/ 目录。先在项目外克隆一份：

git clone https://github.com/tudouya/vibe-kit.git

通过标准：克隆目录中能看到 template/AGENTS.md、template/.kiro/steering/ 和 template/.kiro/prompts/。

复制前先检查目标项目里是否已经有 AGENTS.md、CONTEXT.md 或 .kiro/。这些文件可能包含项目自己的规则和配置，不能被模板覆盖。

目标项目没有同名文件时，可以复制整个骨架：

cp -R <克隆目录>/template/. <你的项目>/

目标项目已有同名文件时，不运行上面的覆盖式复制。先保证现有改动可恢复，再用不覆盖已有文件的方式补入缺失项：

cp -Rn <克隆目录>/template/. <你的项目>/

-n 会跳过已经存在的文件。复制后逐项查看新增内容；已有 AGENTS.md、steering 和提示词需要比较后合并，不能用模板版本替换。更新本地克隆也不会自动更新已经初始化的项目；以后升级骨架时仍要比较差异，只合并需要的变化。

通过标准：项目原有文件内容不变，缺失的骨架文件已经补入，新增和跳过的文件都经过检查。

8.2 全新项目的 steering

全新项目没有既有实现可审计，事实来源是你确认的决策和已有需求材料。有 PRD 时，把它作为主要输入，但仍要区分已经决定的内容和仍在讨论的设想；没有 PRD 时，通过对话把必要决策逐项定下来。

下文命令后的 fresh、establish、revise、audit、incremental、extend、new 和 sync 都是可选参数，不是必填语法。直接运行 /td-product、/td-tech 等裸命令时，提示词会根据目标文件的状态判断模式，并在写入前说明判断结果；正文显式写出参数，是为了标明这条流程预期采用的模式，也可以在状态已经明确时避免误判。

复制 template 后，CONTEXT.md 已经存在，因此术语命令预期走 extend。按下面 10 步依次做：

  1. 运行 /td-product fresh，确认产品定位和边界。
  2. 运行 /td-tech establish，确认技术栈与技术约束。
  3. 运行 /td-structure establish，确认目录职责和依赖方向。
  4. 运行 /td-testing establish，确认测试分层与标准。
  5. 运行 /td-api-standards，判断是否需要 API 规则；不需要时按后文处理占位骨架。
  6. 运行 /td-security fresh，建立安全红线。
  7. 运行 /td-glossary extend，在已有 CONTEXT.md 中播种术语。
  8. 人工收口 style.md 和 red-lines.md 的非安全部分。
  9. 运行 /td-agents sync，整理项目入口和路由。
  10. 检查占位符、文件冲突和失效链接，按本节通过标准验收。

这些提示词会先调查和提出修改方案，经过确认后才写入；明确不适用的分支可能直接退出。

命令产出与边界
/td-product fresh填写 product.md：定位、目标用户、系统边界、关键决策和阶段规划。未决定的内容留在待明确区域，不冒充事实。
/td-tech establish填写 tech.md：语言、框架、运行环境、核心组件和不应擅自替换的技术决定。
/td-structure establish填写 structure.md：目录职责、依赖方向和新代码的放置规则。
/td-testing establish填写 testing.md，逐项确认十类测试是否适用以及相应标准。
/td-api-standards先判断是否有对外 API；有才建立接口契约。
/td-security fresh只填写 red-lines.md 的安全段，规则适用于全部代码。
/td-glossary extend在 template 已放入的 CONTEXT.md 中播种术语，新词先标 待确认。如果项目没有这个文件，才改用 fresh。
/td-agents sync最后收紧 AGENTS.md，只保留每次会话需要且没有被常驻 steering 重复承载的内容，并路由到 steering 之外的深文档。

没有对外 API 时，/td-api-standards 不会修改文件。由于 template 已预置占位的 api-standards.md，确认它仍是未填写的原始骨架后，将它移除；以后需要 API 时再运行命令创建。不能保留占位文件，也不能误删已经填写的接口约定。

还有两类内容需要人工收口：style.md 没有专门提示词，red-lines.md 的架构、测试和部署段也不归 /td-security 管。用项目已经确认的样例和硬规则替换占位符；暂时没有真实内容时，删除不适用的占位项，不让 Agent 把模板文字当规则。

通过标准：适用的 steering 没有 {{...}} 占位符，文件之间没有冲突；不适用的可选 steering 不存在；AGENTS.md 的路由只指向真实存在的 steering 外文档。

8.3 存量项目的代码事实基线

存量项目先运行 /td-codebase-facts。它从源码和配置中提取可核实的技术事实，生成 docs/codebase-facts.md，并为每项事实标出处。无法确认的内容进入”需进一步确认”，不能补成事实。

这份基线记录代码现在是什么，不决定项目以后应该怎样。产品边界仍由你和可信需求材料确认；技术、结构和测试提示词用代码基线了解现状，再由你决定哪些做法保留、哪些需要迁移。

通过标准：关键模块、入口、实际使用的技术栈和外部依赖都有出处；无法证实的内容没有混进已确认区域。

8.4 存量项目的 steering 与技术债

存量项目不能整套判断为 establish 或 audit。逐个检查目标文件，再为每条命令指定模式；同一个项目里可以同时出现两种模式。

内容只有缺失文件或占位骨架已有真实、可信的内容
product.md/td-product fresh/td-product revise
tech.md/td-tech establish/td-tech audit
structure.md/td-structure establish/td-structure audit
testing.md/td-testing establish/td-testing audit
api-standards.md先判断是否需要 API；需要时 establish先判断当前是否仍有 API；需要时 audit
red-lines.md 安全段/td-security fresh/td-security incremental
CONTEXT.md文件不存在时 /td-glossary fresh；template 空骨架已经存在时用 extend/td-glossary extend
AGENTS.md文件不存在时 /td-agents newtemplate 骨架或真实文件已经存在时用 sync

顺序仍然是产品、技术与结构、测试与接口、安全与术语，最后收口 AGENTS.md。代码事实基线是技术现状的证据，不是产品目标或应有约定的替代品。Fresh/establish 用它避免误读现状；Revise/audit 用它检查已有规则是否漂移。

API、style 和非安全红线按全新项目中的规则收口。没有 API 时只移除未经填写的占位骨架；已有真实内容时先判断它是仍有效的契约还是需要迁移的历史材料，不能直接删除。

现有代码与应有约定冲突时，不把乱象抄成规则。/td-tech 和 /td-structure 会把确认要迁移的历史违规起草成技术债，再交给 /td-tech-debt register 登记。/td-security 对新增和修改的代码执行硬约束，遗留代码不为合规而整体重构；已经发现的高风险遗留问题登记为安全技术债。

完成 steering 后运行 /td-tech-debt analyze，补充能够通过现有规则定位的高价值缺口，例如关键路径没有测试、旧模块违反已经确认的边界。不要登记”遗留代码普遍缺测试”这类无法行动的概括，也不要回头给整个系统补齐说明文档。

如果项目暂时无法启动，而这个阻塞没有被 analyze 识别，单独运行 /td-tech-debt register，把报错、发生位置、已查证原因和目标状态写成一条具体技术债。只登记而未解除阻塞时，项目仍未通过初始化。

通过标准：steering 区分了当前事实和目标约定；每份文件按自身状态选择模式；历史违规进入技术债而不是规则；新旧代码的安全适用范围写清；技术债条目能指向具体位置和目标状态。

8.5 初始化 spec-kit 并安装扩展

新项目和存量项目都在 steering 就位后初始化 spec-kit。下面的命令已在本机 specify 1.2.2、Kiro CLI integration 下实跑。

项目目录已经有文件，--force 会允许合并或覆盖。运行前先确认现有改动可恢复，运行后检查实际新增和修改的文件：

specify init . --integration kiro-cli --force
specify extension add bug
specify extension add assess

integration 在 specify init 阶段确定；extension add 不接受 --integration 参数。扩展必须在已经初始化的 Spec Kit 项目中安装。

通过标准：

specify extension list

输出中能看到 bug 和 assess；项目中存在 .specify/，Kiro 的命令目录中存在 /speckit.* 对应文件。按官方 integration 说明，重新进入项目会话后即可调用 /speckit.constitution、/speckit.specify 以及两个扩展提供的命令。

8.6 生成 constitution

template 已预置一条通用纪律「规格写在决策层，模糊不往下漏」（命名决策而非写实现、需实验的参数先做 spike、每个任务绑可独立验证的结果、实质歧义先澄清再往下）。specify init 不会覆盖已存在的 constitution，这条预置内容会被保留。

运行 /speckit.constitution，明确要求它以已经确认的 steering 为依据，在预置的通用纪律之上补写项目真正要遵守的原则（如语言偏好、领域硬约束），不要删掉预置那条，也不为填满模板增加空规则。

通过标准：constitution 没有模板占位符；预置的通用纪律仍在；每条新增原则能追溯到已经确认的项目约束；constitution 与 steering 没有冲突。发现重复或冲突时，先确定哪一份是权威来源，再修改，不同时保留两种口径。

8.7 初始化完成判据

全新项目完成初始化，要同时满足：

存量项目还要满足：

8.8 第一次练习

初始化完成后，先用一个结果已知、可以撤回的小任务校准流程，不直接拿高风险需求试运行。

存量项目可以复现自己过去手工完成的一次提交：只给 Agent 当时的需求，不给它看原实现，让它走一遍流程，再比较行为、测试和改动范围。已有答案可以快速暴露 steering 漏加载、流程卡点和实现偏航。

全新项目没有历史提交时，先写下一个小任务的可观察结果、输入输出样例和通过命令，再让 Agent 完成。选择可以丢弃或回滚的任务，避免为了练习留下无用代码。

练习通过的标准不是”Agent 做完了”，而是预先写下的结果成立、验证命令通过、改动范围合理，并且暴露的问题已经回到对应的 steering 或流程中处理。

本章小结

项目初始化先获取方法骨架，已有文件默认不覆盖。全新项目向前建立 steering；存量项目先建代码事实基线，再按每份文件是否已有可信内容分别选择 establish 或 audit，并把历史违规交给技术债。两条路都要初始化 spec-kit、安装扩展、生成 constitution，最后用一个结果已知且可撤回的小任务校准流程。

参考与出处