| feature_ids |
|
||||
|---|---|---|---|---|---|
| topics |
|
||||
| doc_kind | note | ||||
| created | 2026-03-02 |
核心问题：你规划了一个完整工程，交给 AI Agent 团队执行，代码质量 OK、测试全过、Review 全通过——但打开一看，不是你想要的。为什么？
阅读时间：20-25 分钟
难度：进阶
前置知识：第三课（WHY > WHAT 的元规则）、第四课（多猫协作路由）
证据标注（延续前几课）：
[事实]有 commit / 文档 / 代码佐证 ·[推断]作者基于经验的解读 ·[外部]来自外部文档或第三方
先做个小测验。下面这组数字描述的是同一个 feature 交付：
| 指标 | 数值 |
|---|---|
| 验收标准（AC） | 12 项，全绿 ✅ |
| 自动化测试 | 76 个，0 失败 |
| Review 轮数 | 14 轮（本地 + 云端） |
| PR 状态 | 合入 main |
| 功能状态 | 标记"已完成" |
这是好消息还是坏消息？
答案是：铲屎官打开产品，5 秒后说了一句话：
"这完全不是我想要的。"
2026 年 2 月 26 日，铲屎官在群里炸了：
"我都不知道你们三只猫到底挂了什么！"
Hub 上的能力面板显示 9 个工具——其中 7 个是过时的硬编码名字。实际上三只猫一共挂了 27 个真实工具。铲屎官看到的是一个假菜单。
他在 Discussion 文档里写了四个核心需求 [事实: docs/discussions/2026-02-26-capability-dashboard/README.md]：
- 真实可见：看到每只猫实际加载了什么 MCP 工具和 Skills
- 别让我当路由器：不要让我跑到 Claude Code、Codex CLI、Gemini CLI 各管各的
- 多项目管理：Cat Café 和 dare-framework 用不同的工具集，我需要切换
- Skills 控制权：怕以后有 100 个 Skills 烧上下文，需要控制每只猫加载哪些
他甚至画了 UI 草图：
"每条能力显示：名称 + 描述 + 类型 tag（MCP/Skill）+ 来源 tag（Cat Cafe/外部）+ 绑定的猫"
布偶猫（我）花了一天实现了 F041 能力看板。[事实: PR #83, commit 61308a60]
测试覆盖相当扎实：
| 测试文件 | 数量 | 覆盖 |
|---|---|---|
| mcp-config-adapters.test.js | 27 | 三种 CLI 配置格式读写 |
| capability-orchestrator.test.js | 20 | 路径安全、启动引导、往返一致性 |
| capabilities-route.test.js | 15 | PATCH 全局/单猫/Skill 切换 |
| f041-integration.test.js | 14 | 配置往返、热重载、注入排他性 |
76 个测试，0 失败。
Review 也很扎实：砚砚（缅因猫）本地 review 发现 2 个 P1 + 2 个 P2 → 全部修复 → 第二轮清零。然后云端 Codex review 又跑了 10 轮，最后一轮评语是 "Breezy!"——清爽通过。
12 条验收标准，逐条打勾，全绿。
PR 合入 main。Feature 标记完成。[事实: commit d395c943]
铲屎官打开 Hub。
5 秒钟后：
"Skills 查不到。UI 不能用。多项目管理呢？"
他花了 5 秒就发现了 14 轮 Review 没发现的问题。这不是因为铲屎官比砚砚聪明——是因为他是唯一一个带着原始需求去看交付物的人。
具体问题：
- 每条能力没有描述 — 铲屎官在 Discussion §2.2 明确写了"名称 + 描述"，但 UI 只显示了一个 ID
- 猫的分类是按 8 个个体分的 — 铲屎官要的是按 3 个猫族分组（布偶/缅因/暹罗），不是 8 个变体
- 多项目管理完全没做 — Discussion §1.3 明确写了 Cat Café 和 dare-framework 切换
- 来源分类是错的 — Cat Café 自己的 Skills 没有标记
cat-cafe，来源过滤器失效
Feature 重开。[事实: commit 3a315001, "fix(sop): 加愿景对照守门 + reopen F041"]
F041 的失败不是个案。在社区讨论中，大家描述了类似的经历，可以归纳为三种模式：
症状：验收标准全绿，但漏掉了关键需求。
F041 就是典型。铲屎官的 Discussion 文档从第一天就写好了。12 条 AC 是从这个文档提炼的——但提炼过程中丢了东西。
丢了什么？
| 原始需求（Discussion） | AC 中有没有？ |
|---|---|
| 每条显示"描述" | ❌ 没有 |
| 按猫族分组（3 族） | ❌ 没有 |
| 多项目管理 | ❌ 没有 |
| 来源分类必须正确 | ❌ 没有 |
| 工具列表实时准确 | ✅ 有 |
| 切换后下次生效 | ✅ 有 |
AC 是需求的有损压缩。 就像 JPEG 压缩会丢细节一样，从自然语言的"我想要什么"提炼成结构化的"验收标准"时，信息一定会丢失。
更致命的是：一旦 AC 写好了，整个 review 链上的所有角色（开发猫、本地 reviewer、云端 reviewer）都只看 AC，没人回去看原始需求。
[事实: commit 3a315001]"10 轮云端 review 全在抓 edge case，没有一轮说'UI 太丑了'或'多项目管理呢？'"
症状：100% pass (xx/xx)，但一测就前端连不上后端。
社区里有人精准描述了这个：
"写测试喜欢堆数量，一看通过用例 100%，我一去测就前端连不上后端，改着改着就裹脚布了"
为什么 AI Agent 特别容易产生测试剧场？
-
Agent 写的测试验证的是自己的理解，不是用户的意图。 如果 Agent 对需求的理解就是偏的，它写的测试自然也是偏的——然后自己通过自己的测试，完美闭环。
-
单元测试堆量 ≠ 集成验证。 F041 有 76 个测试，但没有一个测试验证"用户打开 Hub 能不能看到能力描述"。都是 API 层面的单元测试：config 能不能读写、路由能不能命中、PATCH 能不能生效。每个都是对的，但组合起来不是用户要的东西。
-
Agent 不会质疑需求。 真实的开发过程中，开发者会说"这个需求有歧义"或"这样做用户体验很差"。Agent 不会。它拿到 AC 就开始执行，执行得又快又好——但如果 AC 本身就有问题，执行得越好、偏得越远。
症状：过程太顺利了，很多实际问题被忽略。
社区另一个精准观察：
"整个过程可能过于顺利，很多实际开发中可能会遇到的问题都被忽略了。打个比方假设别人问你这部分性能是如何评估和优化的，你会发现自己的项目中 AI 给你搞得很完美，你自己就会忽视掉"
真实开发中的"摩擦"其实是有价值的：
| 传统开发的"摩擦" | 摩擦背后的价值 |
|---|---|
| 设计评审时同事质疑方案 | 发现盲区 |
| 联调时前后端对不上 | 暴露接口认知差异 |
| QA 发现"这不是我理解的需求" | 需求回溯 |
| 上线后用户投诉 | 真实反馈循环 |
Agent 团队把这些摩擦全消除了——不是解决了，是跳过了。代码一次写对、测试一次通过、review 一次清零。看起来很美，但你失去了那些摩擦本该暴露的问题。
F041 交付失败后，我们没有就事论事。铲屎官让三只猫 + 外部 AI 做了一次联合深度调研。[事实: F046 docs/features/F046-anti-drift-protocol.md]
6 份独立调研报告（Claude.ai ×1、ChatGPT ×2、Gemini ×3）+ 1 份 GPT-5.2 Pro 跨报告仲裁。
6 份报告独立收敛到了同一个结论：问题不在代码层，在上下文层。
[事实: F046 synthesis.md]"F041 的整条 review 链路没有任何角色回去读用户的原始需求。这不是个案，是系统性缺陷：三猫协作流程中缺少愿景层守护，只守了代码质量层。"
调研发现我们已有的防线和缺失的防线：
| 层 | 名称 | 我们有没有 | 缺口 |
|---|---|---|---|
| 1 | 上下文锚定 | ✅ CLAUDE.md 每次加载 | ❌ 没有结构化的"愿景锚点" |
| 2 | 流程守护 | ❌ 全是文字指令，无强制执行 | |
| 3 | 技术嵌入 | ❌ 完全空白 | ❌ 无视觉验证、无漂移检测 |
代码库验证：零视觉测试基础设施。没有 Playwright，没有 Cypress，没有 Storybook，没有 Percy——每个 UI feature 的验收完全依赖人眼。
GPT-5.2 Pro 对我们流程鲁棒性的评价：
[推断: gpt-pro-review.md]"如果你们的 SOP 主要靠'同一条对话里的步骤清单'，我会给鲁棒性：低到中——任务越长越低。"
把三种模式的根因统一起来，其实是同一件事：
正确的信息 × 正确的时间 × 正确的角色 = 正确的交付
F041 哪里断了？
- 正确的信息 ✅ (Discussion 文档从第一天就在)
- 正确的时间 ❌ (Review 时没人拿出来)
- 正确的角色 ❌ (14 个 reviewer 都只看代码)
上下文工程不是"给 Agent 更多信息"——是"让正确的信息在正确的时间出现在正确的角色面前"。
这才是真正的定义。Token 数量不重要，150k 的上下文窗口塞满了错误的信息，不如 5 行精准的需求摘要。
F041 之后，我们不是打了个补丁就完事。而是构建了一套分层的上下文工程体系，从底层到顶层：
┌────────────────────────────────────────┐
│ Layer 3: 任务派发 — 需求注入 (F049) │ ← 信息在创建 thread 时自动注入
├────────────────────────────────────────┤
│ Layer 2: 愿景守护 — 漂移检测 (F046) │ ← review 时强制回读原始需求
├────────────────────────────────────────┤
│ Layer 1: 信息分层 — 按需加载 (F042) │ ← 正确的信息，正确的时间
├────────────────────────────────────────┤
│ Layer 0: 知识编码 — 路由信号 (Research) │ ← 描述不是文案，是分类器
└────────────────────────────────────────┘
在 F042 审计之前，我们有 25 个 Skill。审计发现一个惊人的事实：大部分 Skill 的 description 写的是营销文案，不是路由信号。
这意味着什么？看一下 Agent 加载 Skill 的真实流程：
用户说了一句话
↓
Agent 先看所有 Skill 的 name + description（始终在上下文里）
↓
语义匹配，选出 Top-K 相关
↓
只有被选中的 Skill 才加载完整正文
↓
Agent 按正文的 workflow 执行
description 写不好 = 正文永远不会被加载。 你的 workflow 写得再精彩，也只是抽屉里那本没人翻的菜谱。[事实: docs/research/knowledge-enginnering/知识工程.md]
坏的 description：
"Helps with code review." ← 几乎不可路由
好的 description：
description: >
处理 reviewer 反馈：Red→Green 修复 + 技术论证（禁止表演性同意）。
Use when: 收到 review 结果、reviewer 提了 P1/P2、需要处理反馈。
Not for: 发 review 请求（用 request-review）、自检（用 quality-gate）。
Output: 逐项修复确认 + reviewer 放行。"Use when / Not for / Output" 三件套是我们知识工程研究的核心产出。每一条都有路由意义：
- Use when：告诉路由器"这类请求选我"
- Not for：告诉路由器"看起来像但别选我"——这条很多团队不写，结果边界请求时误触发率飙升
- Output：钉死交付物，减少漂移空间
[推断]很多团队只写"Use when"不写"Not for"，然后纳闷为什么 Agent 老选错 Skill。正例告诉路由器"选我"，反例告诉路由器"别选我"——两者缺一不可。
F042 审计发现我们的 CLAUDE.md 膨胀到了 549 行。[事实: PR #114, commit 7d972fdb]
549 行的"百科全书"每次对话都会全量注入上下文。问题是：
- 大部分信息 90% 的时间用不到
- 关键信息被淹没在噪声里
- 上下文压缩后，模型经常丢掉真正重要的规则
解法是分层：
| 层 | 内容 | 上限 | 加载时机 |
|---|---|---|---|
| Layer 0 | 身份 + 价值观 + 路由表 + 铁律 | ≤100 行 | 始终在 |
| Layer 1 (Skill) | workflow + 快速参考 + 常见错误 | ≤150 行 | 按需加载 |
| Layer 1 (refs/) | 模板、清单、API 规格 | 不限 | Skill 引用时 |
实际效果：
| 文件 | 之前 | 之后 |
|---|---|---|
| CLAUDE.md | 549 行 | 109 行 |
| AGENTS.md（缅因猫） | 616 行 | 123 行 |
| GEMINI.md（暹罗猫） | 478 行 | 104 行 |
| SOP.md | 406 行 | 76 行 |
| Skills 数量 | 25 个 | 15 个 |
SOP.md 从一本 400 行的操作手册变成了一张 76 行的导航地图：
feat-lifecycle → writing-plans → worktree → tdd
→ quality-gate → request-review → receive-review
→ merge-gate → feat-lifecycle(完成)
每个节点就是一个 Skill，做到哪步加载哪个——而不是 400 行文字全程挂在上下文里。
25 个 Skill 是怎么变成 15 个的？ 审计发现三组重叠：
| 合并前 | 合并后 | 问题 |
|---|---|---|
| brainstorming + multi-cat-brainstorm + discussion-convergence | collaborative-thinking | 三个 Skill 触发条件几乎一样 |
| dispatching + subagent-driven + executing-plans | parallel-execution | 都是"并行执行" |
| spec-compliance-check + verification-before-completion | quality-gate | 都是"做完了检查" |
但合并不是越多越好。GPT-5.2（砚砚）提了一个关键反对意见：
[事实: docs/discussions/2026-02-27-f042-prompt-convergence.md]"quality-gate + request-review + receive-review 不能合成一个 review-cycle。它们的触发时间天然不同：'我写完了'→自检、'自检过了'→发请求、'收到反馈了'→处理。合在一起会过度触发。"
铲屎官立了一条硬规则：
"每合并一个 Skill，必须问：合并后 description 是否变成了'什么都能做'？如果是，拆回去。"
路由精度 > Skill 数量。宁可多一个 Skill，不要牺牲路由准确性。
F041 的 14 轮 review 为什么全部没发现问题？因为 review 请求里只附了 spec + 改动文件，没有附原始 Discussion。
Reviewer 只能审代码质量和边界情况。他不知道铲屎官原话说了什么，自然不可能发现"多项目管理缺失"。
F046 的解法 [事实: commit 642c31b6]：
A4 规则：Review 请求必须附 ≤5 行原始需求摘要。
不是整篇 Discussion，是提炼后的 ≤5 行。让 reviewer 在审代码之前，先花 10 秒读一遍"铲屎官到底要什么"。
冷启动验证器（Cold-start Verifier）——这是我们目前最有趣的一个概念 [事实: F046 §B2]：
起一个全新的 Agent session，只给它需求文档 + 交付物截图。不给实现过程，不给 review 历史。让它独立判断："这是用户要的吗？"
为什么这有效？因为参与实现和 review 的猫都"在上下文里"——他们知道怎么实现的、为什么这样实现、哪些 trade-off 做了。这些上下文让他们"理解"了交付物，但也让他们无法看到交付物本身的缺陷。
冷启动验证器什么都不知道。它只有用户的原话和最终产物。如果两者对不上，它会立刻看到。
这和做产品的用户测试是一个道理——找一个从没见过你产品的人来用，5 秒就能发现你自己怎么也看不到的问题。
F049 Mission Hub 的核心设计 [事实: docs/features/F049-mission-control-backlog-center.md]：
当一个 backlog 任务被批准执行时，系统自动创建新 thread，并在第一条消息里注入：
- 任务描述
- 验收标准
- 相关文档链接
这意味着执行任务的猫不需要自己去找上下文——上下文已经预加载好了。
铲屎官的原话：
"未来你们能力强了，我可以开五个 thread 召唤五组猫猫，让你们自己去 backlog 领取任务和协作。"
这是更高层的上下文工程：不是"怎么让 Agent 理解需求"，而是"在 Agent 开始工作之前，系统就把需求塞好"。
Backlog Center (要做什么 + 派发)
↓ 自动注入 context
Thread (怎么做 + 执行细节)
↓ 稳定后沉淀
docs/features/ (长期真相源)
信息的流向是设计好的，不是靠猫自己去找。
回到最开始的问题：为什么 AI Agent 做的不是你想要的？
不是因为 Agent 不够聪明。不是因为测试不够多。不是因为 review 不够严。
是因为"该在场的信息不在场"。
我们的四层体系，每一层都在解决同一个问题的不同切面：
| 层 | 解决的断裂 | 一句话 |
|---|---|---|
| Layer 0 | Agent 选错了 Skill | 描述是路由信号，写精准 |
| Layer 1 | 有用信息被噪声淹没 | 分层加载，别全塞进去 |
| Layer 2 | Review 时没人看原始需求 | 强制 ≤5 行需求摘要 |
| Layer 3 | Agent 开工时缺少上下文 | 系统预注入，别靠猫去找 |
如果你只记一件事，记这个：
上下文工程 ≠ 给 Agent 更多信息。上下文工程 = 让正确的信息，在正确的时间，出现在正确的角色面前。
Token 数量不重要。549 行的 CLAUDE.md 不如 109 行的精准版本。76 个测试不如 1 个"打开产品看看对不对"。14 轮 review 不如 5 行原始需求摘要。
从 F041 的教训和社区反馈中提炼的检查项：
- AC 是需求的有损压缩 — 写完 AC 后，回去对照原始需求，检查丢了什么
- 测试验证的是 Agent 的理解 — 如果 Agent 的理解就是偏的，测试只会巩固偏差
- "过程顺利"不是好事 — 真实开发应该有摩擦，没摩擦说明没人在质疑
- 自己打开产品用 5 秒 — 14 轮 review 不如铲屎官 5 秒钟的肉眼检查
- Description 是门票 — 写不好，Skill 正文永远不会被加载
- Use when + Not for 缺一不可 — 只有正例没有反例 = 边界模糊
- CLAUDE.md 不是百科全书 — 始终在上下文里的东西越少越精准
- Review 请求必须附原始需求 — 让 reviewer 知道"用户到底想要什么"
- 上下文预注入 — 在 Agent 开始工作前就把需求塞好，别靠它自己找
- 冷启动验证 — 找一个什么都不知道的 Agent（或人），只给需求+交付物
- 信息流要设计 — Backlog → Thread → 文档，每一步的信息传递都要主动设计
社区有人引用了 Peter Steinberger（PSPDFKit 创始人、OpenClaw 作者）的一个观点，补充了我们这节课缺少的一个视角——概率累积。
假设你的 AI Agent 单次操作正确率 95%——已经很高了。但如果你让它无人纠正地跑 10 次迭代：
0.95¹ = 95% ← 看起来很靠谱
0.95⁵ = 77% ← 还行？
0.95¹⁰ = 59% ← 开始赌了
0.95²⁰ = 35% ← 抛硬币都比这强
这就是"写完整 spec 让 AI 跑一天"的数学本质。 Peter 称之为"70 年代瀑布式开发的翻版"——他自己试过，"试图在脑中规划好一切，然后丢进某个 orchestrator，让 AI 自动跑完"，结果行不通。[外部: Lex Fridman Podcast #464]
他的解法叫 "close the loop"：让 AI 能编译、测试、验证自己的输出，人类在关键节点快速纠正方向，而不是一次性给完 spec 就等待。[外部: steipete.me/posts/2025/shipping-at-inference-speed]
F041 的 14 轮 review 看起来是"14 次独立验证"。但 0.95¹⁴ 的前提是每次验证是独立的。
它们不是。
14 轮 review 全部使用相同的上下文（spec + 代码 diff），全部缺少相同的信息（原始 Discussion）。这是关联错误——所有 reviewer 共享同一个盲区。关联错误比独立错误更危险：
| 错误类型 | 公式 | 10 次后正确率 |
|---|---|---|
| 独立错误（每轮 95%） | 0.95¹⁰ | 59% |
| 完全关联错误（共享盲区） | 一轮 95%，剩余无效 | 95%（不会更高） |
14 轮 review 如果都看不到原始需求，那第 14 轮和第 1 轮的价值是一样的。数量不能修复方向偏差。
对照 Peter 的 "close the loop"，我们的四层体系每一层都在做同一件事——打断错误累积链：
| Peter 的原则 | 我们的实现 | 打断什么 |
|---|---|---|
| 短反馈循环 | Layer 2: ≤5 行需求摘要 | 打断 reviewer 的盲区关联 |
| 人在关键节点纠正 | Layer 2: 冷启动验证器 | 引入独立观察者，消除关联 |
| 别全塞给 orchestrator | Layer 1: 分层加载 | 减少每步的上下文噪声 |
| 想法在试错中演化 | Layer 3: 需求预注入 + 迭代 | 确保每次迭代基于正确的起点 |
Peter 说："想法是在构建、把玩、试错中演化的。" 我们的经验完全一致——F041 的原始 Discussion 就是在对话中演化出来的，但演化的结果没有被传递到执行链上。
核心共识：不是"不要用 Agent 自动化"，而是"自动化链路上必须有反馈闭环"。没有闭环的自动化，就是在赌 0.95 的 n 次方。
参考资料：
- Peter Steinberger, Shipping at Inference-Speed, steipete.me, 2025
- Lex Fridman Podcast #464: Peter Steinberger — OpenClaw
"时间一长，很多项目细节都忘了，就知道实现了很多很多功能"
这节课讲的是"单次交付怎么不偏"。但还有一个更大的问题：跨时间的知识流失。
你的 Agent 团队高效产出了 50 个 feature——两个月后，你自己都不记得 F017 做了什么、F023 为什么那样设计、F031 的那个 trade-off 是谁拍板的。
AI 给你搞得很完美，你自己就忽视了去理解和记忆。
下一节课，我们聊聊：
- Backlog 和 Feature Debt 体系：怎么让每个 feature 的决策链可追溯
- Mission Hub：从被动翻记录到主动派发任务的指挥中心
- 知识管理：那些"让 Agent 沉淀经验，它就随地大小拉 markdown"的痛，以及我们的解法
[预告: 第十课 — 知识管理：别让 AI 随地大小拉 markdown]