tech-spec

技术规格 Skill

触发条件

• 关键词：tech spec、technical specification、spec review、review spec、feature design

不适用场景

• 创建请求文档（使用 /create-request）
• 代码实现（使用 feature-dev）
• 架构咨询（使用 /codex-architect）

命令

命令	用途	适用时机
/tech-spec	创建或更新技术规格	根据文件系统状态自动检测创建或更新
/deep-analyze	深入分析规格 + 路线图	初步构想之后
/review-spec	审核技术规格	确认规格时

上下文感知模式（Upsert）

在未提供完整需求描述的情况下调用时，此 Skill 会根据 references/native-feature-resolution.md 中的级联规则自动检测目标功能——该文件是此 Skill 自身的参考资料，特意不包含命令。

此 Skill 授予 Bash(git:*)，但不授予 Bash(node:*)，因此解析器脚本不是它可以运行的命令；它也不会链接到介绍该脚本的共享参考资料，因为在此 Skill 可访问的依赖图中放入无法运行的命令文件才是缺陷，而不是缺少相应注释。级联规则只需要 $ARGUMENTS、git branch --show-current、git diff --name-only HEAD，以及对 docs/features/* 执行 Glob。但这些操作不会生成四组文档源集合或 scan_error——此 Skill 两者都不使用。需要这些集合的 Skill（/architecture、/tech-brief、/runbook、/ask）会授予 Bash(node:*)，并自行读取共享参考资料。

仍需执行规范的发现流程；只测试一个字面路径并不能完成该流程。 规格可能已拆分到文件夹中，也可能使用了变体名称，而本仓库中的 docs/features/auto-loop-evolution/2-tech-spec/2-tech-spec.md 就是实际示例。使用 Glob 在 docs/features/<key>/ 下按以下顺序解析——以第一个命中项为准：

#	Glob	含义
1	docs/features/<key>/2-tech-spec.md	未拆分的规范规格
2	docs/features/<key>/2-tech-spec/2-tech-spec.md	已拆分的规格——文件夹保留生命周期前缀，主文件保留规范文件名（@rules/docs-numbering.md § Size Limit）
3	docs/features/<key>/2-tech-spec*.md，排除任何匹配 -fp-brief.md 或 -tech-brief.md 的命中项	变体（2-tech-spec-v2.md）。排除这两个后缀，是因为它们不是规格：scripts/config/doc-taxonomy.json 出于相同原因包含相同的 exclude_pattern，而 docs/features/seek-verdict/ 中就有一个实际的 2-tech-spec-fp-brief.md，否则此 glob 会将其作为规范规格返回。剩余命中项达到两个或更多即为歧义，而非匹配——应报告并采用 Need Human 退出路径，不要自行选择

需求文档（1-requirements.md）使用相同的三种方式解析，但不排除后缀——doc-taxonomy.json 仅在 tech-spec 类型上设置了 exclude_pattern；在此处将其复制到需求文档上会使此 Skill 与分类器不一致，而非保持一致。发生错误的 Glob，或解析置信度为 low 但没有匹配项的 <key>，并不等同于“没有规格”——应说明具体是哪种情况；不要悄然转入创建模式。

第四种查找用于解析意图产物：功能目录中名称必须恰为 intent-<key>.md——必须是精确名称，绝不能通过通配符挑选。单独执行 Glob intent-*.md 只用于发现无关文件或键名错误的文件（应报告，绝不能将其用作意图文件）。

文件系统状态	操作
规范文件的规范发现结果恰好为一个	更新模式：读取该文件——使用发现返回的路径，而不是字面路径 2-tech-spec.md ——研究上次更新后代码的变更，增量更新有变动的章节
三个 glob 均无匹配结果	创建模式：使用模板在 docs/features/<key>/2-tech-spec.md 生成新规范
Glob 3 返回两个或更多结果	门槛：需要人工处理——规范文件不明确，列出候选项
未能确定功能	门槛：需要人工处理

在创建模式下，如果不存在 intent-<key>.md，则先使用 /req-analyze 随附的意图模板编写该文件——从需求澄清步骤提炼而来（仅包含约束，≤60 行）——然后再编写规范。如果文件已存在，则在设计前先阅读。

在更新模式下，重点关注近期代码变更影响的章节（使用 git diff 确定）。保留未变更的章节。如果不存在 intent-<key>.md，则完全按照创建模式创建（如果存在 1-requirements.md，则依据其 §§ 1–2；否则依据规范中的需求摘要）——这样 next-step 建议才能适用于规范早于意图机制的功能。如果文件已存在，则先阅读：任何与 INV-* 或非目标相矛盾的规范章节，都是需要向用户指出的冲突，不得掩盖——也绝不能改写意图来匹配规范；修订意图属于人工重新决策。

工作流

sequenceDiagram
    participant A as Analyst
    participant C as Codebase
    participant D as Document

    A->>A: 1. Requirement clarification
    A->>C: 2. Code research
    C-->>A: Related modules
    A->>A: 3. Solution design
    A->>A: 4. Risk assessment
    A->>A: 5. Work breakdown
    A->>D: 6. Output document

规范结构

1. 需求摘要（问题 + 目标 + 范围）
2. 现有代码分析
3. 技术方案（架构 + 数据模型 + API + 核心逻辑）
4. 风险和依赖项
5. 工作拆分
6. 测试策略
7. 未决问题

编写时预算

规范在编写时保持简短，成本最低。事后强行控制长度意味着必须拆分或删减，两者都会增加一轮评审；按预算编写本可避免这种情况。

行数（wc -l）	编写时要求
≤ 300	目标值。尽量控制在此范围内
301–400	可接受——添加更多内容前先精简
> 400	在文档本身说明连贯性例外的原因，否则在写入前删减或拆分。“空间不够”不构成例外

例外说明应在规范中用一句话解释，为什么这些章节合在一起构成一个论述，分开后反而不易阅读。若未说明，超过 400 行的规范即超出预算；@rules/docs-numbering.md § Size Limit 将按此处理——先删减，再合并，最后拆分。

应省略的内容：已考虑但拒绝的备选方案（每项用一行说明，不单独成章）、设计变更过程的历史（应记录在记录文档中），以及代码能比文字更精确地表达的内容。

在更新模式下，代码已使其过时的章节应直接删去，而不是添加注释。原地重写可使规范保持当前权威性；添加“此前……”之类的说明会将其变成记录文档，但它并非记录文档。

输出

带编号的技术规范文档，包含以下章节：概览、需求、架构、实施计划、工作拆分、测试策略、未决问题。

验证

• 方案涵盖所有需求要点
• 架构图使用 Mermaid
• 风险均有缓解策略
• 工作可拆分为可跟踪的事项
• 符合编写时预算，或已在文档中说明连贯性例外

参考

• references/template.md - 规范模板 + 评审维度

文件位置

docs/features/{feature}/
├── 2-tech-spec.md    # Technical spec (numbered per docs-numbering rule)
├── requests/         # Request documents
└── README.md         # Feature description

示例

Input: /tech-spec "Implement user asset snapshot feature"
Action: Requirement clarification -> Code research -> Solution design -> Output document

Input: /review-spec docs/features/xxx/2-tech-spec.md
Action: Read -> Research -> Review -> Output report + Gate