用途
spec-extract 用于把代码变更及其背后的对话理由,整理成模块化的规格包与决策记录,便于人工评审和自动化验证。它强调两类事实来源:代码与差异是“发生了什么”的依据,对话记录是“为什么这样”的依据,不凭空编造结论。
主要能力
- 按变更更新受影响的规格包 docs/specs/<layer>/<pack>.md,内容包括递增版本号、Intent、Invariants、Acceptance Criteria(使用 kebab-slug 标识)、精简的 Implementation Notes(仅记录关键的 SDK/平台陷阱)、Verification 与 Open Callouts。
- 以追加方式维护 docs/decisions.jsonl,记录提炼后的决策(D-1..N),含类型、结果、作者署名、所属规格包、摘要、处理结论及按时间顺序的第一人称评论。
- 标准保护:正常运行时不编辑 docs/standards/*.md;若本地代码有意偏离继承的标准规则,需在 docs/decisions.jsonl 记录人工决策,并在所属规格包中声明 overrides 块,或改用 spec-refactor 显式拉取、更新、提升标准。
- 提供校验脚本 scripts/check-specs.ts,用于初始化 docs 结构、解析生效规则集以及最终校验 schema、slug 唯一性、override 权限与索引链接。
使用方式
- 引导与读取事实来源:若仓库中缺少 docs/INDEX.md 或 docs/decisions.jsonl,先以非破坏方式初始化: node --experimental-strip-types <this-skill-dir>/scripts/check-specs.ts --root "$PWD" --init 随后检查 git status 与 git diff(功能分支上用 git diff <base>..HEAD;堆叠分支逐层与直接父分支比较);若 Git 未初始化或无提交,则直接检查项目树、配置、测试与实现文件。同时读取当前对话历史及磁盘上的会话记录,读取 docs/INDEX.md、受影响的规格包、docs/decisions.jsonl 最近内容,并解析生效规则集: node --experimental-strip-types <this-skill-dir>/scripts/check-specs.ts --root "$PWD" --effective --json 将变更文件映射到已有的概念规格包,不创建冗余包或重新分层,除非变更引入了真正不同的领域边界(结构性拆分或合并应使用 spec-refactor)。
- 提炼决策:依据 references/decisions.md 的提炼、署名与线索规则,把选择、有意为之的特殊做法、已接受风险、非显而易见的已修缺陷、延后跟进项、撤回的顾虑、已答复或待答复的问题等追加到 docs/decisions.jsonl;仅把构建、配置、运行或避免静默回归所必需的关键操作/SDK 陷阱写入所属规格包的 Implementation Notes。
- 更新所属规格包:Intent 用 1–3 句平实语言描述行为目的,避免内部类/文件/表名;Invariants 与 Acceptance Criteria 依据 references/acceptance-criteria.md 执行各项门槛,每包保留 2–5 条聚焦标准并使用稳定的 kebab-case slug,行为未变则保留原有 slug,新增标准不得挤掉其他包的标准;Verification 保持简洁可执行(只读状态/数据库查询、CLI 检查、UI 检查或隔离的 mktemp -d 演练);Implementation Notes 简明记录确切的协议/配置契约与 SDK 陷阱;Open Callouts 仅标记真正未决或矛盾的事项。
- 交互式评审:在写入前预览时,展示受影响的规格包、Intent、Acceptance Criteria(注明每个 slug 独立验证)、Open Callouts、所需的标准 Overrides 与决策预览,并询问:“Anything to add, remove, or tighten before I persist these updates to docs?”;若用户明确要求立即写入,则直接写入并注明已预先授权确认。
- 持久化与校验:只更新受影响的规格包文件(递增整数版本),向 docs/decisions.jsonl 追加新行并逐字保留已有行;若新增规格包,更新 docs/INDEX.md 使每个包都有相对 Markdown 链接;最后运行: node --experimental-strip-types <this-skill-dir>/scripts/check-specs.ts --root "$PWD" 注意:任何规则文本发生变更后,都需由 verify-deploy 重新验证,docs/runs/ 中的既往豁免不随规则文本修改而延续。
适用场景
适用于需要把代码变更的意图、验收标准与决策沉淀为可评审、可验证规格的仓库,尤其是希望规格包保持最小化、可冷重建,并区分“做了什么”与“为什么”的团队工作流。
限制
该技能依赖 Git 差异与对话记录作为事实来源;缺少这些输入时只能直接检查项目文件。正常运行不修改 docs/standards/*.md,偏离标准需通过决策记录与 overrides 声明处理。规则文本变更后需重新验证,既往豁免不延续。