spec-kit-plan

根据功能规格制定技术实施计划。

输入：可选指定变更名称。如果省略，请根据上下文推断或询问。 用户添加的其他内容（如首选技术栈、约束）均作为计划的输入。

步骤

1. 选择变更并加载资料

   加载 specs/changes/<name>/spec.md。如果文件不存在，请提示先使用 spec-kit-specify 技能。

   同时加载 FRAMEWORK.md（如果存在，还要加载 FRAMEWORK.local.md）、其中链接的已启用标准相关能力文档、与变更领域相关的 specs/features/ 文档，以及 specs/decisions/ 中对其有约束的决策记录。

2. 调查未知事项

   如果规格中包含未解决的 [NEEDS CLARIFICATION] 标记，请暂停，并建议先使用 spec-kit-clarify 技能，除非用户明确表示希望继续。

   列出计划本身的未知事项——需要选择的依赖项、集成模式、现有代码的行为等——并通过阅读代码或依赖项文档逐一确定。 在 ## Decisions & Rationale 下记录每项已确定的未知事项及考虑过的备选方案。

3. 编写 specs/changes/<name>/plan.md

   结构：

   # Plan: <Feature Name>
   
   ## Technical Context
   <Language and versions, main dependencies, storage, testing tools, target platform, constraints. Only what the code or the user establishes.>
   
   ## Architecture
   <Bounded context, layers affected, dependency direction. Must comply with FRAMEWORK.md dependency rule.>
   
   ## Data Models
   <Entities, value objects, aggregates. Identity vs. structural equality. Invariants. Field constraints: required or optional, limits, allowed values, validation rules.>
   
   ## Interface Contracts
   <Ports, use case signatures, domain events, and what the project exposes to users or other systems (commands, endpoints, public APIs, messages). Technology-agnostic where the layer requires it.>
   
   ## Implementation Phases
   1. <Phase name> — <what it establishes>
   2. ...
   
   ## Decisions & Rationale
   | Decision | Rationale | Alternatives Considered |
   |----------|-----------|------------------------|
   
   ## Exceptions
   | Rule | Trade-off | Simpler alternative rejected | Verification |
   |------|-----------|------------------------------|--------------|
   
   ## Record Search
   | Record | Search | Disposition |
   |--------|--------|-------------|
   
   ## Validation Scenarios
   <Runnable scenarios that prove the feature works end to end: prerequisites, the commands to run, expected outcomes.>
   
   ## Constraints & Risks
   <Known constraints, open technical risks.>
   

   规则：

   • 依赖方向必须是 infrastructure -> application -> domain。绝不可反向依赖。
   • 影响业务行为的外部依赖必须置于端口之后。
   • 仓储按聚合根划分，而不是按表划分。
   • 领域层或应用层设计中不得出现框架名称。
   • 上下文之间必须通过共享内核中的契约或领域事件交互，绝不可相互导入（包括导入其他上下文的应用服务）。
   • 对约束性规则的例外必须在 ## Exceptions 下记录，并填写全部四列；否则不得记录。没有例外时填写 None.。 spec-kit-analyse 接受已记录且权衡合理、验证方式存在的例外；缺少任一列则视为违规。
   • ## Record Search 必须列出变更会使其内容失实的所有现行规格、决策记录和文档。通过搜索 specs/features/、specs/decisions/ 和项目文档中与变更相关的术语来查找——既要搜索概念词语，也要搜索其拼写形式，因为仅搜索路径会漏掉写着“位于功能规格旁边”的页面，而这种表述说明了文档位置。 每行都要说明查找方式和处理方式：由变更更新（以及如何更新），或不受影响（以及原因）。 如果变更推翻某项决策记录，必须明确说明并引用用户的决定；计划不得自行推翻已记录的决策。 如果没有任何内容受影响，请填写 None found.，并注明所做的搜索。
   • ## Validation Scenarios 用于指导验证，而非描述实现：链接到契约和数据模型，不要重复其内容；不得包含实现代码、迁移或完整测试套件。

4. 根据现有实际内容检查计划

   如果变更会修改现有内容，请先阅读该内容，再进行描述。 计划具有权威性，因此如果不在此处检查，以下错误都可能在评审中遗留下来：

   • 阈值和比较。 引用代码中的运算符和常量，不要换一种说法转述。 如果计划写着“达到或超过上限”，而代码测试的是 > limit，就会让实施者去修改正常工作的代码，或编写一项按计划中规则判定的测试。
   • 需求暗中依赖的配置。 在将某项记录为范围外之前，检查需求是否需要它：权限、构建或部署设置、缓存键、检出深度。
   • 代码中的数量、枚举和位置。 使用搜索从代码中推导集合（“执行 X 的文件”），不要依据示例推断，并记录搜索方式，以便实施者重复操作。 用可搜索的内容来指明代码位置，例如函数、类型或具有辨识度的字符串；绝不要使用行号，因为其他地方的编辑会导致行号变化。
   • 变更所影响内容的读取方，而不仅是生成方。 在确定变更所涉及的标识符、消息、格式、标志或端点的形式之前，按代码中的拼写在整个代码库中搜索所有读取方，包括代码和测试，并记录搜索方式。 如果代码的其他部分已经会解析某段文本，那么它就是一种格式：只有找到并检查解析器后，才能安全地向其中添加字段或标记；而解析器通常不在正在编辑的文件中。 列出变更范围之外所有会读取变更内容的测试名称，以便 spec-kit-tasks 能为其安排任务：否则变更会让这些测试过时。
   • 特殊情况必须检查每一步读取其所变更事实的流程， 而不仅是引入该事实的步骤，并在计划中说明每一步现在会如何处理。
   • 出现相同结果，并不能证明所有生成方都处理了新情况。 如果某个结果（状态、错误、停止）可能由多个触发条件产生，请逐一检查并列出每个生成方；而即使某个使用方会通用地处理新值，它旁边仍可能输出一句对新情况不属实的硬编码文本。
   • 规则的例外必须指出该规则的每一处重述。 一条规则通常会在多个地方表述——标准、技能、文档——而这些重述之处都必须修改以纳入例外；请搜索该规则的措辞。
   • 安全检查的豁免应以确保安全的状态为依据， 并在豁免适用之处观察该状态；绝不能以可能在该状态结束后仍然存在的记录为依据。
   • 承诺的提交必须可以分开。 在规划将一个文件中的两种行为拆成两个提交之前，先检查它们能否清晰分离；如果它们交织在同一个函数中，就规划一个同时说明两者的提交。
   • 项目自身的模板决定计划的章节。 如果 FRAMEWORK.local.md 或项目文档要求计划包含更多章节，就添加这些章节。

5. 宪章检查

   在完成之前，以及设计完成之后，再次确认计划没有违反 FRAMEWORK.md 中任何不可协商的规则。 发现违规时，必须在计划中修正，或将其记录为 ## Exceptions 下的例外；不得不作说明。

输出

编写计划后：

• 确认文件位置。
• 着重说明值得用户关注的架构决策、例外和受影响记录。
• 下一步：“使用 spec-kit-tasks 技能生成任务列表。”也可以先使用 spec-kit-checklist 技能，对某个领域（安全、用户体验、API）的需求进行审查。

护栏

• 不生成代码——只编写计划。
• 如果规范中有影响架构、尚未解决的澄清事项，应明确指出，不要自行猜测。
• 优先保护领域模型；围绕它调整基础设施。
• 绝不要改变规范的要求；计划无法满足的要求必须交由用户处理。