# Spec Init

> 按风险编写和维护项目规范，保留有效功能约定与关键决策。用于明确要求整理 spec、补齐项目文档、更新需求设计或迁移旧文档流程；普通代码修改不自动启动完整文档流程。

- Skill: `legeling/spec-init-2` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add legeling/spec-init-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/legeling/spec-init-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: legeling (https://skillmd.com/u/legeling)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/legeling/spec-init-2

---


# 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、规则大全或未使用目录。

## 按需参考

- 需要决定文档归属或迁移旧流程时，读 [文档边界与迁移](references/doc-boundaries.md)。
- 用户需要具体写法或需求反转示例时，读 [简短示例](references/example-idea-to-docs.md)。
- 用户明确要求完整设计或本轮有高风险变化时，读 [设计与风险](references/design-and-risk.md)。

## 交付

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