Menu
Use when 用户调用 /spec-update, or 工作中沉淀出新 convention / 接口 contract / 模式需要落到 .claude/code-specs/, or execute 末尾终审（workflow-execute Step 7）建议沉淀 code-spec。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when 用户调用 /design-plan, or 需要为复杂跨服务需求(多服务改动 / 数据库 DDL / 新增对外接口 / 架构调整)产出可评审的技术方案文档,典型用户是技术主管 / 资深研发。简单单服务改动走 /workflow-spec,Bug 修复走 /fix-bug。
Use when asked to review a diff, do a pre-commit code review, or review staged/branch changes. Supports staged diffs, branch diffs, and session mode that reviews only files edited in the current conversation context.
Use when 用户调用 /plan-archive, or 三阶段研发流程的阶段三:在所有模块研发上线后,根据实际代码改动回写阶段一技术方案 + 项目级架构文档(docs/architecture / docs/contracts / docs/assets/概要设计 等)。
Use when 用户说「快速规划」「轻规划」「不走 workflow」「plan 一下」「quick plan」, or 需求清晰、作用域明确、可一次性规划完成的简单到中等任务。复杂项目(跨 module / 新子系统 / 需追溯)或需要正式需求文档 / PRD 请用 /workflow-spec。
Use when 用户调用 /spec-bootstrap, or 项目尚未建立 .claude/code-specs/ 骨架且需要初始化 code-specs 体系。
Use when 用户说「补充前端设计」「UX 深化」「页面 flowchart」「布局提取」「补 §4.4」, or workflow-spec Step 5 确认需要前端设计深化, or 已有 Spec 需要补充 User Flow / Page Hierarchy / Layout Anchors。
| name | spec-update |
| description | Use when 用户调用 /spec-update, or 工作中沉淀出新 convention / 接口 contract / 模式需要落到 .claude/code-specs/, or execute 末尾终审（workflow-execute Step 7）建议沉淀 code-spec。 |
显式、用户驱动的 code-specs 沉淀入口，走交互式模式引导用户落笔。
{pkg}/{layer}/*.md 相似主题，提示追加还是新建> Type: X 注释"| Guide | Description | Status |，不加 Type 列、不做 From→To 日志.template-hashes.json.version 落后于最新 manifest 时，走 planMigration / applyMigration 做显式迁移。支持链式（v5.1 → v5.2 → v5.3 连跳）与 partial failure 恢复路径。不做自动触发，必须用户在 /spec-update 时确认。/spec-review + 全仓 markdown 链接校验，旧引用由人工处理。| 触发 | 示例 | 目标 |
|---|---|---|
| 实现了新特性 | "新加了 template 下载" | {pkg}/{layer}/{topic}.md（7 段 code-spec） |
| 跨层协作决策 | "前后端字段命名映射表" | 对应 code-spec 的 Contracts + guides 的指针 |
| 修复了 bug | "错误处理的微妙漏洞" | 对应 code-spec 的 Validation & Error Matrix + Wrong vs Correct |
| 发现了新模式 | "更好的组织方式" | {pkg}/{layer}/{topic}.md（7 段） |
| 碰到 gotcha | "X 必须先于 Y" | 若是"怎么写"→ code-spec；若是"写之前想什么"→ guides |
| 建立了convention | "命名模式统一" | {pkg}/{layer}/conventions.md（7 段） |
| 类型 | 位置 | 模板 | 适用内容 |
|---|---|---|---|
| Convention | {pkg}/{layer}/*.md | convention-template.md（必备 4 段 + 可选扩展） | 代码风格、目录convention、命名规则、组件/module写法 |
| Contract | {pkg}/{layer}/*.md | code-spec-template.md（7 段） | API 请求/响应字段、DB schema、错误码矩阵、字段级contract |
| Guide | guides/*.md | guide-template.md | 思考清单（写代码前想什么），指向 convention/contract 的指针，不复述具体规则 |
问自己：
不确定时优先 convention（轻量）；只有真正涉及严格字段contract才升到 contract。
基于 core/specs/spec-templates/convention-template.md：
必备段（缺任一段 → /spec-review 标记 missing）：
可选扩展（按需加）：Patterns / Examples / Quick Reference / Reference Tables / Strategy / Checklist
基于 core/specs/spec-templates/code-spec-template.md，7 段结构保持不变：Scope / Signatures / Contracts / Validation & Error Matrix / Good-Base-Bad Cases / Tests Required / Wrong vs Correct。
仅在涉及严格 API/DB/字段contract时升级到 contract；日常convention都走 convention。
在进入 Step 1 的"基础/深度更新分流"前，先检查 code-specs 的 template 版本：
.claude/code-specs/.template-hashes.json 的 version 与 migrationStatusmigrationStatus === 'failed_partial' → 立即终止，输出恢复路径提示：
⚠️ 检测到上次模板迁移失败并停在 {rollbackKey} 的第 {step} 步。
请先：
1. 查看 .claude/code-specs/.migration-rollback.json
2. 运行 `git diff .claude/code-specs/` 检查已修改文件
3. 手工回退 / 补齐改动后，重跑 `/spec-update` 继续
pre-5.2core/specs/spec-templates/manifests/ 的最新 manifest 版本：
recommendMigrate === true → 调用 planMigration({ fromVersion, toVersion, projectRoot })
terminated === true → 展示 reason（unknown_baseline / manifest_not_published / chain_not_reachable），要求用户手工指定基准或更新 agent-workflow 后重跑chain / apply 条数 / skip 条数 / conflicts 条数conflicts 非空 → 默认终止（不迁移），要求用户手工清理冲突后重跑1. 立即升级 / 2. 跳过本次 / 3. 查看 changelog / 4. 终止
applyMigration(plan, { projectRoot })
status === 'ok' → 把 .template-hashes.json.version 更新到目标版本，继续 Step 1status === 'failed_partial' → 把 .template-hashes.json.migrationStatus 写为 failed_partial、version 不改，输出 rollback 路径，终止notes / breaking / migrations 摘要后再问一次rename / rename-section 成功后不自动修 markdown 链接引用；用户在迁移完成的 summary 里会看到提示"请跑一次 /spec-review + 全仓链接校验，旧引用由人工处理"先问一次：
| 路径 | 适用场景 | workflow |
|---|---|---|
| 基础更新 | 补一条 Rule / 加一个 Mistake / 追加一段代码 | 直接追加，只检查"有代码示例 + 有 Why + 放对文件" |
| 深度更新 | 新主题 / 重写已有主题 / 补字段contract | 走完整 checklist：Overview/Rules/DO-DONT/Common Mistakes 都要过 |
学到了什么？（一句话）
语义类别（6 类，仅用于建议模板类型与正文注释，不进 index 表头，不进 frontmatter）：
| 类别 | 建议模板 |
|---|---|
| Design Decision | convention 或追加到现有 Overview |
| Convention | convention（Rules 段） |
| Pattern | convention + 可选 Patterns 扩展块 |
| Forbidden | convention（DO/DON'T 的 DON'T 侧） |
| Common Mistake | convention（Common Mistakes 段） |
| Gotcha | convention Rules 首行 > Gotcha: ... 注释 |
| （字段contract） | contract 模板（7 段） |
位置：哪个 package / layer？（单包项目默认推断，monorepo 列出可选）
目标文件（Step 3 fuzzy 匹配后确认）
写入前扫描范围 = 同层 {pkg}/{layer}/*.md（topic 文件）+ 同层 index.md + 兄弟 convention 文件：
existing.md / 2. 新建？"（可回数字）index.md 或兄弟 convention 文件已有内容在讲同一件事 → 提示"已有相近内容，改为指针而非复制？"guides/，各包改指针？"directory-structure.md / component-guidelines.md 是否已画过同一棵树 → 命中则提示"目录树留一处，另一处改指针"> Type: {类别} 注释，便于阅读识别spec_kind{pkg}/{layer}/index.md 的 Guidelines Index 表：
| name](<filename>.md) | 描述 | Draft |（去掉空格与占位符后即可直接使用）Not Started / Draft / Donelocal.md 的 Changelog 追加一行.template-hashes.json）index.md / 兄弟 convention 文件重复（重复改指针）{pkg}/{layer}/index.md 的 Status 已更新/spec-update # 交互式走完整流程
/spec-bootstrap 确保骨架存在/spec-review 跑一次 7 段 lint，确认所有段都填充完整