第 22 天：沉淀 spec 模板——提炼个人模板，设计自己项目的 .ai/ 目录骨架

SDD + Harness 四周学习计划 · Week 4 · Day 22（全计划第 22 课）

今日主题：沉淀 spec 模板：提炼个人模板，设计自己项目的 .ai/ 目录骨架

建议用时：60–90 分钟｜前置：Day 5 的 spec v2 + Day 9 的 .ai/ 目录笔记

输出物：个人 spec 模板 v1（可直接复制的 Markdown）+ 你项目的 .ai/ 目录骨架图

0. 一句话剧透

前三周你一直在”写 spec、配 harness、跑流程”，但每次都是临时起意。今天打开 Week 4「沉淀输出」：把你散落各处的经验压成模板和骨架——spec 模板让下一次写 spec 从”从零开始”变成”填空”；.ai/ 目录骨架让新项目三分钟就能立起 SDD+Harness 的架子。今天是全计划第一次”造工具”，而不是”用工具”。

Week 4 的逻辑一句话：Day 22–23 造模板和工具 → Day 24–25 对齐团队规范 → Day 26–27 拿大作业验证 → Day 28 打包输出。

1. 今日目标（学完你能做到）

能用一句话说出 Week 4「沉淀输出」在整份计划中的位置
能把 Day 5 的七要素 + Day 6 的 delta spec 标记 + Day 15 的四类契约，融合成你自己的 spec 模板 v1
能背出 .ai/ 目录里至少 6 个关键文件/子目录各自干什么
能为自己的项目画出一份 .ai/ 目录骨架（裁剪版，不是照抄）
完成动手练：spec 模板 v1 + 目录骨架存盘

对应计划评估标准第 6 条：已沉淀个人 spec 模板与团队工作流，能输出给他人复用。

2. 学习动线

步骤	内容	用时
1	回顾 Week 1–3：Day 1–21 一句话串讲	10 分钟
2	精读「4」：spec 模板的构成逻辑 + 直接复制模板骨架	20 分钟
3	精读「5」：.ai/ 目录骨架（sdd-harness 结构 + 裁剪方法）	15 分钟
4	精读「6」：模板与目录怎么协同	5 分钟
5	动手练「7」：填自己的模板 + 画目录骨架	15–25 分钟
6	自测「8」+ 打卡	10 分钟

3. Week 4 开门：前三周你攒下了什么

先自己默写，再对照下表。能独立写出来，说明前三周没白学。

周	一句话
Week 1（Day 1–7）	认知打底：SDD 三大瓶颈、完整闭环、spec 七要素、三种落地、动手写 spec、工具链、周复盘——产出 spec v2
Week 2（Day 8–14）	Harness 工程：四大护栏、.ai/ 目录、安装 pre-commit hook、七命令循环、多实现对比、spec-first 提交、周复盘——产出跑通的 harness
Week 3（Day 15–21）	工程化闭环：四类契约、规范即代码/测试、持续交付、Gherkin 验收、三大挑战、端到端功能、周复盘——产出完整闭环证据

Week 4 要回答的问题：前三周你每次都是从零开始搭的。如果下周一新项目、新队友、新 AI 来了，你能半小时内把整套架子立起来吗？不能，就说明经验还在脑子里，没变成可复用的东西。沉淀，就是把”我会”变成”我有”。

4. 沉淀 spec 模板：把”会写”变成”有模板”

4.1 模板要回答的四个问题

问题	答案
为什么沉淀？	写 spec 的高频动作是”填空 + 查漏”，不是”创作”。模板把七要素、复查清单、GWT、四类契约内嵌成”占位符 + 提示句”，填的时候自然不漏
模板由哪几块组成？	① 七要素主体（Day 5）② 验收标准统一 GWT + 数字（Day 5/7/18）③ 四类契约区（Day 15，按需）④ 变更记录区（delta spec 四标记，Day 6）
为什么放 delta spec？	存量项目改功能时，不需要重写全量 spec，只写”这次改了什么”（Day 6）。所以模板要有全量版和 delta 版两种形态
怎么迭代？	模板 v1 今天定稿，Day 27 大作业复盘后用真实教训升级为 v2，Day 28 输出最终版 v3

4.2 spec 模板骨架 v1（可直接复制）

用法：新建 spec 时复制下面的骨架，逐节填空；括号里的灰色文字是提示，填完删掉。标题/要素编号与 Day 5 完全对齐，方便复查清单直接套用。

# Spec：<功能名>

> 状态：draft / in-review / approved / implemented
> 日期：YYYY-MM-DD ｜ 作者：<你> ｜ 关联变更：<delta 提案名，如有>

## 1. 背景
<现状数据？代价？给 1–2 个数字。删掉这段还知道"非做不可"吗？>

## 2. 目标
<outcome，不是 output；一句话可量化成功判据；技术方案（HOW）留待 plan，不写在这里>

## 3. 用户故事
- 作为<角色>，我想<能力>，以便<价值>。
- <每条故事至少能对应到一条验收>

## 4. 验收标准
- AC-1（主路径）：GIVEN <前置>，WHEN <动作>，THEN <可观测结果 + 数字>
- AC-2（失败路径）：GIVEN <前置>，WHEN <动作>，THEN <明确错误码 / 降级行为>
- AC-3（回归/边界）：GIVEN <前置>，WHEN <动作>，THEN <可观测结果 + 数字>
- <每条 AC 都能转成一句自动化断言，零形容词>

## 5. 非目标
- 不做：____
- 不改：____
- 不重构：____
- <至少 3 条，堵住 AI"顺手多做"的空白；把"我顺手的念头"也写进来>

## 6. 边界条件
- 空结果：____
- 极限数据：____
- 超时/失败：____
- 并发：____
- <至少覆盖 3 类>

## 7. 验证方式
- AC-1 ← <哪个脚本/指标/样例集证明>
- AC-2 ← <同上，与 AC 一一对应>

## 8. 四类契约（按需填写，Day 15）
- 数据契约：<Schema 变化>
- 行为契约：<API 边界 / 异常>
- 质量契约：<延迟 / 吞吐 / 准确率 + 数字>
- 可观测性契约：<日志 / 指标 / 追踪>

4.3 delta spec 片段模板（改存量项目时用）

# Delta for <域>
## ADDED Requirements
### Requirement: <新增能力名>
<行为描述>
#### Scenario: <场景名>
- GIVEN <初始状态>
- WHEN <动作>
- THEN <预期结果 + 数字>

## MODIFIED Requirements
### Requirement: <要改的已有行为名>
（此前）<原行为>
（改为）<新行为>

## REMOVED Requirements
### Requirement: <下线的行为名>

## RENAMED Requirements
### Requirement: <原名> → <新名>

自检三问（沿用 Day 6）：① 只写了”这次改了什么”吗？② 每条 Scenario 有 GIVEN/WHEN/THEN 吗？③ 新增/修改/删除/重命名分清楚了吗？

5. 设计自己项目的 .ai/ 目录骨架

5.1 sdd-harness 的参考结构（Day 9 精读过）

sdd-harness 用 .ai/ 目录收纳全部”AI 协作上下文”，零依赖（bash + git）、runtime-agnostic：

<你的项目>/
├── CLAUDE.md / AGENTS.md     # 5 行 bootloader，只重定向到 .ai/ROUTING.md
└── .ai/
    ├── ROUTING.md            # canonical 入口：告诉 AI"先读我，再按图索骥"
    ├── PRODUCT.md            # 用户填：产品背景、目标、边界
    ├── CONTEXT.md            # 用户填：项目约定、术语、技术栈约束
    ├── BACKLOG.md            # 用户填：待办池
    ├── BOOTSTRAP.md          # 初始化脚本/说明
    ├── adrs/                 # 架构决策记录（Architecture Decision Records）
    ├── agents/               # 子代理定义（含 spec-writer）
    ├── commands/             # 七个 Markdown 流程文件（spec/story/implement/verify/review/release/phase-close）
    ├── hooks/                # pre-commit-spec-check.sh + post-edit-trace.sh
    ├── notes/                # 学习/踩坑笔记
    └── specs/                # 你的 spec 都放这里（含 delta spec）

记忆锚点：ROUTING 是地图，PRODUCT/CONTEXT/BACKLOG 是用户填的”三张表”，adrs 记决策，agents 定义人设，commands 定义流程，hooks 做守门，specs 存契约。

5.2 你的裁剪版（今天动手练要画的东西）

sdd-harness 是全量参考，你的项目按需裁剪，推荐”最小可用集”：

<你的项目>/
└── .ai/
    ├── ROUTING.md            # 必留：AI 的第一入口
    ├── CONTEXT.md            # 必留：术语/约定/技术栈
    ├── BACKLOG.md            # 建议留：待办池
    ├── adrs/                 # 建议留：>1 人协作时尤其有用
    ├── commands/             # 必留：Day 23 往里填流程文件
    ├── hooks/                # 必留：pre-commit-spec-check.sh（Day 10 已装）
    ├── notes/                # 建议留：踩坑清单（Day 28 输出）
    └── specs/                # 必留：spec 模板 v1 放这里当"母版"

裁剪原则：单人小项目可去掉 PRODUCT.md / BOOTSTRAP.md / agents/；只要开始协作，adrs/ 和 commands/ 就建议保留。

6. 模板与目录怎么协同

一句话：specs/ 是仓库，模板是模具，ROUTING.md 是索引。

模板 v1 存到 .ai/specs/_template/（或 specs/templates/），新功能复制它 → 填 → 存回 specs/<功能名>.md。
改存量功能时用 delta 片段模板，存 specs/deltas/<变更名>.md。
ROUTING.md 里加一行：”spec 一律用 .ai/specs/_template/ 下的模板书写”——这样 AI 和队友都按同一把尺子来。

7. 动手练（约 20–25 分钟）

7.1 定稿你的 spec 模板 v1（15 分钟）

复制第 4.2 节骨架到新文件 MySpec-Template-v1.md。
对照 Day 5 的 spec v2 微调：哪些要素你实际用不上？哪些提示句对你最有用？把提示句改成你自己的话。
把第 4.3 节 delta 片段追加到同文件末尾。
自检：拿你 Day 5 的 spec 往里套一遍，能不能”套得进去”？套不进去的地方就是模板要改的地方。

7.2 画你的 .ai/ 目录骨架（8–10 分钟）

按第 5.2 节的最小可用集，画出你自己项目的目录树，标注每个节点”必留 / 建议留 / 已砍”。把图存成 My-AI-Directory-Skeleton.md。

打卡输出：MySpec-Template-v1.md + My-AI-Directory-Skeleton.md。Day 23 要在你的目录里填 commands 和 config.sh。

8. 自测题

Week 4 的主题「沉淀输出」要解决前三周遗留的什么问题？
你的 spec 模板 v1 融合了哪几天的成果？（至少说出 4 天）
全量 spec 模板和 delta 片段模板分别在什么场景用？
.ai/ 目录里 ROUTING.md 的作用是什么？为什么说它是 canonical？
.ai/ 目录里哪几个节点是”用户填”的？哪几个是”AI 读”的？
裁剪 .ai/ 目录时，”只要开始协作就建议保留”的两个目录是什么？为什么？
你的模板里，AC 的统一格式是什么？为什么必须带数字？
为什么 spec 模板里要留”四类契约”区？它对应 Day 15 的什么概念？

提示：第 2 题答案在 4.1 的表里；第 7 题答案是 GWT + 数字，理由可引用 Day 3/7 的”形容词是验收死敌”；第 8 题对应数据/行为/质量/可观测性四类契约。

9. 延伸阅读

sdd-harness 仓库（.ai/ 目录结构与七个 commands 的原始出处）：https://github.com/iMark21/sdd-harness
腾讯云《SDD 规范驱动 + Harness：AI 全栈开发从”能跑”到”可控”》（规范即代码的落地形态）：https://cloud.tencent.com/developer/article/2703349

本工作纸依据《SDD+Harness四周学习计划.md》Day 22 主题编制。整理日期：2026-09-09

SDD+Harness 四周学习计划 · Week 4 · Day 22