Field Manual · 作战手册

Agentic 开发作战手册

这一页不是又一篇概念综述。它是把 12 份一线实践（Addy Osmani、obra/superpowers、Every compound engineering、spec-kit / OpenSpec / BMAD、gstack、everything-claude-code、oh-my-claudecode、planning-with-files、mattpocock/skills）读完之后，逐个决策点拍板出来的一套个人 agentic 开发体系——5 条没人跳过的业内共识、5 个必须自己选的决策、一张 L0/L1/L2 路由表、可直接复制的模板，和 8 题通关自测。所有选型都已在本机落地跑通，不是纸上方案。

定稿于 2026-07-07：4 路并行子 Agent 调研 → 头脑风暴逐点拍板 → 当天落地（skill 治理、CLAUDE.md 重写、记忆桥、SDD 接入）。方法本身就是这套体系的第一次实战。

§1

共识层：没人跳过的五件事

12 份资料立场各异、重量级悬殊，但这五件事所有人都在做——分歧只在「做多重」，没人跳过。这一层不需要选型，直接采纳。

共识层是地基。下面五个决策点，才是你必须结合自己处境拍板的部分——每张卡给出业界谱系、我的选择和为什么，你的答案可以不同，但不能不答。

§2

五个决策点：谱系、选择与理由

读资料的正确姿势不是「都学」，而是把它们放到同一个决策点下对比，然后选一个能落地的。以下是我的五次拍板。

A

狭义 Context：CLAUDE.md 怎么写、怎么分层

每个 session 都要付的固定成本，写错方向就是持续漏 token。

  • 极简五要素派（Addy context-engineering）：只写技术栈、常用命令、约定、边界、一个「好范例」文件——范例比十条规则管用。缺点：纪律没地方放。
  • 全家桶派（everything-claude-code）：34 条 rules 分层 + 20 个 hooks + 完整模板。覆盖全面，但大量 rules 是模型本来就会的通用建议，纯吃上下文——ECC 自己都警告别全量堆叠。
  • 三层各司其职：全局层薄（个人硬纪律 + 反借口表 + 路由判据）；项目层五要素 + 指针；流程给 skills，确定性给 hooks，CLAUDE.md 不承担流程。

我的选择：三层各司其职。判据一句话：每一行都要过「删掉这行，agent 会做错什么？」测试——答不上来就删。实现细节会过时（用文件引用代替）、通用建议模型已会（删）、流程步骤该做成 skill（挪走）。

谱系：addyosmani/agent-skills（context-engineering）· affaan-m/everything-claude-code · 模板见 §4

B

广义 Context：知识大脑放在哪

踩坑教训、架构决策、项目档案——放 repo 里还是笔记库里？

  • 先立判断标准：按「消费者是谁」分家。agent 消费的知识必须放在 agent 默认可达的地方；「靠约定才够得着的记忆」在实践中一定会被遗忘。
  • repo 内沉淀（compound 派）：docs/solutions/ + docs/adr/，与代码同版本、可 grep、换机器不断链。缺点：跨项目知识各自为政。
  • 笔记库唯一大脑（Obsidian 等）：人看东西只有一个地方，跨项目档案统一。缺点：agent 默认读不到，桥必须自己修。
  • 双层：agent 的记忆在 repo，人的大脑在笔记库，中间定「升舱」规则。

我的选择：笔记库唯一大脑（Obsidian），把桥修成一等公民基础设施。三条协议：① 每个 repo 的 CLAUDE.md 显式指向笔记库里的项目文件夹；② 开工读项目 index、收工写回（进度、决策 ADR、踩坑 pattern）；③ plan / review / debug 开工先检索 Learnings，命中标 Known Pattern。代价是 repo 可移植性（云端 agent、协作者读不到）——单机工作流可接受。

诚实的变体提示：如果你多机工作或有协作者，双层更稳——agent 记忆走 repo，笔记库只留人读的档案。

谱系：EveryInc/compound-engineering（docs/solutions）· gstack（gbrain）· planning-with-files

C

流程：SDD 框架怎么选、怎么分级

spec-kit、OpenSpec、BMAD、superpowers……装哪个？答案是别把这当单选题。

  • spec-kit（GitHub 官方）：constitution + 七步阶段门（specify→plan→tasks→implement），中量级，适合绿地大 feature；小改动仪式感过剩。
  • OpenSpec：最轻（proposal→apply→archive），唯一有 living spec 机制——archive 时把变更增量回写 source of truth，专为存量项目设计。
  • BMAD：模拟整个敏捷团队（PM/Architect/Dev/QA 十余角色）。对 solo 开发者，多数场景 overkill——只值得借它的 architecture 单品。
  • superpowers：不是 spec 格式而是硬门全链——brainstorm→写计划→subagent 逐任务执行→review→验证，纪律最强。

我的选择：不选框架，选路由。SDD 的失败模式不是「框架选错」而是「一刀切」：小改动过重仪式导致弃用，大改动裸奔导致返工。按改动大小分级——L0 直接干、L1 走 OpenSpec 提案流、L2 走 superpowers 全链（见 §3 路由表）。公认教训：spec 的价值 = agent 真的会读 × 跨会话存活 × 随代码演进，写完即弃的 spec 是纯开销。

谱系：github/spec-kit · Fission-AI/OpenSpec · bmad-code-org/BMAD-METHOD · obra/superpowers

D

技能：skill 装了一堆，怎么治理

合集仓库随手一装就是 100+ 个 skill——这本身就在吃你的上下文，还让 agent 同时听几套指挥。

  • 治理的钥匙是一个区分：流程型互斥，工具型可叠加。流程型 skill（brainstorm、plan、review）定义「按什么步骤走」，同时激活两个 = 让 agent 听两套互相矛盾的流程；工具型（浏览器、笔记库 CLI、图表）只提供能力，叠加无害。
  • 一阶段一主将：把开发生命周期切成阶段（构思/规格/架构/计划/开发/评审/QA/发布/排障），每阶段只激活一个流程主将 + 若干工具型。同类非主将不删源、只不激活——想换随时换。
  • 单一供应链：所有 skill 从一个管理面进出（git 上游源 + 本地自写目录），插件层只留工具型/平台型。我落地时在四个角落挖出了四层混居的 skill，收编成单链后：68 项全部受管、零散件。
  • 自己只写「胶水」：流程上游已经卷得很成熟，值得自写的是接你自己基础设施的胶水（比如把 learnings 沉淀改道到自己的笔记库）。
阶段主将（我的选型）为什么
构思interview-me（Addy）一次一问磨意图，比发散 brainstorm 适合 solo
规格openspec-proposal / gstack-specL1 提案流 / L2 绿地五阶段
架构bmad-architectureBMAD 唯一保留单品
计划superpowers writing-plans产出能直接喂 subagent 的细粒度计划
开发superpowers executing-plans + TDDIron Law 纪律最硬
评审gstack-review + Codex 第二意见双模型独立复审
QAgstack-qa真浏览器闭环找 bug
发布gstack-ship测试→diff→版本→changelog→PR 全流水线
排障superpowers systematic-debugging没查到根因不许动代码

谱系：garrytan/gstack · obra/superpowers · Yeachan-Heo/oh-my-claudecode（模式分档思路）

E

纪律：验证与编排开多大档

全档 TDD 太磨，全靠自觉必翻车——档位要跟着改动大小走。

  • L0：只强制 verification-before-completion——跑起来、看到证据、才算完成。「应该能工作」不是证据。
  • L1：TDD（改行为必须测试先行，红→绿→重构）+ 单模型 review。
  • L2：TDD + 双模型 review（一个写、另一个独立复审——卡住时换模型也是 Addy 的「model musical chairs」）+ 真浏览器 QA。
  • worktree 隔离：开发/QA/排障强制独立 worktree，评审只读——agent 实验不弄脏主工作区。

唯一全级别不可豁免的是 verify。它是调研里公认「成本最低、防『假完成』收益最大」的一条：没跑验证命令、没看到输出，就不许说「完成」。

谱系：superpowers（verification-before-completion / Iron Law）· Addy Osmani（Never commit code you can't explain）

§3

两轴路由：什么改动走什么流程

横轴是生命周期阶段（每阶段一个干净工作台），纵轴是改动大小（决定走哪几个阶段）。三级还对应三种「你出现的程度」——高效指挥 agent 的具体形态，就是把注意力只花在杠杆最高的决策点上。

级别判据走哪些阶段验证档位你出现的程度
L0 小改<30 分钟，影响面一目了然直接干verify：跑起来见证据只看结果
L1 中改≤半天，改行为，存量演进spec（提案）→ 批准 → dev → reviewTDD + 单模型 review批 proposal
L2 大活多天，新子系统 / 新项目构思 → spec → 架构 → 计划 → dev → review → QA → 发布TDD + 双模型 review + 浏览器 QA全程参与设计
debugbug / 故障（横切，不分级）先根因，后动手，补回归测试根因证据 + 回归测试看根因报告

把判据写进全局 CLAUDE.md，让 agent 开工先自报「这是 L 几」，拿不准就问。跨阶段衔接用文件接力：每阶段收尾把产出落盘，下一阶段开新会话读文件——接力棒是结论文件，不是聊天记录（fresh context，共识 #4）。

练手：这个改动是 L 几？

☝ 点一个场景，看它该走哪条路由、为什么。
§4

模板库：拿去就能用

四份模板都是我实际在用的版本做了通用化（把本机路径换成占位符）。复制后按「删掉这行 agent 会做错什么」的标准裁剪成你自己的。

T1 · 全局 CLAUDE.md（路由 + 硬纪律 + 反借口表 + 记忆协议）

~/.claude/CLAUDE.md
# 全局约定

## 开工路由：先自报改动等级
- **L0 小改**（<30 分钟、影响面一目了然）：直接做，验证门槛不减。
- **L1 中改**（≤半天、改行为、存量演进）：先出变更提案，批准后实现，完成后归档回写 spec。
- **L2 大活**（多天、新子系统/新项目）：走全链 brainstorm → spec → architecture
  → plan → 分步实现 → review → qa → ship。
- 修 bug 走 debug 流程（先根因后动手），不参与分级。
开工时先说「这是 L 几」，拿不准就问。

## 硬纪律（不可协商）
1. 没跑验证不许说「完成」——必须给出运行命令与输出证据。
2. L1/L2 改行为必须测试先行（红 → 绿 → 重构）。
3. 修 bug 先定位根因，未定位不许改代码。
4. L1/L2 未经批准的 spec/plan 不写产品代码。
5. 不确定就问，不许编造 API 或事实。

## 反借口表（出现这些念头 = 停下）
| 借口 | 反驳 |
|---|---|
| 「先跳过测试，回头补」 | 回头不存在。现在写。 |
| 「改动太小不用验证」 | 小改动引发的事故最多。跑一遍。 |
| 「应该能工作 / 看起来对」 | 「应该」不是证据。要输出。 |
| 「直接修快一点」 | 不查根因的修复会回来第二次。 |
| 「这个不用写进 spec」 | 没写下来的东西不存在。 |

## 记忆协议
- 项目档案在 <你的笔记库>/<项目>/：开工先读 index，收工把进度/决策/踩坑写回。
- plan / review / debug 开工先查该项目的 Learnings 与 ADR，
  命中要在产出里标 Known Pattern 并遵循；修完非平凡 bug 主动提议沉淀。

## 本机
- （把你机器上的环境陷阱写在这里，例：node 要用绝对路径 ~/.nvm/.../bin/node）
全局层只写「稳定、且 agent 猜不到」的东西。语言偏好、模型选择这类配置项放 settings，不占 CLAUDE.md。

T2 · 项目 CLAUDE.md（五要素 + 指针）

<repo>/CLAUDE.md
# <项目名>（项目约定）

## 项目是什么
一句话：做什么、给谁用。线上地址 / 部署方式。

## 技术栈与关键命令
- 栈：<语言 / 框架 / 数据库>
- 构建：`<命令>` · 测试：`<命令>` · 本地起服务：`<命令>`
- 部署：<怎么发布，push 即上线还是要跑脚本>

## 约定
- 目录结构要点、命名规则、代码风格里「模型猜不到」的部分。

## 边界（不许碰）
- <目录/文件>：为什么不许动（需要硬保证就再加 permissions deny 或 hook）。

## 范例
- 新增 <页面/模块/接口> 照 `<某个真实文件路径>` 写——范例比十条规则管用。

## 指针（引用，不内联）
- 进度与决策档案：<笔记库项目文件夹路径>（开工先读 index）
- 深入文档：`docs/<...>`
五要素出自 Addy 的 context-engineering：stack / commands / conventions / boundaries / 一个好范例。实现细节永远用文件引用，不复制进来。

T3 · 踩坑 pattern（Learning）模板

<笔记库>/<项目>/Learnings/YYYY-MM-DD-主题.md
# <一句话说清坑>

- **症状**：报什么错 / 什么行为
- **根因**：真正原因（不是表象）
- **解法**：怎么修的，贴关键命令或代码点（file:line）
- **防复发**：下次怎么提前发现 / 避免（检查命令、写进哪个配置、加了什么测试）
- **适用边界**：什么情况下这条不适用
≤15 行，写给两周后的自己 30 秒能用上。判断要不要记的标准不是坑的大小，是会不会再犯。

T4 · 架构决策记录（ADR）模板

<笔记库>/<项目>/ADRs/YYYY-MM-DD-决策名.md
# <决策名>    （status: proposed | accepted | superseded）

- **背景**：什么问题逼出这个决策
- **选项**：候选方案 + 一句话权衡
- **决定**：选了什么
- **后果**：接受了什么代价；什么信号出现时该重审
被推翻的旧 ADR 改 superseded 并链到新档，不删除——决策历史本身就是 context。质询（grill）收敛时顺手写 ADR，让「问清楚」这个动作直接变成沉淀。
§5

来源书架：每份资料最值得抄的一件事

不必都读。每条只记一件「这家独有、别家没有」的事——想深入哪个再点进去。

§6

自测：会路由、会治理，才算学会

8 题全对才算通关。错了会给出该重读的小节。

0 / 8 已作答