spec-init

帮助项目保留足以指导开发的有效约定，让文档投入与当前任务的风险相称。 用户要求实施时，推进到实现和验证；用户只要求分析或方案时，交付分析或方案。

先确定本轮需要多少文档

请求	最小准备	文档投入
小修复、局部调整、普通重构	问题、范围、验证办法已明确	不新建需求、计划或 change；已有说明失真时原位更新
普通功能	目标、非目标、验收条件清楚	更新已有功能文档；独立新主题才新建一份
跨会话或多人实施	上述内容和剩余工作可交接	按需保留一份活动计划，同一目标继续更新原计划
权限、数据迁移、公共契约、不可逆操作等高风险变化	关键决策、失败路径、兼容和恢复办法清楚	在相关文档补必要设计与验证；重大取舍才独立记录
明确要求完整需求或设计	覆盖用户指定范围	按需要展开角色、异常流、契约和质量目标，不自动铺满目录

小改动也可能高风险，按影响判断，不按代码行数判断。 若没有需要改变的约定，零文档改动是正常结果。

执行流程

1. 定向读取。 先看项目指令、README、相关代码与测试；有文档入口就据此定位本任务的有效约定。没有入口时按功能搜索，确认文件状态，不补全项目文档目录。参考资料按下方触发条件读取，不默认全部加载。
2. 明确必要信息。 回答“要改成什么、影响什么、如何验证”。从现有代码、测试和已确认决策解决常规选择；只澄清会实质影响范围、安全、数据或兼容性的未知项。未确定方案不能写成已确认事实。
3. 进入实施。 上述信息充分且无关键阻塞就开工。缺编号、历史索引、无关文档或一般格式不阻塞实现。源码、测试、配置、迁移与受影响文档形成一个完整批次，再统一执行必要检查。
4. 校准结果。 核实行为与约定，记录实际验证和剩余风险；仅同步本次主题的权威文档、相关引用和实施状态。未跑测试、未上线或未完成迁移不能写成通过或已交付。

停止扩写的条件：当前任务能够安全实施、能够验收，必要约定已经明确。 不要为“更完整”补无关背景、示例、测试矩阵或未来功能；不要在每个局部修改后扫描所有文档。

需求文档是唯一真源

每个主题指定一份权威文档，保存最新确认的需求、边界和验收；沿用原路径，由已有文档入口指向它。唯一真源不等于全项目只能有一个文件。 用户确认需求变化后，立即原位替换权威文档中的旧要求与验收，不只追加补充说明，不等实现完成才更新，也不另建“新版需求”。尚未确认的提议不能替换已确认需求。 需求与交付状态分开：新需求立即生效，未完成的实现标注“待实施”；必要时注明当前实现差距，不能把旧实现描述成仍然有效的要求，也不能把新需求写成已交付。

围绕本次变更的主题、术语和旧规则，定向检查相关现行文档，包括 README、AGENTS、设计和计划。权威文档以外的需求和验收副本改为链接，不重新抄写新规则；设计只记录实现方案或差距。修订只改受影响内容，保留原有命令和其他无关信息，不能只改一份而让另一份旧规则继续生效。 活动计划只记实施动作、进度和阻塞，并引用权威需求，不再保存另一套需求定义。需求变化时撤下失效待办，完成或被替代后移出活动入口。 历史仅用于追溯，由历史正文或入口明确其已失效及现行文档，不作为执行依据；普通编辑历史交给 Git。无需重写所有历史或全仓库扫文档。

用户最新明确决定用于更新权威文档；代码和测试用于核实实现状态，不能覆盖已确认需求。若无法判定哪份文档权威或哪项决定已确认，只澄清影响本次工作的关键冲突。 交付前确认本次主题没有冲突的现行说法，验收与最新需求一致，实施状态真实。不要用“已归档”或“已更新计划”代替纠正仍生效的旧规则。

保留验证，减少重复登记

验收条件直接关联真实测试路径、命令或人工验收步骤。已有 API schema、配置说明和测试资产优先引用，不重复转抄。 日常开发不强制 FR / DES / TEST / T 编号或手工覆盖矩阵；项目明确需要追踪体系时保留已有 ID，只维护本任务涉及的关系。 测试策略、测试标准、用例、回归和 fixtures 不必拆成七份文档。高风险变化仍要覆盖失败、幂等或恢复路径，并如实说明未验证边界。 完成标准是目标满足、必要检查完成或限制已说明、受影响约定准确；文档数量不是门禁。

现有项目与辅助脚本

更新 Skill 不等于项目里旧的 AGENTS 或规则已经迁移。存在旧的全量文档门禁时，先辨明规则来源；仅在获准的迁移范围内改写，不能静默忽略项目规则。 迁移保持原路径和用户内容，不自动删除旧文档、清空 active、移动目录或覆盖整份 AGENTS。只替换已确认来自旧 Skill 的流程片段，保留项目特有约束。

只有用户需要空项目文档骨架时才运行 scripts/spec-init.sh；默认仅生成 README、简短 AGENTS 和文档入口。 脚手架不理解业务，跑完不能声称 spec 完成。现有项目优先人工定向更新，不用脚手架强制覆盖来迁移规则。 不要创建空需求、示例 change、规则大全或未使用目录。

按需参考

• 需要决定文档归属或迁移旧流程时，读 文档边界与迁移。
• 用户需要具体写法或需求反转示例时，读 简短示例。
• 用户明确要求完整设计或本轮有高风险变化时，读 设计与风险。

交付

说明实现或规范改变了什么、如何验证，以及剩余限制。没有改文档无需补“无变化”记录。 不以补齐规范代替已获授权的实施；不把未完成实现标成完成。