第 23 天：固化工具——把常用命令固化为团队 commands；配置 hooks config.sh 保护范围

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

今日主题：固化工具：把常用命令固化为团队 commands；配置 hooks config.sh 保护范围

建议用时：60–90 分钟 ｜ 前置：Day 11 的七命令循环 + 已装 harness 的测试仓库

输出物：3–5 个 commands 文件（Markdown）+ config.sh 保护范围配置（含 SH_CODE_GLOBS / SH_CODE_EXCLUDE_GLOBS）

0. 一句话剧透

Day 11 你学的是”七命令循环”——spec → story → implement → verify → review → release → phase-close，但那是纸上的流程。今天把它们固化成 .ai/commands/ 下的 Markdown 流程文件，让 AI 和队友照着同一份文件执行；再配置 hooks 的 config.sh，把”哪些改动必须写 spec”的保护范围用 SH_CODE_GLOBS / SH_CODE_EXCLUDE_GLOBS 钉死。Day 22 造了模板（模具），今天造流程（流水线）。

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

• 能说出 Day 11 七命令循环的完整顺序和各自用途
• 能写出一个标准 commands 文件的四段结构（Usage / Inputs / Procedure / Done criteria）
• 能讲清 SH_CODE_GLOBS 和 SH_CODE_EXCLUDE_GLOBS 各自控制什么、默认值是什么
• 能配置 config.sh，让”改代码不写 spec”被拦、而”只改文档”不被拦
• 完成动手练：把 3–5 个常用命令固化成文件 + 配好 config.sh 并验证

2. 学习动线

3. 回顾 Day 11：七命令循环

今天不学新命令，把其中你最常用、最该让团队统一的几个（spec / implement / verify / review 是重点）写成文件。

4. commands 文件：流程的”标准作业指导书”

4.1 为什么用 Markdown 文件而不是脚本

sdd-harness 的 commands/ 下是七个 Markdown 流程文件，不是可执行脚本。原因是：流程是给人 + AI 共同读的——人要照着执行，AI 要照着推断。固定四段结构（Usage / Inputs / Procedure / Done criteria），任何人在任何 CLI 里都能对齐”现在该干嘛、干完算没算完”。

4.2 四段结构

4.3 示例 1：spec.md（今天直接可用）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Command: spec

## Usage
在开始任何代码改动之前运行；输入一个粗粒度需求，产出 .ai/specs/ 下的 spec 文件。

## Inputs
- 需求描述（一句话即可）
- 目标文件：.ai/specs/<功能名>.md

## Procedure
1. 复制 .ai/specs/_template/ 下的模板（Day 22 产物）
2. 按模板七要素逐节填充
3. 验收标准统一为 GWT + 数字
4. 涉及存量功能时，改用 delta 片段模板（只写本次变更）

## Done criteria
- 七要素齐全
- 每条 AC 可转自动化断言，零形容词
- 无 HOW（技术方案不写进 spec）
- 已存盘并登记到 ROUTING.md

4.4 示例 2：verify.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Command: verify

## Usage
实现完成后运行；验证 spec 的每条 AC 都有证据。

## Inputs
- spec 文件路径
- 测试/验证结果位置

## Procedure
1. 逐条 AC 对照证据（自动化测试 / 样例集 / 压测记录）
2. 无证据的 AC 标记为"待验证"，不允许进入 review

## Done criteria
- 每条 AC 有对应证据
- 失败项已记录原因，未静默跳过

4.5 示例 3：review.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Command: review

## Usage
verify 通过后运行；产出书面审查记录（Day 25 详讲"书面"二字）。

## Inputs
- spec 文件路径
- 代码 diff / PR 链接
- 验证证据位置

## Procedure
1. 对照 spec 逐条 AC 检查实现
2. 检查"非目标"是否被悄悄越界
3. 记录：审查人、日期、结论（approve / request-changes）、遗留问题

## Done criteria
- 有可追溯的审查记录（不是口头"我看了"）
- request-changes 时给出具体修改点

5. hooks config.sh：把”保护范围”配置化

5.1 为什么需要 config.sh

Day 10/13 你体验过 pre-commit hook：feat/* 或 feature/* 分支上改代码但不碰 .ai/specs/ 或 .ai/adrs/ → 提交被拒；chore/* docs/* fix/* hotfix/* 豁免；SH_SDD_SKIP=1 显式例外。但”哪些文件算代码”不能写死，要可配置——这就是 hooks/config.sh 的职责。

5.2 两个核心变量

• SH_CODE_GLOBS：定义哪些文件路径被视为”代码”（默认 include *，即所有文件）
• SH_CODE_EXCLUDE_GLOBS：定义哪些路径被排除（默认排除 .ai/ 目录与文档类文件如 *.md）

判定逻辑：只有”被 SH_CODE_GLOBS 匹配 且 不被 SH_CODE_EXCLUDE_GLOBS 排除”的文件改动，才会触发”改代码必须同时改 spec”的检查。

注意：具体变量名与默认值以 sdd-harness 仓库实际 config.sh 为准（待核验）。以下为基于其设计的示例，动手配置前先到仓库核对。

5.3 config.sh 配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# .ai/hooks/config.sh —— pre-commit hook 保护范围
# 说明：以下为基于 sdd-harness 设计的示例；变量名/默认值以仓库 config.sh 为准（待核验）

# 1) 哪些路径算"代码"（默认 include *，即所有文件）
SH_CODE_GLOBS=(
  "*"
)

# 2) 哪些路径排除在"代码"之外（默认排除 .ai/ 与文档类）
SH_CODE_EXCLUDE_GLOBS=(
  ".ai/*"
  "*.md"
  "docs/*"
  "*.txt"
  # "*.json"   # 若你不想让配置文件改动触发 spec 检查，可取消注释
)

# 3) 分支豁免规则（沿用 Day 13 的 hook 行为，通常由 hook 脚本内建判断）
#    feat/* feature/* 分支：改代码必须带 spec
#    chore/* docs/* fix/* hotfix/*：豁免
#    SH_SDD_SKIP=1：显式例外，且 shell 历史留痕

5.4 配置完怎么验证（5 条清单）

1. feat/x 分支上只改一个 .md 文档 → 提交应放行（被 EXCLUDE 排除）
2. feat/x 分支上改 .py/.java/.ts 代码但不碰 specs/ → 提交应被拦
3. 改代码 + 改 spec → 放行
4. chore/x 分支上改代码 → 豁免放行
5. 强制场景用 SH_SDD_SKIP=1 git commit ... → 显式例外，shell 历史留痕

这套验证清单，就是 Day 26 大作业里”harness 配置证据”的一部分。每一条的通过/拦截现象都值得记录。

6. commands 与 config.sh 怎么变成”团队资产”

• commands/ 和 hooks/ 提交进仓库根目录 → 每个 clone 的人都有同一套流程和守门规则。
• ROUTING.md 里登记：”新功能先读 .ai/commands/spec.md“。AI 读 ROUTING.md 就会自动按流程走。
• 配置有改动 → 走 adrs/ 记录（Day 22 提过 adrs/），让”为什么这么配”有据可查。

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

7.1 固化你的 commands（15 分钟）

把第 4 节的 spec / verify / review 三个文件存到你的测试仓库 .ai/commands/，再按你的习惯补一个 implement.md（或 release.md）。每个文件必须四段齐全。

7.2 配置 config.sh 并验证（10–15 分钟）

1. 先去 sdd-harness 仓库核对真实变量名与默认值（标”待核验”处）。
2. 按第 5.3 节示例创建 .ai/hooks/config.sh。
3. 跑第 5.4 节的 5 条验证，逐条记录结果。

7.3 打卡

记录：哪条验证没通过？是配置问题，还是 hook 行为与预期不符？（这是 Day 27 复盘要用的素材）

8. 自测题

1. Day 11 七命令的完整顺序是什么？今天你固化了哪几个？
2. commands 文件的四段结构是哪四段？各回答什么问题？
3. SH_CODE_GLOBS 的默认值是什么？SH_CODE_EXCLUDE_GLOBS 默认排除哪两类路径？
4. 判定”是否触发 spec 检查”的逻辑是什么（两个变量如何共同作用）？
5. 在 feat/x 分支上只改 README.md，会不会被拦？为什么？
6. 在 chore/x 分支上改代码，会不会被拦？为什么？
7. SH_SDD_SKIP=1 是什么？为什么说它”留痕”？
8. commands 用 Markdown 而不是脚本，原因是什么？

提示：第 3、4 题答案在 5.2；第 5、6 题在 5.4 验证清单；第 7 题可回翻 Day 13 讲义。

9. 延伸阅读

• sdd-harness 仓库（commands/ 与 hooks/ 的原始出处）：https://github.com/iMark21/sdd-harness
• CSDN《SDD 和 Harness：AI 编程的两大支柱》（Harness 落地整体框架）：https://blog.csdn.net/qq_43284469/article/details/164267908

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

• Previous
  第 22 天：沉淀 spec 模板——提炼个人模板，设计自己项目的 .ai/ 目录骨架
• Next
  第 24 天：团队流程——分支规范（feat/fix/chore）、commit 规范、review/merge、release 与 SemVer