| name | handbook-search |
| description | ai-playbook handbook（数千行）智能查询入口。当用户/任务提到 §NN.M 章节号、 "手册"、"playbook"、"铁律 #N"、"反模式"、"竞品" 等关键词时自动触发。 读 INDEX.md 得章节号 → grep 运行时定位行 → 精读对应段，避免塞全文进上下文。
|
| user-invocable | false |
| when_to_use | 用户提到 §<数字>.<数字> 章节引用、"手册第 N 节"、"playbook 说"、"铁律 #N"、 "反模式 #N"、"按手册"、handbook.md 的具体章节查询时。
|
Handbook Search (§4 Context Engineering 实践)
handbook.md 数千行 / §1-§50。全塞进上下文反 §4.1（attention budget 浪费）。
本 skill = "INDEX 得章节号 → grep 定位行 → 精读" 三段式。v3.14：用 grep 运行时定位，不依赖硬编码行号（行号随编辑漂移，grep 永远准）。
工作流
Step 1: 读 INDEX.md 得章节号（不是行号）
test -f playbook/INDEX.md && cat playbook/INDEX.md
INDEX.md 维护"场景/铁律/反模式 → §号"语义映射（不再有行号）。例：forbidden 路径 → §32.1；EDD → §35。
Step 2: grep 运行时定位章节起始行
grep -nE '^## 32\.' playbook/handbook.md
grep -nE '^### 32\.1' playbook/handbook.md
grep -nE '^## 铁律' CLAUDE.md
| 用户问题模式 | 应查 § | grep 模式 |
|---|
| "§32.1 怎么说的" | §32.1 | ^### 32\.1 |
| "铁律 #13 是什么" | CLAUDE.md 铁律段 | ^## 铁律 然后看第 13 条 |
| "vibe coding 反模式" | §32.5 / §33 | ^### 32\.5 / ^## 33\. |
| "什么是 spec-driven" | §18 | ^## 18\. |
| "Constitution 怎么写" | §37 + docs/ai-cto/CONSTITUTION.md | ^## 37\. |
| "怎么跨模型 review" | §48 | ^## 48\. |
| "怎么写 eval" | §35 + evals/ | ^## 35\. |
| "分发档位/装子项目" | §49 | ^## 49\. |
Step 3: 读特定章节段
grep 得起始行 L 后：
Read(file_path="playbook/handbook.md", offset=L, limit=120)
不够再以 offset+limit 续读到下一个 ^## 为止。
Step 4: 引用回应
用 §N.M 格式精准引用（基于实际读到的内容，铁律 #2）：
"按手册 §32.1，forbidden 路径定义为 ..."（不写行号——行号会漂）
反模式
| 反模式 | 应当 |
|---|
直接 Read playbook/handbook.md（全文） | 先 INDEX 得 §号 → grep 定位 |
| 凭记忆引用 §N.M | 必须 grep + Read 实际确认（铁律 #2） |
| 引用硬编码行号 | 用 grep 运行时定位（行号会漂移） |
| 不引用直接说"手册说" | 用 §N.M 格式让用户能查证 |
当 INDEX.md 不存在
"⚠️ playbook/INDEX.md 不存在。
fallback: grep -nE '^## [0-9]' playbook/handbook.md 列全部章节标题再定位。"
引用
- handbook §4.1 Context Engineering（为什么不塞全文）
playbook/INDEX.md（章节语义映射 SSOT，无行号）- 定位方式：
grep -nE '^## N\.' playbook/handbook.md
