日期： 2026-08-01
核心问题： Anthropic的Thariq披露Claude Code系统提示词被删掉80%以上、编码评测无任何损失——这个反直觉发现对我们前17篇提炼的流程约束设计意味着什么？Context Engineering是否构成了7节点框架之外的新维度？综合方案需要哪些修正？

引言

本系列前17篇围绕”AI应该做什么”展开——从Explore到Archive的7个节点，从5个项目的对比到综合方案的提炼，再到Bun案例与Ponytail懒惰约束的检视。我们反复讨论”约束”——Superpowers的Iron Law、Rationalization表、HARD-GATE，gstack的21步ship流程和anti-footgun rules，ECC的delivery-gate hook。这些约束被视为塑造agent行为、防止常见失败模式的核心机制。

但2026年7月底，Anthropic创始团队成员、Claude Agent SDK核心负责人Thariq发了一篇长文，说了一件反直觉的事：他们把Claude Code的系统提示词删掉了超过80%，在Claude Opus 5和Claude Fable 5等新模型上，编码评测没有任何可测量的损失。

这不是”约束可有可无”的轻描淡写——这是Anthropic官方对自家产品做的最大规模简化实验。Thariq的结论是：他们曾经over-constraining了Claude Code，新模型已经有了足够的judgement，许多曾经的”必要约束”反而成了负担。

这个发现直接挑战了我们前文的部分核心假设。本篇以Thariq的文章为镜子，重新检视我们提炼的约束机制，讨论三个问题：

1. Thariq揭示的6个Then→Now转变，对我们前文的项目分析意味着什么？
2. Context Engineering是否构成了我们7节点框架遗漏的新维度？
3. 第十四篇的综合方案需要哪些修正？

需要强调：Thariq说的是Claude 5代际模型的行为，前文5个项目大多基于Claude 3代际或同代模型设计——它们的约束在当时是必要的。但模型能力在演进，流程设计必须随之演进。本篇不是否定前文，而是补全”模型能力拐点后”的演进方向。

1. Thariq实验的核心发现

1.1 80%瘦身无损失

Thariq的描述很直接：

We removed over 80% of Claude Code’s system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations.

这个数字本身已经足够震撼——一个产品的核心系统提示词删掉80%，功能评测不退反进。但更值得关注的是Thariq对原因的诊断：

Generally, Claude can interpret the user’s intent to get to the right answer, but Claude must think more carefully about these overlapping and conflicting messages before deciding what to do.

关键洞察：约束的代价不只是”占用context窗口”那么简单——当多条约束在同一请求中重叠或冲突时（比如”leave documentation as appropriate”和”DO NOT add comments”同时出现在system prompt、skills、CLAUDE.md中），模型必须在”思考该做什么”之前先”思考该听哪条规则”。这种元层面的判断消耗的是模型的有效推理能力。

这跟我们前文讨论的”context window稀缺”是两回事——context window是容量问题，而Thariq揭示的是约束冲突的认知负担问题。容量可以通过progressive disclosure缓解，认知负担只能通过减少约束本身来解决。

1.2 over-constraining的真实代价

Thariq列举了曾经的系统提示词：

In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max. Don’t create planning, decision, or analysis documents unless the user asks for them — work from conversation context, not intermediate files.

这条规则看起来很合理——避免AI写无用注释、避免生成多余文档。但Thariq承认：

For a certain subset of prompts, this guidance would be wrong. In the case of documentation, the user may have their own preferences, or specific parts of very complex code might need multi-line comment blocks.

这是over-constraining的典型模式——用一条全局规则防御一种失败模式，但这条规则本身在另一个场景下就是错的。老模型没有judgement区分场景，所以需要全局规则；新模型有judgement，全局规则反而成了阻碍。

新版系统提示词变成了：

Write code that reads like the surrounding code: match its comment density, naming, and idiom.

关键转变：从”全局规则”到”上下文judgement”——让模型观察周围代码的风格并匹配。这条新规则更短、更通用、更不容易与其他规则冲突。

1.3 模型能力演进的拐点

Thariq的发现不是孤立的——它是第十五篇讨论的”模型能力与流程复杂度的反向关系”的强力佐证。第十五篇提出：

模型能力越强，流程可以越简单；模型能力越弱，流程需要越复杂来补偿。但这个关系有一个关键限制——流程不能弥补模型能力的不足。

Thariq的实验给出了这个反向关系的一个具体数据点：当模型从Claude 3代际演进到Claude 5代际时，80%的约束可以被删除。这不是渐进式的简化，而是阶跃式的拐点。

第十五篇还提到一个区分：

流程可以补偿模型能力的”习惯性不足”（如不运行验证、跳过探索），但不能补偿模型能力的”能力性不足”（如无法判断业务风险、无法做跨task结构性思考）。

Thariq的发现进一步细化了这个区分——许多我们以为是”习惯性不足”的失败模式（如写无用注释、生成多余文档），在新模型上其实是”能力性已足”——它们有了judgement，不再需要规则来代为决策。这意味着许多我们以为必要的约束，其实是给”已经能判断的模型”戴上”防止它不能判断”的枷锁。

2. Then vs Now：6个转变对我们的启发

Thariq文章的核心是6个Then→Now的转变。本节把这6个转变对照我们前文的项目分析，讨论每一个转变对流程设计的启发。

2.1 Rules → Judgement：Rationalization表的边界

Superpowers的Rationalization表是”Rules”范式的极致——它列出AI逃避流程的所有借口，每个借口附”现实对照”：

• “should work now” → RUN the verification
• “I’m confident” → Confidence ≠ evidence
• “Agent said success” → Verify independently

我们在第十四篇评价：”Rationalization表可能是最有效的单一技巧——它直接针对AI最常见的失败模式（自我合理化）。”这个评价在Claude 3代际是成立的——老模型确实会”自我合理化”跳过验证。

但Thariq的发现提出了一个问题：Claude 5代际是否还会”自我合理化”？ 如果新模型的judgement足够好，它不需要一张”借口对照表”来识别”should work now”是逃避——它自己能识别。

实践方向：Rationalization表不是要全盘否定，而是要分场景。对于”模型能力性不足”导致的失败（如无法判断业务风险），Rationalization表无效，需要人工介入。对于”模型习惯性不足”导致的失败（如不运行验证），Rationalization表有效，但应该定期评估——随着模型演进，哪些条目可以从表中删除？Superpowers的94% PR拒绝率是高质量的标志，但也意味着它的约束可能比当前模型需要的更重。

2.2 Examples → Interface Design：mattpocock的example-heavy skill如何调整

Thariq说：

The number one rule for tool usage was to give Claude examples on how to use them. With our newest models, we’ve found that giving examples actually constrains them to a certain exploration space.

Thariq给出的例子是Todo工具——不靠example，而是靠status枚举（pending/in_progress/completed）和”keep one item in_progress”的接口设计，让模型自己推断用法。

这跟我们在第十一篇讨论的mattpocock的”reference-only TDD”是同一个方向——mattpocock明确不提供step-by-step workflow，依赖”AI内化的TDD精神”。但mattpocock的其他skill（如grill-me、to-tickets）仍然是example-heavy的。

关键洞察：从”Examples”到”Interface Design”的转变，要求我们重新思考skill的设计单位。前文的skill大多以”指令+示例”为单位——告诉模型做什么，给出几个例子。Thariq建议的设计单位是”接口契约”——定义参数空间、状态枚举、不变量，让模型在接口约束下自由探索。

这对我们前文的”行为塑造”范式是个修正——行为塑造不只可以通过”写指令”实现，也可以通过”设计接口”实现。后者的优势是：接口契约比自然语言指令更精确、更难冲突、更容易演进。Superpowers的File Handoffs机制（task-brief、report、review-package通过文件传递）其实已经隐含了这个方向——文件格式就是接口契约。

2.3 Upfront → Progressive Disclosure：gstack的preamble可以瘦身

Thariq说：

Since then, Claude Code has gotten very competent at using progressive disclosure- loading the right context at the right times. For example, we moved verification and code review into their own skills that Claude Code could selectively call.

这跟我们在第十二篇讨论的gstack的preamble形成对比——gstack在每个skill开始时注入Context Recovery，但这增加了token消耗。Thariq的发现表明，新模型可以可靠地”在需要时主动加载”上下文，而不需要”在开始时全部注入”。

更值得注意的是Thariq提到的”deferred loading”工具——agent必须通过ToolSearch才能找到工具的完整定义：

Some of our tools are ‘deferred loading,’ which means the agent must search for their full definitions using ToolSearch before using them. This allows us to have more tools (such as our Task tools) that don’t take up context until they’re needed.

这是一个比skill化更彻底的progressive disclosure——工具本身也可以deferred loading。我们前文讨论的”skill化”是把指令从system prompt抽到skill文件，deferred loading是把工具从tool列表抽到搜索空间。两者方向一致：减少默认加载，按需展开。

实践方向：gstack的preamble（每个skill开始时注入Context Recovery）在新模型上可能可以瘦身——只保留”当前skill产出物”和”上游skill关键决策”的指针，其余依赖agent主动查询。ECC的67个agents已经是这个方向——它们是”素材库”而非”流程步骤”，按需调用。

2.4 Repeat → Simple Tool Descriptions：重复约束的清理

Thariq说：

Earlier Claude models could sometimes need repeated instructions or be more likely to listen to instructions at the end of their context window than at the start. This meant our system prompt would sometimes have references to tools in the main system prompt as well as instructions in the tool description. We found we could delete these repeat examples and put instructions on how to use tools in the tool descriptions rather than the system prompt.

这跟我们在第十三篇讨论的gstack的21步ship流程形成对比——gstack的anti-footgun rules”永远不要在有非WIP commit时盲目 git reset --soft“在Step 15、Step 15.0、Step 15.1、历史踩坑表四个地方重复出现。我们当时评价这是”防御性设计”，但Thariq的发现表明——新模型不需要重复约束，重复反而增加冲突的可能。

实践方向：约束应该有”唯一归属地”——一条约束只在一个地方定义（system prompt / skill / tool description / CLAUDE.md），其他地方最多用指针引用。gstack的21步流程中，Step 15的anti-footgun rule与Step 15.0、Step 15.1的内容高度重叠——在新模型上可以合并为单一定义，其他地方只引用step编号。

2.5 CLAUDE.md Memory → Auto-memory：流程的”记忆节点”被产品接管

Thariq说：

We used to encourage users to save things to Claude’s memory, by using the # hotkey to write to their CLAUDE.md automatically. Instead, Claude now automatically saves memories that are relevant to the work and to you.

这是一个我们前文没有充分讨论的维度——记忆管理。我们的7节点框架（Explore → Spec → Plan → Execute → Review → Verify → Archive）是行为流程，没有把”记忆”作为独立节点。但前文多个项目都涉及记忆：

• ECC的Continuous Learning v2（instinct-based learning with confidence scoring）
• gstack的 /learn 命令（cross-session learnings）
• mattpocock的CONTEXT.md（ubiquitous language）
• Superpowers的Progress Ledger（抗context compaction）

这些都是”用户手动管理”或”工具辅助半自动管理”的记忆。Thariq的发现表明，记忆管理正在从”流程的一部分”变成”产品的内置能力”——Claude Code自动判断什么值得记、自动保存。

关键洞察：这暗示我们7节点框架的一个盲区——记忆是横切所有节点的支撑能力，不是独立节点，但也不是可有可无的附属品。当模型能力 + 产品能力（auto-memory）足够好时，记忆节点可以从流程中”隐式化”——agent自己管理，不需要流程显式规定”何时记、记什么”。但在那之前，记忆仍然是流程需要显式处理的问题。

2.6 Simple Specs → Rich References：spec形态的扩展

Thariq说：

We’ve found that Claude can handle increasingly more complicated references. Instead of simple markdown files, Claude can reference HTML artifacts created by our new artifacts feature. You may also give Claude references in the form of code. A spec may also be a detailed test suite, or a function in a different codebase that Claude might port.

这是对第九篇Spec节点讨论的重要补充。我们在第九篇主要讨论了OpenSpec的结构化spec（### Requirement: + #### Scenario: + RFC 2119）和mattpocock的CONTEXT.md——这些都是markdown格式。

Thariq指出spec可以是更丰富的形态：

• HTML mockup：优于描述或截图，因为是高保真指令
• Test suite：测试本身就是spec——“测什么”定义了”做什么”
• Code in other codebase：让Claude port一个已有函数
• Rubrics：动态工作流 + verifier agent用rubric校验taste

关键洞察：spec不是”用自然语言描述需求”——spec是”任何能让Claude高保真理解意图的载体”。代码比自然语言更精确，mockup比描述更具体，rubric比自由评测更可验证。这跟我们在第九篇对OpenSpec的”结构化spec”评价形成有趣的对话——结构化spec的优势不是”格式化了”，而是”接近代码的可执行性”。

实践方向：Spec节点的产出物应该按”保真度”排序选择——优先代码 > 测试 > mockup > 结构化spec > 自然语言spec。当可以用现有代码或测试作为spec时，不需要再写自然语言spec。这跟Bun案例（第十六篇）中”用Rust测试套件作为Zig→Rust迁移spec”的实践一致。

3. Context Engineering作为流程的新维度

3.1 7节点框架的盲区

第七篇定义了7个通用节点（Explore → Spec → Plan → Execute → Review → Verify → Archive），后续六篇逐个节点深入分析。但Thariq的文章揭示了一个我们遗漏的维度——Context Engineering。

Thariq说：

But when you send a message to Claude, the prompt is only a small part of the context it gets. Much of your context is assembled from your system prompt, Skills, CLAUDE.md files, memory, and other sources. We call this context engineering, and it makes a big impact on the results you generate when using Claude Code or in building your own agents.

Context Engineering不是7节点之一——它是横切所有节点的支撑维度。每个节点的执行都依赖context：Explore需要context理解现有系统，Spec需要context理解需求背景，Execute需要context理解plan，Review需要context理解标准。但context本身不是节点产出物，而是节点执行的前提。

我们在第十四篇讨论过”Context管理”作为独立章节，但当时主要讨论的是”context window的容量管理”（File handoffs、Continuous Checkpoint、subagent隔离）——这是容量视角。Thariq的Context Engineering是更广的视角——包括容量管理，但更核心的是”在context中放什么、不放什么、什么时候放”。

关键洞察：7节点框架回答”做什么”，Context Engineering回答”用什么信息做”。两者正交——同一个节点可以用不同的Context Engineering策略执行。比如Execute节点，可以一次性加载所有plan + spec + 相关代码（upfront），也可以按task逐步加载（progressive disclosure）。前者context丰富但易冲突，后者context精简但需要模型主动查询。

3.2 Context Engineering与7节点的关系

Context Engineering不是替代7节点，而是7节点的”第二轴”。可以用一个二维框架理解：

1
2
3
4
5
6
7
8
9
10
11

                Context Engineering策略
                (upfront) ←─────────────→ (progressive disclosure)
                ↑
        Explore |    高保真但易冲突         |    按需加载现有系统信息
        Spec    |    一次性加载全部需求     |    按issue逐步澄清
        Plan    |    一次性加载全部spec     |    按task逐步细化
7节点   Execute |    一次性加载全部plan     |    按task逐步加载
        Review  |    一次性加载全部代码     |    按diff范围加载
        Verify  |    一次性加载全部测试     |    按变更影响加载
        Archive |    一次性加载全部历史     |    按合并需求加载
                ↓

5个项目在这个二维框架中的位置：

• Superpowers：偏upfront——HARD-GATE要求在Spec阶段就完整定义，File Handoffs一次性传递artifact
• OpenSpec：偏progressive disclosure——Artifact Graph支持任意阶段修改任意artifact，CLI按需查询
• gstack：偏upfront——preamble在每个skill开始时注入Context Recovery
• mattpocock：偏progressive disclosure——skill小而可组合，用户按需调用
• ECC：偏progressive disclosure——67个agents按需选择，不全部加载

实践方向：随着模型能力演进（Thariq揭示的judgement提升），Context Engineering的最优策略正在从upfront向progressive disclosure移动。但移动速度因节点而异——Spec节点可能仍需要相对upfront（需求理解需要全局上下文），Execute节点更适合progressive disclosure（按task加载减少冲突）。

3.3 新维度的实践原则

综合Thariq的建议和前文的项目分析，Context Engineering的实践原则可以归纳为4条：

原则1：约束最小化

• 删除任何”防御一种失败模式但在另一场景下是错的”的全局规则
• 用”match the surrounding code”代替”DO NOT add comments”——让模型用judgement而非规则
• 定期评估约束的必要性——随着模型演进，哪些约束可以删除？

原则2：Progressive Disclosure

• system prompt只放产品上下文（”这是Claude Code，你在做编码”）
• skill放特定领域知识，按需加载
• CLAUDE.md只放”gotchas”——避免陈述”obvious”的事物
• 工具deferred loading——通过ToolSearch按需发现

原则3：接口优于示例

• 工具设计优先考虑参数空间和状态枚举，而非示例
• skill设计优先考虑”接口契约”（输入、输出、不变量），而非step-by-step示例
• 当模型judgement足够时，接口约束比示例约束更鲁棒

原则4：Reference形态多样化

• spec不一定是markdown——可以是代码、测试、mockup、rubric
• 优先高保真reference：代码 > 测试 > mockup > 结构化spec > 自然语言
• @mention文件作为reference，让模型直接读取而非通过描述传递

4. 对前文项目的重新检视

4.1 Superpowers：行为塑造范式的边界

我们在第十四篇评价Superpowers：”强制程度最高——agent被’绑定’到流程中。代价：简单变更也走完整流程（过重）；skill触发率约50-80%（不如hook 100%）。”

Thariq的发现补充了一个新的代价维度——Rationalization表本身的认知负担。当模型需要先”判断该听哪条rationalization对照”再”做实际决策”时，它的有效推理能力被消耗在元层面。对于Claude 3代际，这种消耗是必要的——模型不识别”should work now”是逃避，所以需要对照表。但对于Claude 5代际，这种消耗可能成为负担——模型能识别，对照表反而让它在”是不是该查表”上犹豫。

修正：Superpowers的Rationalization表不是错误——它是特定模型能力下的合理设计。但它的演进方向应该是逐步瘦身——定期评估哪些条目在新模型上已经”内化”，可以从表中删除。Superpowers的eval体系（drill harness + 压力测试）正好可以做这件事——在新模型上跑eval，如果删除某条rationalization后eval通过率不降，就可以删除。

4.2 gstack：21步流程的简化空间

我们在第十三篇详细分析了gstack的21步ship流程，注意到它有大量重复约束（Step 15、Step 15.0、Step 15.1、历史踩坑表四处重复anti-footgun rules）。

Thariq的发现表明，这些重复在新模型上可以大幅简化：

• 重复约束合并：anti-footgun rules只在一处定义（建议在Step 15主体），其他地方只引用”见Step 15”
• Rules→Judgement：部分”永远不要X”的规则可以改为”在X情况下，根据Y判断”——让模型用judgement而非遵守绝对禁令
• Examples→Interface：Step 9的specialist dispatch（security变更触发Security Officer等）可以改为接口设计——变更类型枚举 + reviewer映射表，让模型自己推断

但gstack的简化空间是有限的——它的21步流程中，许多步骤是机械化操作（如Step 12 version bump、Step 13 CHANGELOG生成），这些不依赖模型judgement，约束简化对它们无效。

修正：gstack的21步流程不是”过度约束”，而是”约束集中在错误的地方”。机械步骤（version、changelog、push、PR创建）的详细约束是必要的——它们不消耗模型judgement，只消耗执行步骤。可以简化的是判断性步骤的约束（如Step 9 specialist dispatch、Step 11 adversarial review）——这些步骤依赖模型judgement，约束过重反而阻碍。

4.3 ECC：素材库vs约束库

我们在第四篇和第十四篇评价ECC：”覆盖最广但深度最浅——261+ skills但不定义流程约束。”

Thariq的发现表明，ECC的”不定义流程约束”可能反而是符合演进方向的——当模型judgement足够好时，提供素材让模型按需调用比定义流程让模型遵守更有效。ECC的67个agents已经是”deferred loading”的实践——它们不全部加载，按需选择。

但ECC的局限也很明显——它的skills本身仍然是”Rules + Examples”范式，没有转向”Interface Design”范式。ECC的演进方向应该是：保留素材库的灵活性，但将每个skill的内部设计从”指令+示例”转向”接口契约+不变量”。

修正：ECC的”素材库不定义流程”不是缺陷，而是符合Context Engineering方向的设计选择。但素材本身的形态需要演进——从”行为塑造skills”到”接口契约skills”。

4.4 OpenSpec：Artifact治理的优势显现

我们在第二篇和第十四篇评价OpenSpec：”强制程度中等——工具验证artifact格式但不阻断用户行动。”

Thariq的发现让OpenSpec的Artifact治理范式显示出独特优势——Artifact本身就是接口契约。OpenSpec的spec格式（### Requirement: + #### Scenario: + RFC 2119关键词）是一种”接近代码的接口契约”——它比自然语言spec更精确、更难冲突。OpenSpec的Delta机制（ADDED/MODIFIED/REMOVED/RENAMED）是状态枚举——比”修改spec”的自然语言指令更鲁棒。

这跟Thariq的建议”Interface Design优于Examples”完全一致——OpenSpec的整个设计就是Interface Design范式。它的spec不是”给Claude看的自然语言描述”，而是”程序可解析的结构化契约”——validator可以程序化检查，archive可以程序化合并。

修正：OpenSpec的Artifact治理范式在Context Engineering时代显示出独特价值——它本身就是Thariq建议的”Interface Design”方向。前文对OpenSpec”编写成本高”的评价仍然成立，但需要补充：”编写成本高”的代价换来的是”约束冲突少、可程序化验证”的优势——这个交易在模型judgement提升、约束简化的大趋势下越来越划算。

5. 简化的勇气：流程迭代的启示

5.1 删除80%无损失是一个强信号

Thariq的80%瘦身不是渐进式的”减少10%”——而是阶跃式的”删除80%”。这种简化幅度在工程实践中罕见——大多数简化是渐进的，因为不敢一次删太多。

Anthropic敢于删除80%的底气来自他们的eval体系——编码评测可以量化验证”无损失”。这跟我们在第十五篇讨论的Superpowers的eval方法（drill harness + 压力测试 + 94% PR拒绝率）是同一思路——简化的前提是可衡量。

关键洞察：流程简化的最大障碍不是”不知道什么可以删”，而是”不敢删”——担心删除后出现问题。这种担心只能用eval数据消除。没有eval体系的简化是赌博，有eval体系的简化是工程。

5.2 简化的判断标准

综合Thariq的发现和前文分析，可以提炼简化的判断标准：

可以简化的约束：

• 防御”模型习惯性不足”的规则——当模型judgement提升后，这些规则成为负担
• 重复定义的约束——只在一处保留，其他改为引用
• 与其他约束冲突的规则——任选其一，删除其他
• 防御”已不存在的失败模式”的规则——老模型的失败模式在新模型上不出现

不应简化的约束：

• 防御”模型能力性不足”的规则——业务风险判断、跨task结构性思考，这些模型judgement仍不足
• 机械步骤的约束——version bump、changelog生成等不依赖judgement的步骤
• 程序化验证的约束——validator、delivery-gate hook等确定性检查
• 安全相关的约束——credential检查、文件删除保护等

判断方法：用eval体系量化——删除约束前后跑eval，通过率不降则可删。没有eval的约束简化只能凭经验判断，风险较高。

5.3 claude doctor的启发：自动化简化

Thariq提到了一个新命令——claude doctor，用于自动rightsizing skills和CLAUDE.md文件：

We rolled out a new command called claude doctor, which will help you do this automatically as well.

这是一个有趣的方向——简化本身也可以工具化。前文的5个项目都有”约束膨胀”的倾向（Superpowers的24 failure memories持续积累、gstack的21步流程逐步加step、ECC的261+ skills持续增长），但没有项目提供”简化工具”——简化都依赖人工评审。

claude doctor的启发是：简化可以是程序化的——分析CLAUDE.md和skill文件，识别重复约束、冲突约束、过时约束，建议删除。这跟OpenSpec的validator是同一思路——程序化检查比人工评审更确定。

实践方向：流程工具链应该包含”简化工具”——不只是”添加约束”的工具（如validator、delivery-gate），还要有”删除约束”的工具（如doctor）。前者防止约束不足，后者防止约束过度。两者缺一不可。

6. 对第十四篇综合方案的修正

6.1 约束机制章节的更新

第十四篇2.1节提出了三种流程控制范式（行为塑造、Artifact治理、Sprint链式），并评价行为塑造”强制程度最高”。

修正：增加第四种范式——Interface Design（接口契约）。这种范式不通过指令塑造行为，也不通过artifact治理流程，而是通过设计接口（参数空间、状态枚举、不变量）约束模型行为。Thariq的Todo工具示例（status枚举 + “keep one item in_progress”）是这种范式的典型。

Interface Design范式的特征：

• 强制程度中等——接口约束明确，但模型在接口内有judgement空间
• 工具依赖——需要程序化解析接口契约
• 关键设计：参数枚举、状态机、不变量、类型约束
• 代价：接口设计本身需要工程能力；不适用于所有约束（如”运行验证”难以接口化）

4种范式的演进关系：随着模型judgement提升，最优范式从行为塑造 → Sprint链式 → Artifact治理 → Interface Design移动。但不是替代关系——不同节点适合不同范式。Spec节点适合Artifact治理（结构化spec），Execute节点适合行为塑造（TDD Iron Law），Archive节点适合Interface Design（接口化合并操作）。

6.2 Context Engineering作为新增维度

第十四篇2.4节讨论了”纯Markdown vs工具强制的tradeoff”，但没有把Context Engineering作为独立维度。

修正：增加Context Engineering作为流程设计的第二轴。流程设计不只是”做什么节点”（7节点框架）和”用什么约束”（约束机制），还包括”用什么context策略”（Context Engineering）。三者正交：

• 7节点框架：行为流程的时序——Explore → Spec → … → Archive
• 约束机制：行为流程的控制——行为塑造 / Artifact治理 / Sprint链式 / Interface Design
• Context Engineering：行为流程的信息——upfront / progressive disclosure / deferred loading

完整流程设计需要三个维度都做选择。比如OpenSpec：7节点 + Artifact治理 + progressive disclosure。Superpowers：7节点 + 行为塑造 + upfront（HARD-GATE要求前置定义）。Claude Code新设计：7节点 + Interface Design + progressive disclosure。

6.3 简化原则的强化

第十四篇的”实践方向”中提到了”流程的自然倾向是膨胀，需要主动简化”（来自第十五篇的观察4），但没有把简化作为独立原则。

修正：将简化提升为流程设计的第一原则——任何约束的添加都应该附带eval基线，定期评估是否可以删除。这跟Thariq的claude doctor思路一致——简化不是一次性活动，而是持续过程。

具体原则：

• 添加约束时记录eval基线——后续可以量化评估约束的必要性
• 定期跑eval评估约束——删除通过率不降的约束
• 约束必须有”唯一归属地”——避免重复定义
• 新模型发布时优先评估约束简化——模型能力拐点是简化窗口

7. 结论

Thariq的80%瘦身实验是本系列的一个重要外部参照点。它不否定前17篇的分析——前文的项目都基于当时的模型能力设计，约束在当时是必要的。但它揭示了模型能力演进后流程设计需要调整的方向：

调整1：约束的代价不只是context容量，还有认知负担。多条约束重叠或冲突时，模型消耗有效推理能力在”判断该听哪条”上。简化约束不只是释放context，更是释放judgement。

调整2：Context Engineering是流程设计的第二轴。7节点框架回答”做什么”，约束机制回答”用什么控制”，Context Engineering回答”用什么信息”。三者正交，完整流程设计需要三个维度都做选择。

调整3：Interface Design是约束机制的新范式。除了行为塑造、Artifact治理、Sprint链式，Interface Design通过设计接口（参数空间、状态枚举、不变量）约束模型——它在模型judgement提升后越来越有效。

调整4：简化是流程设计的第一原则。任何约束的添加都应该附带eval基线，定期评估是否可以删除。简化不是一次性活动，而是持续过程——claude doctor的启发是简化本身也可以工具化。

调整5：Reference形态多样化。spec不一定是markdown——可以是代码、测试、mockup、rubric。优先高保真reference——代码 > 测试 > mockup > 结构化spec > 自然语言spec。

需要强调的边界：Thariq的发现基于Claude 5代际模型——Opus 5、Fable 5。在Claude 3代际或同代模型上，前文的约束设计仍然成立。流程设计必须跟随模型能力演进——这本身就是第十五篇”模型能力与流程复杂度的反向关系”的实践印证。

本系列到此告一段落。17篇正文 + 本篇外部参照检视，覆盖了从全景扫描到逐节点深入、从综合方案到案例验证、从懒惰约束到Context Engineering的完整探索。流程设计没有终点——模型在演进，工具在演进，最佳实践也在演进。我们能做的，是建立”可衡量、可简化、可演进”的流程框架，让它随时代调整。

点击下方”阅读原文“进入我的演示网站。

一个用纯Markdown驱动AI agent行为的系统，是如何做到可靠执行的？每个设计决策背后的失败教训是什么？

1. 架构拆解

1.1 Skill文件结构

Superpowers的核心单元是 skill——一个标准目录结构：

1
2
3
4
5
6
7
8

skills/
  skill-name/
    SKILL.md              # 主参考文件（必需）
    supporting-file.*     # 辅助文件（按需）
    references/           # 平台适配引用
    scripts/              # 可执行工具
    implementer-prompt.md  # 子 agent 模板
    task-reviewer-prompt.md

每个SKILL.md由两部分组成：

• YAML Frontmatter：name 和 description 两个字段。description 只描述”何时触发”，不描述”做什么”——这是经过测试的刻意设计（详见2.2 Description Trap）。
• Markdown正文：包含Overview、When to Use、核心机制、Red Flags、Rationalization表等结构化段落。

writing-skills/SKILL.md 定义了skill的完整规范，包括目录结构、frontmatter规范、Skill Discovery Optimization（SDO）等。

1.2 Bootstrap机制

Superpowers的入口是 using-superpowers skill。它通过 SessionStart hook 在每次会话启动时注入到agent的上下文中。不同平台的注入方式有差异：

using-superpowers 的核心规则：

“Invoke relevant or requested skills BEFORE any response or action”

这意味着agent在回答用户的第一个问题之前，就必须检查是否有相关skill适用。这不是建议，是强制规则。

1.3 Skill引用关系

14个skill之间存在明确的依赖链：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

using-superpowers（入口）
    ↓
brainstorming（设计阶段）
    ↓
using-git-worktrees（隔离环境）
    ↓
writing-plans（任务拆解）
    ↓
subagent-driven-development / executing-plans（执行）
    ↕
test-driven-development（实现约束）
    ↓
requesting-code-review（审查）
    ↓
finishing-a-development-branch（收尾）

辅助skill：

• systematic-debugging：调试时的流程约束
• verification-before-completion：完成前的验证约束
• writing-skills：创建新skill的元skill

1.4跨平台适配

v6.0.0是一个关键里程碑：所有skill从Claude Code方言（”use the Task tool”、”put it in CLAUDE.md”）改为通用动作语言（”dispatch a subagent”、”your instructions file”），并添加了per-harness reference文件映射到具体工具。当前支持10个平台：Claude Code、Antigravity、Codex App、Codex CLI、Cursor、Factory Droid、GitHub Copilot CLI、Kimi Code、OpenCode、Pi。

2. Skill设计哲学

2.1 “Skills are Code”

writing-skills skill的核心论断：

“Writing skills IS Test-Driven Development applied to process documentation.”

这不是类比，是字面意义上的TDD：

每次创建或修改skill时，必须先跑baseline测试（看agent在没有skill时怎么失败的），再写skill，再验证agent是否遵守。writing-skills skill的Iron Law与TDD完全平行：NO SKILL WITHOUT A FAILING TEST FIRST。

2.2 Description Trap

v4.0.0发现的关键设计教训：当 description 字段包含workflow摘要时，agent会跟随description而不读取skill正文。例如，description写 “code review between tasks” 导致agent只做了一次review，而skill的flowchart明确要求两阶段review。

修复方案：description 只描述触发条件（”Use when…”），绝不包含workflow摘要：

1
2
3
4
5

# 错误：包含 workflow 摘要
description: Use when executing plans - dispatches subagent per task with code review between tasks

# 正确：只有触发条件
description: Use when executing implementation plans with independent tasks in the current session

Agent倾向于走捷径——如果一个短摘要看起来足够指导行动，它不会去读完整文档。这意味着 description 字段的Skill Discovery Optimization（SDO）和workflow指导功能必须分离：description负责”被发现”，正文负责”被遵守”。

2.3 Match the Form to the Failure

v6.0.0引入的设计模式选择框架：

关键发现： 禁令在”产出形状”问题上适得其反——head-to-head测试显示，禁令组比无引导的对照组产生了更多不需要的内容。原因是agent在竞争性激励下会与 “don’t X” 谈判。这意味着对AI agent的行为引导，不能简单套用人类的规则设计经验——“禁止做X” 对人类有效，但在某些场景下对AI可能产生反效果。

2.4 Micro-test Wording

v6.0.0引入的低成本措辞验证方法：

1. 每次调用一个fresh-context样本（raw API call或单次subagent）
2. 始终包含无引导对照组
3. 每个变体至少5次重复
4. 手动阅读每个匹配结果
5. 把方差视为度量指标——5次得到5种不同解读，说明措辞没有约束力

这是”测试驱动”理念在措辞层面的应用：在投入昂贵的完整压力场景之前，先验证措辞本身是否有约束力。

3. 关键设计模式

3.1 Iron Law（铁律）

三条Iron Law分布在三个skill中：

1. TDD：NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
2. Verification：NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
3. Writing Skills：NO SKILL WITHOUT A FAILING TEST FIRST

铁律的特点：

• 全大写——视觉上的强制感
• 无例外条款——不写”除非…”、”在特殊情况下…”
• 附带删除指令——“Write code before test? Delete it. Start over.”
• 堵住每一条退路——“Don’t keep it as reference”、”Don’t adapt it”、”Delete means delete”

铁律不是”最佳实践建议”，是”违反即失败”的硬约束。比如TDD铁律不只是说”先写测试”，还明确规定：如果先写了生产代码，删掉它，从测试重新开始——不允许”保留作为参考”、”适配一下”等退路。这种设计来自baseline测试的发现：agent在压力下会忽略”prefer…”、”should…”类的软建议，但对全大写、无例外的铁律compliance显著提高。Iron Law假设agent会寻找任何loopholes来绕过规则，因此必须显式封堵每一个。

3.2 Rationalization表

显式列出agent用来绕过规则的借口，并逐条反驳。以 using-superpowers skill为例：

这些rationalization不是凭空写的——每一条都来自baseline测试中agent实际使用的借口（verbatim记录）。v3.2.2添加了最初的8条，后续版本不断补充。每条借口旁边都附有直接反驳，这样当agent在压力下试图用某个借口绕过规则时，会在skill中看到这个借口已经被预判并反驳了。

3.3 Red Flags（红旗清单）

Rationalization表的”自查版”——不是”agent会说什么”，而是”如果你在想这些，停下来”。以TDD skill为例，其Red Flags列表包含：

1
2
3
4
5
6
7

- Code before test
- Test after implementation
- Test passes immediately
- Can't explain why test failed
- "I already manually tested it"
- "It's about spirit not ritual"
- "This is different because..."

两者的关键区别：Rationalization表是被动识别（看到agent说了才知道），Red Flags是主动自查（agent在行动前自己检查是否正在滑向违规）。比如”I know what that means”（我知道这是什么意思）是一个Red Flag——当agent想到这句话时，意味着它打算跳过skill加载直接行动。

3.4 HARD-GATE

brainstorming skill使用 <HARD-GATE> 标签阻止agent在设计批准前进入实现阶段：

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.

来自v4.3.0的失败模式：agent在brainstorming过程中一旦觉得”想清楚了”，就会跳过用户审批直接开始写代码（”skipping the design phase and jumping straight to implementation skills”）。v4.3.0的修复包含四个部分：<HARD-GATE> 标签、显式checklist（6项）、Graphviz process flow（以 writing-plans 为唯一合法终止状态）、以及anti-pattern callout（拦截”this is too simple to need a design”的借口）。

HARD-GATE解决的是”agent不认为需要进入流程”的问题——不同于Rationalization表（解决”agent知道规则但不遵守”），HARD-GATE解决的是”agent认为可以直接跳到实现”。

3.5 SUBAGENT-STOP

using-superpowers skill中的 <SUBAGENT-STOP> 标签：

If you were dispatched as a subagent to execute a specific task, ignore this skill.

子agent被分派执行特定任务时，不需要触发完整的skill检查流程。controller在dispatch subagent时会加上这个标签，告诉subagent直接执行任务指令。这避免了subagent被 using-superpowers 入口skill干扰——否则每个subagent都会花时间检查skill库，而它的任务只是执行一个具体的编码指令。

3.6持续执行（Continuous Execution）

subagent-driven-development skill的核心执行原则：

Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete.

用户要求执行计划，就执行完，不暂停询问”是否继续”。来自v5.0.0之前的失败模式：executing-plans skill每3个任务暂停一次询问”是否继续”，导致一个10个任务的计划需要用户确认3-4次。agent在等待用户确认时context不变，但用户一旦离开，整个session就卡住了。改为持续执行后，agent从第一个任务执行到最后一个任务，中间只在遇到BLOCKED、无法推进的歧义、或全部完成时才暂停。

3.7 Progress Ledger（进度账本）

v6.0.0引入的外部化记忆文件（.superpowers/sdd/progress.md），记录每个完成的任务。当agent的context被compaction（上下文压缩）截断时，已完成的任务信息会丢失，agent会从第一个任务重新开始执行——Superpowers称之为”the single most expensive failure observed”。Progress Ledger把任务状态写到磁盘文件中，compaction后agent重新读取ledger就能恢复进度，从上次中断处继续。

需要注意的是，ledger文件最初放在 .git/ 目录下，但Claude Code把 .git/ 视为保护路径，拒绝agent写入。v6.0.3将ledger移到 .superpowers/sdd/ 目录——这个目录不在 .git/ 中，但也不被git跟踪（.gitignore），因此 git clean -fdx 会删除它。

3.8 File Handoffs（文件交接）

v6.0.0引入的context管理策略，controller向subagent传递信息时，不用粘贴内容到dispatch prompt中，而是把信息写入临时文件，让subagent自行读取。具体包括三类文件交接：

一切粘贴到dispatch prompt中的内容都会永久驻留在controller的context中——真实session的dispatch曾达42k字符，其中99% 是之前任务的粘贴历史。文件交接让controller只保留文件路径而非文件内容，大幅减少context占用。

4. SDD演进（v4 → v5 → v6）

v4.0.0：两阶段review引入

引入spec compliance review + code quality review，解决”代码写得好但不匹配需求”的问题。两个review是独立的——spec compliance通过后才进行code quality review。

v5.0.0：SDD强制化

在支持subagent的平台上，subagent-driven-development从可选变为强制：

Writing-plans no longer offers a choice between subagent-driven and executing-plans. On harnesses with subagent support, subagent-driven-development is required.

同时移除了 executing-plans 的batch模式（每3个任务暂停一次），改为连续执行。SDD被证明比inline execution更可靠——fresh context per task避免了context pollution，自动review避免了人为跳过。

v6.0.0：SDD大重写

“cheaper, stricter, and harder to game”：

结果：约2倍速度、50% 更少token。

v5.0.6：Inline Self-Review替代Subagent Review Loop

25分钟的subagent review loop被证明无效（5个版本 × 5次试验的回归测试显示质量分数无差异），30秒的inline checklist达到了相同效果。具体变更：

• brainstorming：subagent dispatch + 3-iteration cap → inline checklist（placeholder scan、consistency、scope、ambiguity）
• writing-plans：subagent dispatch + 3-iteration cap → inline self-review checklist

这一决策表明：不是所有”看起来更严谨”的流程都真的有效。流程的简化需要基于实证数据，而非”感觉差不多”。

5. 测试方法论

5.1 Skill测试即TDD for Documentation

Skill是一份Markdown文档，但它的作用不是提供信息，而是约束agent行为。如果agent读了skill但行为没变，skill就等于没写。因此skill测试的目标不是”文档写得对不对”，而是”agent读了这个文档后，行为有没有改变”。

Superpowers在 testing-skills-with-subagents.md 中将这一思路概括为TDD在文档领域的直接应用：

Testing skills is just TDD applied to process documentation.

If you didn’t watch an agent fail without the skill, you don’t know if the skill prevents the right failures.

具体做法是把TDD的RED-GREEN-REFACTOR循环搬到skill文档上：

跳过RED阶段直接写skill，意味着你只是在解决”你想象中的问题”，而不是”agent实际会犯的错误”。只有先看过agent在没有skill的情况下怎么失败、用什么借口，才能针对性地设计反制条款。

5.2 Drill Eval Harness

RED-GREEN-REFACTOR循环如果纯手工执行，成本极高——每个skill要跑多个场景、每个场景要跑多次、每次都要人工读agent的完整输出并判断是否合规。v6.0.0之前，这些测试放在 tests/ 目录里，依赖人工执行和人工判断，导致测试跑得少、判断不一致、无法回归。

v6.0.0将测试迁移到 evals/ 子模块，构建了 “drill” 自动化评估工具链：

drill把”agent是否遵守skill规则”从人工主观判断变成了可重复、可量化、可回归的自动化测试。

5.3压力测试

Superpowers在测试中发现了一个关键现象：agent在没有压力的”学术题”中表现完美——能背诵规则、能解释为什么。但一旦施加压力，agent会立刻找各种借口绕过规则。测试的核心不是”agent知不知道规则”，而是”agent想不想遵守规则”。只有制造让agent想违规的场景，才能测出skill是否真的有效。

Superpowers在 testing-skills-with-subagents.md 中定义了七种压力类型，其中四种最常用：

另外三种较少使用的压力类型：Economic（经济压力——工作/晋升/公司存亡）、Social（社交压力——显得教条/不灵活）、Pragmatic（实用主义压力——“务实而非教条”）。

单一压力下agent通常能坚持规则，但3+ 种压力叠加时，agent几乎总是能rationalize出违规理由：

Best tests combine 3+ pressures.

好的压力场景需要同时组合多种压力，并强制agent做出明确选择。对比来看：

好的场景有几个关键设计要素：

1. Concrete options - Force A/B/C choice, not open-ended
2. Real constraints - Specific times, actual consequences
3. Make agent act - “What do you do?” not “What should you do?”
4. No easy outs - Can’t defer to “I’d ask your human partner” without choosing

即给具体选项而非开放问答、用真实约束（具体时间、具体金额）、让agent “做”而非”说”、堵住”我会问partner”这种逃避路线。

在RED-GREEN-REFACTOR循环中，REFACTOR阶段的关键操作是逐字记录agent的新借口，因为这些借口会成为skill中的rationalization表（显式列出每个借口和对应的反驳）：

• “This case is different because…”
• “I’m following the spirit not the letter”
• “Being pragmatic means adapting”
• “I already manually tested it”

每发现一个新的rationalization，就在skill中添加一条针对性的反制条款，然后重测——直到agent在最大压力下也无法绕过规则。以TDD skill本身的测试为例（2025-10-03真实记录）：经历了6轮RED-GREEN-REFACTOR迭代，基线测试发现了10+ 种独特的rationalization，每轮REFACTOR关闭特定漏洞，最终在最大压力下达到100% 合规。

5.4 94% PR拒绝率

v5.1.0引入了AI agent贡献者指南（CONTRIBUTING.md中的AI agent规范），基于一个对自身仓库的审计结果：

An audit of the last 100 closed PRs against this repo showed a 94% rejection rate driven by AI-generated slop: agents that didn’t read the PR template, opened duplicates, fabricated problem descriptions, or pushed fork- or domain-specific changes upstream.

这94% 的拒绝不是因为代码质量问题，而是因为AI agent的基本行为规范缺失：

这个数字揭示了Superpowers整个行为约束体系的出发点——未经约束的AI agent在真实开发场景中不仅产出质量低，而且会主动制造噪声（重复PR、虚假描述）。这不是”AI不够聪明”的问题，而是”AI没有行为约束”的问题。Superpowers后续所有的skill设计、压力测试、rationalization防御，都是对这一审计结果的回应：问题不是让AI更能干，而是让AI更守规矩。

这个审计发生在Superpowers自身的仓库上——一个专门研究AI agent行为约束的项目，自身就是AI agent不受约束时破坏力的受害者。这赋予了后续所有设计决策一种”从真实pain中长出来”的可信度。

6. 演进中的关键教训

模式： 流程复杂度的振荡——从简到繁，从繁到简，最终在”够用且不跳过”的平衡点稳定。

7. 能力边界

• 平台依赖：可靠性高度依赖平台的hook机制。using-superpowers 通过SessionStart hook注入，如果平台不支持hook或hook被禁用，skill的触发率从接近100% 降到50-80%——agent可能根本不知道skill库的存在
• 单一agent模型假设：整个流程基于controller + subagent架构，controller负责拆任务和dispatch，subagent负责执行。不支持subagent的平台（如纯对话式AI）无法使用SDD流程，只能降级为单agent直接执行
• Skill粒度不均：14个skill中，有些是通用工程实践（TDD、code review），有些是Superpowers特有的流程约束（HARD-GATE、SUBAGENT-STOP）。后者在其他项目中的适用性需要单独评估，不能直接照搬
• 不处理需求管理：brainstorming skill假设用户已经知道要做什么，只是帮用户把模糊想法变成明确设计。如果用户连”要做什么”都不清楚，brainstorming无法帮用户做需求发现——这一步需要用户自己完成
• Greenfield导向：核心流程从空目录开始设计——brainstorming → plan → execute。对于已有大量代码的存量项目，brainstorming阶段的”从零设计”假设不成立，需要适配为”理解现有架构再做增量变更”的模式

8. 设计决策清单

点击下方”阅读原文“进入我的演示网站。

一个覆盖261+ skills、跨7+ 平台的素材库，是如何组织和管理如此庞大的素材体系的？它选择不定义流程的考虑是什么？

1. 架构拆解

1.1素材分类体系

ECC（Enterprise Claude Code）的自我定位是 “the agent harness operating system”——一个跨harness的agent操作系统。它的架构不是围绕一个工作流设计的，而是围绕素材供给设计的。

1
2
3
4
5
6
7
8
9
10
11
12
13

ECC/
├── skills/           # 261+ 工作流定义和领域知识（主工作面）
├── agents/           # 67 个专门化 subagent（委托执行）
├── commands/         # 94 个 slash command shim（迁移兼容层）
├── hooks/            # 事件驱动自动化（6 种 hook 类型）
├── rules/            # Always-follow 规则（按语言组织）
├── contexts/         # 动态 system prompt 注入（dev/review/research 模式）
├── scripts/          # 跨平台 Node.js 脚本
├── tests/            # 测试套件（997+ 个内部测试）
├── examples/         # 示例配置
├── mcp-configs/      # MCP 服务器配置
├── schemas/          # 数据 schema 定义
└── config/           # 配置文件

README.md 明确描述了素材分类——Skills是”primary workflow surface”，Commands是”legacy slash-entry compatibility during migration”，Agents是”specialized subagents for delegation”。

ECC的素材分为五层，每层有明确的职责边界：

设计考虑： 五层分离使得每层可以独立演化——Skills可以从Commands迁移而不影响Hooks，Rules可以按语言选择性安装。但代价是用户需要理解五层之间的关系，新用户面临陡峭的学习曲线。

1.2 Frontmatter体系

ECC使用YAML frontmatter标注每个素材的元数据：

Skill frontmatter:

1
2
3
4
5
6
7

---
name: continuous-learning-v2
description: Instinct-based learning system...
metadata:
  origin: ECC
version: 2.1.0
---

Agent frontmatter:

1
2
3
4
5
6

---
name: planner
description: Expert planning specialist...
tools: ["Read", "Grep", "Glob"]
model: opus
---

origin 字段区分 ECC（第一方）和 community（社区贡献），使得素材来源可追溯。Agent的 tools 字段实现了权限隔离——planner只有Read/Grep/Glob权限，不能修改文件。model 字段指定agent使用的模型层级。

RULES.md 定义了素材格式规范——Agent文件名必须与name一致、Skills必须包含 “When to Use” 段落、Hooks应使用具体的matcher而非通配符。

1.3安装管线

ECC v1.9.0引入了 manifest-driven selective install 架构：

1
2
3

用户表达需求 → npx ecc consult "security reviews" → 匹配组件
 install-plan.js 生成安装计划 → install-apply.js 执行安装
 SQLite 状态存储记录已安装组件 → 支持增量更新

三种安装Profile:

设计考虑： Selective install解决了261+ skills带来的”context window污染”问题。the-shortform-guide.md 明确警告：”你的200k context window在compaction前可能只有70k——太多tools启用会导致性能显著下降。” 建议保持 < 10个MCP启用、< 80个tools活跃。

取舍： Selective install给了用户精细控制，但增加了配置复杂度。用户需要知道”我需要哪些skills”，这对新手不友好。npx ecc consult 命令试图缓解这个问题，但本质上ECC假设用户知道自己需要什么。

1.4跨平台适配层

ECC支持Claude Code、Cursor、Codex (CLI + App)、OpenCode、Gemini、Zed、GitHub Copilot等7+ AI harness：

跨平台实现策略：

1. 所有hooks和scripts用Node.js重写——不再依赖bash，确保Windows/macOS/Linux行为一致
2. Package manager自动检测——优先级：env var → project config → package.json → lock file → global config → fallback
3. Agent data home隔离——ECC_AGENT_DATA_HOME 环境变量让不同harness的数据互不干扰

v1.8.0将ECC重新定位为 “agent harness performance system, not just a config pack”。跨平台是ECC的核心优势之一——不绑定特定AI工具，用户可以自由选择。代价是维护成本——997+ 个内部测试反映了这个成本。

2. 素材组织哲学

2.1 “提供素材不定义流程”

ECC的核心设计理念：提供261+ skills、67 agents、94 commands，让用户自己组装工作流。没有强制流程、没有阶段门禁、没有工作流引擎。

the-shortform-guide.md 的描述最清楚：

“Skills are the primary workflow surface. They act like scoped workflow bundles: reusable prompts, structure, supporting files, and codemaps when you need a particular execution pattern.”

Skills是”独立的、可复用的工作流包”，而不是”工作流的一个阶段”。

设计考虑： ECC认为不同项目、不同团队、不同任务需要不同的工作流组合。强制一个固定流程会过重或过轻。提供素材让用户按需组装，比定义一个”one-size-fits-all”的流程更灵活。

取舍： 极大的灵活性带来了极大的发现成本——261+ skills中找到合适的那个并不容易。ECC的应对是：

1. Commands作为skills的”slash入口”（如 /tdd → tdd-workflow skill）
2. npx ecc consult 帮助发现匹配组件
3. Skills目录按领域命名（如 django-tdd、laravel-tdd、springboot-tdd）

2.2分类体系与检索

ECC的skills目录按领域组织，而非按工作流阶段：

1
2
3
4
5
6
7
8
9

skills/
├── 框架/语言 patterns:  django-patterns/, laravel-patterns/, springboot-patterns/, golang-patterns/, ...
├── 测试:               tdd-workflow/, django-tdd/, laravel-tdd/, quarkus-tdd/, verification-loop/, ...
├── 安全:               security-review/, security-scan/, defi-amm-security/, ...
├── 基础设施:            docker-patterns/, kubernetes-patterns/, deployment-patterns/, ...
├── 学习:               continuous-learning-v2/, agent-self-evaluation/, eval-harness/, ...
├── 编排:               orch-add-feature/, orch-pipeline/, plan-orchestrate/, team-agent-orchestration/, ...
├── 前端:               frontend-patterns/, react-patterns/, vue-patterns/, frontend-a11y/, ...
└── 领域专用:            healthcare-phi-compliance/, hipaa-compliance/, nutrient-document-processing/, ...

设计考虑： 按领域组织而非按工作流阶段组织，反映了ECC的”素材库”定位——用户按”我在做什么”（如Django开发）检索，而非按”我在哪个阶段”（如spec阶段）检索。

取舍： 按领域组织方便领域内检索（Django开发者找 django-* 即可），但不利于跨领域的工作流理解。用户想知道”如何做code review”时，需要找到 skills/security-review/（安全审查）、agents/code-reviewer.md（审查agent）、commands/code-review.md（slash入口）三个地方。

2.3 Selective Install的多维度控制

Selective install是ECC管理素材规模的核心机制：

状态存储： SQLite状态存储跟踪已安装组件，支持：

• node scripts/ecc.js list-installed——查看已安装
• node scripts/ecc.js doctor——诊断问题
• node scripts/ecc.js repair——修复安装
• node scripts/ecc.js uninstall --dry-run——预览卸载

设计考虑： Selective install让ECC可以从”全量素材库”降维到”项目实际需要的子集”——ECC假设不同项目需要不同的素材组合。

3. Hooks自动化体系

3.1六种Hook类型

ECC的hooks体系覆盖了Claude Code的全部hook生命周期（hooks/README.md）：

关键文件： hooks/hooks.json 定义了所有hook的matcher和command。hooks/memory-persistence/ 定义了会话生命周期的状态保存逻辑。

3.2与Skills的配合：确定性 + 概率性双层保障

ECC的hooks和skills形成了确定性 + 概率性的双层保障：

1
2
3
4
5
6
7
8
9

Hooks（确定性，100% 触发）
  ├── PreToolUse: 阻断不安全操作（dev server 不在 tmux 中 → block）
  ├── PostToolUse: 自动格式化（Edit .ts → prettier + tsc）
  └── Stop: 会话状态保存、模式提取
           ↓
Skills（概率性，AI 判断触发）
  ├── tdd-workflow: AI 判断是否需要 TDD 流程
  ├── security-review: AI 判断是否需要安全审查
  └── verification-loop: AI 判断是否需要验证

关键设计： Continuous Learning v2的文档明确解释了为什么用hooks而非skills来做观察（skills/continuous-learning-v2/SKILL.md）：

“v1 relied on skills to observe. Skills are probabilistic — they fire ~50-80% of the time based on Claude’s judgment.”
“Hooks fire 100% of the time, deterministically.”

取舍： Hooks是确定性的但能力有限（只能基于matcher和exit code），Skills是灵活的但触发不可靠。ECC的策略是用hooks做必须保证的事情（安全检查、格式化、状态保存），用skills做需要判断的事情（TDD流程、code review、验证）。

3.3 Delivery Gate：机械化的质量门禁

skills/delivery-gate/SKILL.md 是一个独特的Stop hook——它在Claude尝试结束会话时执行确定性检查：

设计考虑： Delivery Gate的设计哲学是”mechanical gates check machine-verifiable facts”——机械门禁检查机器可验证的事实，而非依赖AI推理。实现方式是通过hook的exit code进行确定性阻断。AI推理的质量检查不可靠，因为AI可能rationalize跳过检查；但regex匹配和文件mtime检查不会”自我说服”。

3.4运行时控制

ECC提供了精细的hook运行时控制（README.md）：

1
2
3
4
5
6
7
8
9
10
11
12
13

# 严格度 profile
export ECC_HOOK_PROFILE=minimal|standard|strict

# 禁用特定 hook
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# SessionStart context 限制
export ECC_SESSION_START_MAX_CHARS=4000
export ECC_SESSION_START_CONTEXT=off

# Continuous Learning 控制
export ECC_MAX_INJECTED_INSTINCTS=6
export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7

设计考虑： 运行时控制让用户在不修改 hooks.json 的情况下调整hook行为。minimal profile只保留核心安全hook，strict 启用所有提醒和更严格的guardrails。这意味着同一个ECC安装可以适应不同的使用场景——从快速原型开发（minimal）到严格的生产环境（strict）。

4. Continuous Learning v2

4.1 Instinct模型

Continuous Learning v2是ECC最独特的设计——一个从会话中自动学习并形成可复用知识的系统（skills/continuous-learning-v2/SKILL.md）。

Instinct是一个原子级的学习行为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# Prefer Functional Style

## Action
Use functional patterns over classes when appropriate.

## Evidence
- Observed 5 instances of functional pattern preference
- User corrected class-based approach to functional on 2025-01-15

核心属性：

• Atomic——一个trigger，一个action
• Confidence-weighted——0.3（试探性）到0.9（近确定）
• Domain-tagged——code-style、testing、git、debugging、workflow等
• Evidence-backed——记录观察来源
• Scope-aware——project（默认）或global

4.2学习管线

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

会话活动（在 git repo 中）
    │
    │ Hooks 捕获 prompts + tool use（100% 可靠）
    │ + 检测项目上下文（git remote / repo path）
    ▼
observations.jsonl（prompts, tool calls, outcomes, project）
    │
    │ Observer agent 读取（后台，Haiku 模型）
    ▼
模式检测
    ├── 用户纠正 → instinct
    ├── 错误解决 → instinct
    ├── 重复工作流 → instinct
    └── scope 决策：project 还是 global？
    │
    │ 创建/更新
    ▼
instincts/personal/（project 或 global）
    │
    │ /evolve 聚类 + /promote 提升
    ▼
evolved/（skills/commands/agents）

设计考虑： 学习管线的关键设计是观察和提取分离——hooks只负责捕获原始数据（100% 可靠），模式检测由后台Haiku agent完成（不影响主session性能）。/evolve 命令将成熟的instincts聚类为更高层级的skills/commands/agents，这是人工触发而非自动的——ECC认为从instincts到skills的提升需要人类判断。

4.3 v1 → v2 → v2.1的演进

关键设计决策：

1. 从Stop hook到PreToolUse/PostToolUse——v1依赖Stop hook在会话结束时提取模式，但skills是概率性触发的（50-80%）。v2改用hooks，100% 可靠。

2. 从完整skills到原子instincts——v1直接生成完整skills，粒度太粗。v2先生成原子级instincts（一个trigger + 一个action），再通过 /evolve 聚类成skills。

3. v2.1的project-scoped instincts——React patterns留在React项目，Python conventions留在Python项目。当同一instinct在2+ 个项目中出现且平均置信度 >= 0.8时，自动提升为global。

4.4置信度演化

置信度增加： 模式被重复观察、用户未纠正、其他来源的类似instinct一致。

置信度降低： 用户明确纠正、长时间未观察、出现矛盾证据。

设计考虑： 置信度模型让ECC的学习是渐进的——新模式先以0.3的置信度存在，只有被反复验证后才会成为核心行为。这避免了”一次误判成为永久规则”的问题。

取舍： 整个系统默认 observer.enabled: false——需要用户手动开启。这反映了ECC对自动学习的谨慎态度：自动写入行为可能引入错误的”学习”。代价是大多数用户可能永远不会开启这个功能。

5. Orchestration体系

5.1 orch-* 操作族

虽然ECC不定义流程，但它提供了一个可选的编排体系——orch-* skill family（skills/orch-pipeline/SKILL.md）：

关键设计： orch-pipeline/SKILL.md 是共享引擎，5个操作skill是”thin wrappers”——它们不重新实现工作，只是分类请求、选择哪些phase运行、委托给已有的ECC agent或command。

5.2共享管线

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Phase 0: Intake（重述请求）
    │
    ▼
Phase 1: Research & Reuse（gh search repos/code → Context7 → package registries → Exa）
    │
    ▼
Phase 2: Plan（委托 planner agent → 输出 task_list）
    │
    ▼
★ GATE 1 — 用户审批计划 ★
    │
    ▼
Phase 3: Scaffold（仅 orch-build-mvp）
    │
    ▼
Phase 4: Implement (TDD)（tdd-guide agent: red → green → refactor）
    │
    ▼
Phase 5: Review（code-reviewer agent + security-reviewer 如果触发安全条件）
    │
    ▼
★ GATE 2 — 用户审批提交 ★
    │
    ▼
Phase 6: Commit（conventional commits，一个逻辑块一个提交）

skills/orch-pipeline/SKILL.md 明确定义了”two gates”——GATE 1在Plan后（不写实现代码直到用户批准），GATE 2在Commit前（不提交直到用户确认）。两个gate之间的一切流式执行。

5.3 Size Classifier：仪式与影响范围匹配

设计考虑： “Ceremony scales to blast radius”——仪式与影响范围匹配。trivial变更跳过research和plan，直接TDD + review + commit。large变更走完整管线。

取舍： Size classifier是ECC中最接近”工作流设计”的东西。但它仍然是可选的——用户可以不使用 orch-* 而直接调用单个skills。

5.4 Agent/Command Map

orch-* pipeline的每个phase委托给已有的ECC agent或command：

设计考虑： orch-* 是”composer”而非”implementer”——它组合已有的素材，不重新实现。这保持了ECC “提供素材不定义流程”的哲学：orch-* 是一个可选的组合方式，用户也可以自己组合。

5.5 Observer Loop Prevention

v1.9.0引入了确定性的harness audit scoring（README.md changelog）：

“Harness audit scoring made deterministic, orchestration status and launcher compatibility hardened, observer loop prevention with 5-layer guard.”

设计考虑： Orchestrator需要防止observer loop——orchestrator启动的subagent不应该再触发orchestrator。5-layer guard确保编排层级不无限递归。这是一个典型的递归终止条件设计——没有它，orchestrator会不断spawn subagent，每个subagent又触发orchestrator，最终耗尽资源。

6. 其他关键Skills

6.1 Intent-Driven Development

skills/intent-driven-development/SKILL.md 是ECC的需求澄清方法论——将模糊的产品/工程变更转化为可验证的验收标准。

两种深度：

• Quick Capture：3-7个验收标准，低/中风险
• Full Acceptance Brief：安全/数据/迁移/跨系统变更，完整模板

关键设计：

1. 先检查上下文——读仓库、文档、schema、测试基础设施，能从代码推断的不问用户
2. 只问不能推断的问题——产品/业务约束不能从代码推断（business rules, compliance, SLAs, pricing, retention policy）
3. 可观察的验收标准——每个AC-NNN描述起始条件、触发、预期结果、禁止的副作用、验证方法、优先级
4. 不默认阻断实现——足够清晰的请求记录标准后继续，只在阻塞风险时等待确认

设计取舍： ECC的intent-driven-development走的是轻量路线——不强制Socratic对话，不设HARD-GATE，不要求分段确认。它更像”记录够用的验收标准然后继续”。

6.2 Search-First

skills/search-first/SKILL.md 系统化了”先搜索再编码”的工作流：

1

Need Analysis → Parallel Search (npm/PyPI + MCP + GitHub) → Evaluate → Decide (Adopt/Extend/Build) → Implement

设计考虑： “Research-before-coding” 不是新概念，但ECC将其系统化为一个skill，提供了搜索渠道、评估标准（functionality, maintenance, community, docs, license, deps）和决策矩阵（exact match → Adopt, partial → Extend, nothing → Build）。

6.3 Agent Self-Evaluation

skills/agent-self-evaluation/SKILL.md 让AI在完成非平凡任务后自我评分：

5个评估轴：

关键规则： “Every score below 5 MUST cite specific evidence”——不能只说”可以更好”，必须说具体缺了什么。Anti-pattern “Everything is a 5” 被明确禁止。这解决了AI自评倾向于”一切正常”的问题——强制要求低分项必须引用证据，使得自评不是走过场。

7. 演进中的关键教训

模式： 从概率到确定——ECC的演进主线是从依赖skills的概率性触发，逐步迁移到依赖hooks的确定性执行，同时保持skills作为需要判断力的工作流载体。这个模式贯穿了Continuous Learning的v1→v2→v2.1演进，也影响了Delivery Gate的设计（用regex/mtime而非AI推理）。

8. 能力边界

8.1不提供Spec模型

ECC没有结构化的spec模型——没有Requirement/Scenario、没有RFC 2119关键字、没有Delta机制、没有source of truth。

最接近的东西：

• intent-driven-development 的Acceptance Brief（AC-NNN格式）
• planner agent的Implementation Plan（Phase + Step格式）
• tdd-workflow 的User Journeys

但这些都不是持久化的source of truth——它们是一次性的工作产物，不持续演进。

8.2不提供变更追踪

ECC没有change/delta的概念——没有 changes/ 目录、没有archive机制、没有审计链。代码变更的历史完全依赖git。

8.3不强制执行流程

即使用 orch-* pipeline，两个GATE也是”gated, not autonomous”——需要用户审批。但 orch-* 本身是可选的，用户可以完全不用它。

ECC没有行为约束机制：

• 没有Iron Law
• 没有Rationalization表（虽然Delivery Gate检测rationalization模式，但只是警告）
• 没有HARD-GATE（hook的block是安全级别的，不是流程级别的）
• 没有SUBAGENT-STOP

8.4规模带来的发现成本

261+ skills是ECC的优势也是劣势：

• 优势： 几乎覆盖了所有主流语言和框架的场景
• 劣势： 用户发现”我需要哪个skill”的成本很高

ECC的应对策略：

1. Commands作为skills的slash入口
2. npx ecc consult 智能匹配
3. Selective install按需安装
4. Skills目录按领域命名

8.5跨平台维护成本

7+ 个AI harness的适配意味着：

• 每个hook变更需要跨平台测试
• 每个agent定义需要适配不同harness的格式
• 997+ 个内部测试反映维护成本
• Plugin系统的限制（如Claude Code plugin不能分发rules）需要workaround

8.6 Continuous Learning的实际效果未验证

Continuous Learning v2的设计很精巧，但：

• Observer默认关闭（observer.enabled: false）
• 需要后台Haiku agent运行（成本）
• Instinct质量依赖观察质量（garbage in, garbage out）
• 没有公开的eval数据证明学习效果

9. 设计决策清单

点击下方”阅读原文“进入我的演示网站。

一个在人与AI之间建立”先同意再构建”共识层的系统，是如何设计其核心抽象的？工具化程度到了什么水平？

1. 架构拆解

1.1三层架构：CLI工具 + 目录约定 + Slash Command

OpenSpec是一个 npm CLI工具 + 目录约定 + slash command 的三层架构。CLI是引擎（知道规则、验证、合并），slash commands是方向盘（引导AI按工作流行动）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

┌─────────────────────────────────────────────────┐
│                 用户交互层                        │
│  ┌──────────────────┐  ┌──────────────────────┐ │
│  │  Terminal (CLI)   │  │  AI Chat (Slash)     │ │
│  │  openspec init    │  │  /opsx:propose       │ │
│  │  openspec list    │  │  /opsx:apply         │ │
│  │  openspec view    │  │  /opsx:archive       │ │
│  └────────┬─────────┘  └────────┬─────────────┘ │
│           │   CLI 是引擎          │  Slash 是方向盘 │
│           │   (规则、验证、合并)   │  (工作流引导)  │
│           ▼                      ▼               │
├─────────────────────────────────────────────────┤
│                 核心层                            │
│  ┌──────────────────────────────────────────┐   │
│  │  src/core/  (~41 个模块)                  │   │
│  │  artifact-graph / validation / parsers /  │   │
│  │  command-generation / store / archive ... │   │
│  └──────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│                 存储层                            │
│  ┌──────────────────────────────────────────┐   │
│  │  openspec/  (目录约定)                    │   │
│  │  specs/ (source of truth)                │   │
│  │  changes/ (proposed modifications)       │   │
│  │  config.yaml                             │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

设计考虑： 这个分离使得OpenSpec能支持30+ AI工具——CLI是平台无关的，每个AI工具只需要不同的slash command适配器。代价是用户需要理解”终端命令”和”聊天命令”的区别，这是新用户最常见的困惑点（文档专门用一整页解释）。

1.2核心目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

openspec/
├── specs/                    # Source of Truth——系统当前行为
│   ├── auth/
│   │   └── spec.md
│   └── payments/
│       └── spec.md
├── changes/                  # 拟议变更（每个 change 一个文件夹）
│   ├── add-dark-mode/
│   │   ├── proposal.md       # 为什么 + 做什么
│   │   ├── design.md         # 怎么做（技术方案）
│   │   ├── tasks.md          # 实现清单
│   │   ├── .openspec.yaml    # 变更元数据（可选）
│   │   └── specs/            # Delta specs
│   │       └── ui/
│   │           └── spec.md
│   └── archive/              # 已归档变更（带日期前缀）
│       └── 2025-01-24-add-2fa/
├── config.yaml               # 项目配置
└── schemas/                  # 自定义 schema（可选）

设计考虑： specs/ 和 changes/ 的分离是OpenSpec的核心洞察——source of truth和proposed modifications物理隔离。多个change可以并行存在而不冲突，review在merge之前进行，archive后delta合并回source of truth。

1.3源码架构

src/core/ 下约41个模块，核心包括：

关键文件： src/core/artifact-graph/instruction-loader.ts 是连接CLI和AI的桥梁——generateInstructions() 函数将schema定义、项目配置（context + rules）、模板内容组合成AI可消费的指令JSON。

1.4 Agent Contract

docs/agent-contract.md 定义了所有CLI命令的 JSON机器可读接口：

• 每个命令都支持 --json 输出
• 输出结构包含 status（状态数组）和业务数据
• 退出码：0 = 成功，1 = 可恢复错误，2 = 严重错误
• 诊断码：archive_validation_failed、archive_change_not_found 等100+ 诊断码

设计考虑： Agent Contract让AI agent可以程序化地调用CLI、解析输出、做出决策。例如 openspec status --change "name" --json 返回的JSON包含 applyRequires（apply前必须完成的artifact ID列表）、artifacts（每个artifact的状态）和 actionContext（机器可读的动作约束），AI agent据此决定下一步做什么。不依赖AI解析自然语言输出来理解状态。

取舍： 这个设计增加了CLI的复杂度（每个命令需要维护两套输出：人类可读和机器可读），但使得AI集成变得确定性化。

2. Spec模型

2.1行为契约，不是实现计划

OpenSpec的spec模型有一个明确的核心原则（docs/writing-specs.md）：

“A spec says what your system does, in terms anyone could check — not how it’s built.”

具体规则：

• Spec描述外部可观察行为，不描述内部实现
• “如果改了实现但不改外部可观察行为，那它不属于spec”
• 实现细节（类名、库选择、数据结构）放在 design.md，不放入spec

设计考虑： 这个分离解决了一个常见的spec腐化问题——当spec混入实现细节后，每次代码重构都需要更新spec，导致spec迅速过时。行为契约只在行为变化时才需要更新，与实现重构解耦。

2.2 Requirement + Scenario结构

Spec的基本单元是 Requirement（需求）+ Scenario（场景）：

1
2
3
4
5
6
7

### Requirement: Session Timeout
The system SHALL expire a session after 30 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass with no activity
- THEN the session is invalidated and the user must re-authenticate

关键元素：

设计考虑：

1. 一个Requirement一个SHALL/MUST——如果包含三个 “and also” 分句，实际上是三个需求，必须拆分。这让每个需求可独立测试。

2. Scenario必须真正exercise需求——“复述需求的场景测试不了任何东西”。好的场景覆盖edge case而非只覆盖happy path：”你最在意哪个case被破坏？确保有一个场景覆盖它。”

3. RFC 2119关键字——MUST/SHALL/SHOULD/MAY不是装饰，是明确语义强度。默认用MUST/SHALL，只有真正允许例外时才用SHOULD。

取舍： 结构化格式增加了编写成本，但换来了场景可映射为自动化测试（GIVEN/WHEN/THEN → 测试骨架）、需求可独立验证、语义强度明确、Review效率提升。

2.3 Progressive Rigor

OpenSpec不要求所有变更都使用相同级别的规格化（docs/concepts.md）：

“Use the lightest level that still makes the change verifiable”

设计考虑： 这是对”流程过重”问题的回应——不是每个变更都需要完整的规格化。一行typo修复不需要三个Requirement和一个design doc。”Match the ceremony to the stakes.”

2.4 Human + Agent协作模型

OpenSpec明确定义了人和AI的分工（docs/concepts.md）：

1. 人类提供意图、上下文和约束
2. Agent转换为行为需求和场景
3. Agent保持实现细节在 design.md 和 tasks.md，不放入 spec.md
4. 验证确认结构和清晰度

docs/writing-specs.md 进一步解释了如何引导AI产出好的spec：

• State the intent and the boundary——说清楚要做什么和不做什么
• Name the cases you care about——指出需要覆盖的场景
• Then edit——AI的初稿需要人工编辑

设计考虑： OpenSpec认识到AI擅长将自然语言转换为结构化格式，但不擅长判断”什么重要”——什么场景值得覆盖、什么行为值得规格化。因此人类负责”瞄准”，AI负责”填充”。

3. Delta机制

3.1 ADDED / MODIFIED / REMOVED

Delta spec是OpenSpec brownfield-first设计的核心（docs/concepts.md）。Delta spec描述”什么变了”而非重述全部：

1
2
3
4
5
6
7
8
9
10
11
12

## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

## MODIFIED Requirements
### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

## REMOVED Requirements
### Requirement: Remember Me
(Deprecated in favor of 2FA.)

Archive合并规则：

3.2为什么用Delta而非全文重写

从 openspec/changes/archive/2025-08-19-adopt-delta-based-changes/proposal.md 可以看到原始设计动机：

“The current approach of storing complete future states in change proposals creates a poor review experience. When reviewing changes on GitHub, reviewers see entire spec files (often 100+ lines) as ‘added’ in green, making it impossible to identify what actually changed.”

四个理由：

1. 清晰——Delta只展示变更，reviewer不需要mental diff
2. 避免冲突——两个change可以同时修改同一spec的不同requirement
3. Review效率——Reviewer只看变更，不看未变的上下文
4. Brownfield适配——大多数工作是修改现有行为，而非从零创建

设计考虑： Delta机制把”变更”从”状态”中分离出来。传统spec系统存储完整状态，reviewer需要对比才能发现变更；OpenSpec存储变更本身，reviewer直接看到的就是变更。

3.3 Delta应用逻辑

src/core/specs-apply.ts 实现了delta合并逻辑：

• 应用顺序：RENAMED → REMOVED → MODIFIED → ADDED
• 原子性：先在内存中应用所有操作，验证全部通过后才写入文件。任何验证失败都abort，不写部分结果
• 验证矩阵：MODIFIED/REMOVED必须存在于main spec；ADDED不能已存在；RENAMED FROM必须存在且TO不存在；无跨section冲突
• Header匹配：按 ### Requirement: [Name] 精确匹配（trim空格，大小写敏感）

关键文件： src/core/archive.ts 中的 ArchiveCommand.run() 方法展示了完整的归档流程：验证 → 检查任务完成 → 查找spec更新 → 构建更新后的spec → 验证重建的spec → 写入文件 → move change到archive。

3.4验证体系

src/core/validation/validator.ts 实现了多层验证：

1. Spec验证：检查Purpose长度、Requirement必须有SHALL/MUST、每个Requirement至少一个Scenario、Spec结构合规性
2. Change验证：检查delta描述长度、ADDED/MODIFIED必须有requirements
3. Delta Spec验证：每个ADDED/MODIFIED requirement必须有SHALL/MUST和至少一个scenario；REMOVED只需名称；无section内重复；无跨section冲突
4. 重建spec验证：归档时重建完整spec后再验证一次，确保合并结果有效

设计考虑： 验证是 “Enablers not Gates” 哲学的体现——验证发现问题但不阻断操作。Archive可以在有validation error时使用 --no-validate 跳过。验证的目的是暴露问题，不是阻止行动。

4. Artifact Graph

4.1依赖图模型

Artifact之间形成有向无环图（DAG），由schema定义（docs/concepts.md）：

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

                 proposal
                (root node)
                    │
      ┌─────────────┴─────────────┐
      │                           │
      ▼                           ▼
   specs                       design
(requires:                  (requires:
 proposal)                   proposal)
      │                           │
      └─────────────┬─────────────┘
                    │
                    ▼
                 tasks
             (requires:
             specs, design)

关键文件： src/core/artifact-graph/types.ts 定义了schema的Zod类型：ArtifactSchema（id、generates、template、instruction、requires）、ApplyPhaseSchema（apply阶段需要的artifact ID列表）、SchemaYamlSchema（完整的schema YAML结构）。

4.2 “Enablers, not Gates”

这是OpenSpec的核心哲学之一（docs/concepts.md）：

“Dependencies are enablers, not gates. They show what’s possible to create, not what you must create next. You can skip design if you don’t need it.”

设计考虑： 传统工作流用phase gate强制顺序——必须先完成planning才能开始implementation。OpenSpec认为真实工作不fit进盒子，因此用依赖图表示”可以做什么”而非”必须做什么”。如果你想跳过design直接写tasks，技术上可以。

取舍： 这个设计给了用户最大灵活性，但代价是没有强制流程保障。用户可能跳过重要步骤。OpenSpec的应对是——通过verify暴露问题，而不是通过gate阻止行动。

4.3 Schema系统

Schema定义了工作流的artifact类型和依赖关系（docs/customization.md）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
    requires: []

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]

  - id: design
    generates: design.md
    requires: [proposal]

  - id: tasks
    generates: tasks.md
    requires: [specs, design]

apply:
  requires: [tasks]
  tracks: tasks.md

Schema解析顺序（src/core/artifact-graph/instruction-loader.ts）：

1. CLI flag：--schema <name>
2. Change元数据：.openspec.yaml 中的schema字段
3. 项目配置：openspec/config.yaml 中的schema字段
4. 默认：spec-driven

设计考虑： 每层覆盖前一层，实现了四级定制化：CLI临时覆盖 → 单个变更级 → 项目级 → 内置默认。这意味着同一项目中不同变更可以使用不同工作流。

4.4自定义Schema

OpenSpec支持三种创建自定义schema的方式（docs/customization.md）：

1. Fork：从内置schema复制并修改——openspec schema fork spec-driven my-workflow
2. Init：从零创建——openspec schema init research-first
3. Community：从社区schema仓库安装

4.5 Profile系统

设计考虑： core profile只有5个命令，降低了入门门槛。expanded增加了6个命令用于需要逐步控制artifact创建的场景。通过 openspec config profile 切换，然后 openspec update 重新生成slash command。

5. 工具化设计

5.1平台适配器

OpenSpec支持30+ AI编码助手（docs/supported-tools.md），包括Claude Code、Cursor、Windsurf、GitHub Copilot、Codex、Gemini、Cline、RooCode、Kimi等。

集成方式： 每个工具生成两类文件：

• Skills：.../skills/openspec-*/SKILL.md——跨工具标准，AI自动检测
• Commands：工具特定的slash command文件——如 .claude/commands/opsx/<id>.md、.cursor/commands/opsx-<id>.md

5.2 Command Generation机制

src/core/command-generation/generator.ts 的实现极其简洁：

1
2
3
4
5
6
7
8
9

export function generateCommand(
  content: CommandContent,
  adapter: ToolCommandAdapter
): GeneratedCommand {
  return {
    path: adapter.getFilePath(content.id),
    fileContent: adapter.formatFile(content),
  };
}

核心思路是工具无关的content + 工具特定的adapter = 工具特定的command文件。这是一个经典的适配器模式应用。添加新平台支持只需要写一个新的adapter，不需要修改任何业务逻辑。每个adapter只需实现两个方法：getFilePath（文件放哪里）和 formatFile（文件格式是什么）。

5.3 Instruction Loader

src/core/artifact-graph/instruction-loader.ts 的 generateInstructions() 函数是连接CLI和AI的核心桥梁。

指令注入顺序：

1. <context>——项目配置中的context（技术栈、约定等），约束AI但不放入输出
2. <rules>——artifact特定的规则（如”包含回滚计划”），约束AI但不放入输出
3. <template>——schema模板内容，这是输出格式

关键设计： context和rules是”约束你（AI）的，不是输出文件的内容”。模板明确标注：”Do NOT copy <context>, <rules>, <project_context> blocks into the artifact”。这防止了AI把项目背景信息机械地复制到proposal中。

5.4 Customization三层

Context注入示例：

1
2
3
4
5
6
7
8
9
10
11

# openspec/config.yaml
context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format

设计考虑： Context出现在所有artifact中，Rules只出现在匹配的artifact中。这让项目约定（技术栈、编码风格）自动注入到每个AI生成的artifact，而不需要每次手动提醒。

5.5 Store机制（Beta）

Store是OpenSpec的跨repo spec共享方案（src/core/store/）：

• Planning住在独立的standalone repo
• 多个code repo可以引用同一个store
• 适用于：一个功能跨多个服务/仓库、一个团队owns requirements其他团队消费

设计考虑： Store解决的是monorepo之外的多repo协作问题。目前是beta状态，命令和状态可能变化。

6. 演进历程

6.1从Phase-Locked到Fluid Actions（2025-08）

变更： openspec/changes/archive/2025-08-19-adopt-verb-noun-cli-structure/

“Traditional workflows force you through phases: first you plan, then you implement, then you’re done. But real work doesn’t fit neatly into boxes.”

为什么： 传统工作流强制你经过阶段，但真实工作不fit进盒子。用户可能在implementation中发现需要修改spec，或者在design中发现需要回到proposal。

取舍： 流动性给了用户灵活性，但失去了流程的强制保障。OpenSpec的应对是——用依赖图表示”使能”而非”门禁”，用verify暴露问题而非阻断行动。

6.2采用Delta-Based Changes（2025-08）

变更： openspec/changes/archive/2025-08-19-adopt-delta-based-changes/

为什么： 之前存储完整future state，GitHub diff全绿（100+ 行 “added”），reviewer无法识别实际变更。

结果： Delta格式让GitHub diff只显示实际变更（25行代替150+），review效率大幅提升。同时让两个change可以并行修改同一spec的不同requirement。这是OpenSpec brownfield-first设计的基石——Delta让”修改现有行为”成为first-class概念。

6.3结构化Spec格式（2025-08）

变更： openspec/changes/archive/2025-08-19-structured-spec-format/

为什么： 之前spec是自由格式Markdown，无法程序化解析和验证。

结果： 引入 ### Requirement: + #### Scenario: + RFC 2119关键字的标准格式，使得CLI可以验证spec结构、Delta合并可程序化执行（按header匹配）、场景可映射为测试。

6.4多AI工具适配（2025-09）

变更： openspec/changes/archive/2025-09-29-add-multi-agent-init/ 和多个 add-*-support 变更

为什么： 最初只支持Claude Code，但用户使用各种不同的AI工具。

演进： 从Claude Code单平台 → multi-agent init支持多平台 → 29+ 个平台适配器。每个平台只需要一个adapter（getFilePath + formatFile）。

6.5 Artifact Graph Core（2025-12）

变更： openspec/changes/archive/2025-12-24-add-artifact-graph-core/

为什么： 之前依赖约定和AI推断来决定artifact创建顺序，不够确定性。

“The current OpenSpec system relies on conventions and AI inference for artifact ordering. A formal artifact graph with dependency awareness would enable deterministic ‘what’s ready?’ queries.”

结果： 引入 ArtifactGraph 类（基于DAG + 拓扑排序），提供 getNextArtifacts()（哪些可以创建）、getBuildOrder()（构建顺序）、isComplete()（是否全部完成）等确定性查询。

6.6 Project Config + Local Schemas（2025-12 ~ 2026-02）

变更： openspec/changes/archive/2025-12-20-add-global-config-dir/、2025-12-21-add-config-command/

为什么： 用户需要项目级定制——默认schema、技术栈context、per-artifact rules。

结果： openspec/config.yaml 支持context注入和rules配置。Schema可以fork到项目本地并自定义。

6.7 Explore命令的引入

在”还没想好做什么”的阶段提供低成本探索入口——不创建change、不写artifact、不修改代码。Explore是 “a stance, not a workflow”——没有固定步骤、没有必需输出、没有必经路径。填补了”模糊问题”到”具体提案”之间的空白。

7. Review机制

7.1两个Review时机

OpenSpec的review不在流程中的固定位置，而是可以在任何时候进行（docs/reviewing-changes.md）：

关键设计： Review阅读顺序是proposal → specs → tasks（如果proposal错了，不用往下读）。Review是人工的、轻量的——“Right-size review: 简单修改20秒扫一眼，关键修改仔细审”。不强制每次都做完整review。

7.2三个验证维度

/opsx:verify 命令从三个维度验证实现（docs/workflows.md + src/core/templates/workflows/verify-change.ts）：

验证启发式规则：

• Completeness：关注客观检查项（checkbox、requirement列表）
• Correctness：使用关键词搜索和文件路径分析，不要求完美确定性
• Coherence：寻找明显不一致，不吹毛求疵
• False Positive策略：不确定时优先SUGGESTION而非WARNING，优先WARNING而非CRITICAL
• Graceful Degradation：只有tasks.md → 只验证task完成；tasks + specs → 验证completeness和correctness；完整artifacts → 验证全部三个维度

7.3不阻断

“Verify won’t block archive, but it surfaces issues you might want to address first.”

这是 “Enablers not Gates” 哲学的核心体现：

“leaves the call to you”

Archive时：

• 验证有error → 警告但不阻止（除非使用 --json 模式）
• Task未完成 → 警告但可以继续（用 --yes 确认）
• Spec未sync → 询问是否sync，不强制

设计考虑： OpenSpec认为review和verify的价值在于暴露信息，让人类做决策，而不是代替人类做决策。

取舍： 非阻断设计给了用户最大灵活性，但代价是——用户可以忽略所有警告直接archive，导致spec与代码不一致。OpenSpec的赌注是：用户会做出合理的判断，而流程的轻量性会让用户更愿意使用。

7.4 Reviewing in Pull Requests

OpenSpec的team workflow（docs/team-workflow.md）建议将review嵌入PR流程：

1
2
3
4
5
6
7

git switch -c add-dark-mode
/opsx:propose add-dark-mode
REVIEW THE PLAN (读 proposal + specs + tasks)
/opsx:apply
git commit && open a PR (PR 包含 spec delta + 代码)
teammate reviews, merges
/opsx:archive

关键设计： “OpenSpec doesn’t touch git”——OpenSpec从不commit、branch、push或pull。它只读写Markdown文件。所有git操作是用户的职责。这个设计让OpenSpec能无缝融入任何现有的git工作流，而不是替代它。

8. 演进中的关键教训

模式： 从约束到使能——OpenSpec的演进主线是从”硬性约束”（phase gate、固定工作流、全量spec）转向”柔性使能”（enablers、可定制schema、delta），通过暴露问题而非阻断行动来引导质量。

9. 能力边界

9.1不处理开发执行流程

OpenSpec的流程止于 /opsx:apply——按tasks.md逐项实现。它不涉及TDD约束、subagent驱动、代码审查、调试方法论。/opsx:apply 的任务模板只是一个简单的”读tasks.md → 逐项实现 → 勾选checkbox”流程。

设计考虑： OpenSpec有意将执行阶段留给其他工具。它定位为共识层，不是执行层。

9.2不处理行为约束

OpenSpec没有行为约束机制——没有Iron Law、没有Rationalization表、没有Red Flags、没有HARD-GATE。Slash command模板中有Guardrails段落（如explore的”Don’t implement / Don’t rush”），但这些是建议性的，不是强制的。

设计考虑： OpenSpec假设用户会合理使用工具，而不是假设用户（或AI）会试图绕过流程。

9.3验证的精度有限

/opsx:verify 基于启发式规则而非确定性验证：

• Correctness维度使用”关键词搜索和文件路径分析”，承认”不要求完美确定性”
• Scenario覆盖检查是”检查条件是否在代码中处理”，不是运行测试

设计考虑： OpenSpec的verify是”reasonable inference”而非”proof”。它承认AI无法完美地判断代码是否匹配spec，因此选择了宽松的验证策略。

9.4 Delta合并的手动风险

Delta合并虽然程序化执行，但以下风险仍然存在：

• Spec腐化——代码变更但spec未更新，archive时spec与现实不一致
• 合并顺序——bulk archive时多个change修改同一spec，按时间顺序合并，但可能不是语义正确的顺序
• 手动编辑风险——用户手动编辑spec文件可能破坏结构（虽然validate会检查）

9.5平台适配的维护成本

29+ 个平台适配器意味着每个新命令或命令变更需要同步更新所有适配器。虽然适配器模式让添加新平台容易，但维护已有平台的兼容性是一个持续成本。

10. 设计决策清单

点击下方”阅读原文“进入我的演示网站。

日期： 2026-07-11
核心问题： 一个试图把Claude Code变成完整工程团队的项目，是如何设计sprint链式传递的？它的全流程覆盖与工具重度依赖之间是什么关系？

1. 架构拆解

1.1定位与规模

gstack的自我定位是 “turns Claude Code into a virtual engineering team”（README.md）。这不是比喻——README列出了23个specialist skills和8个power tools，每个skill对应一个工程角色：CEO、Eng Manager、Senior Designer、Staff Engineer、QA Lead、Security Officer、Release Engineer、SRE等。Garry Tan（YC总裁）以个人身份构建，声称在60天内交付了3个生产服务、40+ 功能特性，逻辑代码变更速率是2013年的 ~810×。

这个定位的核心信号是：这不是skill集合，而是一个软件工厂。 gstack明确拥有一个完整的sprint流程，每个skill在流程中有固定位置。这与ECC的”提供素材不定义流程”和mattpocock的”不拥有流程”形成了鲜明的立场差异。

1.2 Sprint结构

gstack的核心组织原则是 sprint——一个按工程团队节奏运行的流程（README.md）：

1
2
3
4
5
6
7
8
9

Think → Plan → Build → Review → Test → Ship → Reflect
  │        │        │        │        │       │       │
  │        │        │        │        │       │       └── /retro, /learn, /document-release
  │        │        │        │        │       └── /ship, /land-and-deploy, /canary
  │        │        │        │        └── /qa, /qa-only, /benchmark, /investigate
  │        │        │        └── /review, /codex, /cso
  │        │        └── (由 plan 产出驱动)
  │        └── /plan-ceo-review, /plan-eng-review, /plan-design-review, /plan-devex-review, /autoplan, /spec
  └── /office-hours

每个阶段对应一组skills：

设计考虑： sprint结构不是松散的skill列表，而是一条链式传递的流水线——每个skill的产出喂给下一个。README明确指出：”Each skill feeds into the next. /office-hours writes a design doc that /plan-ceo-review reads. /plan-eng-review writes a test plan that /qa picks up. /review catches bugs that /ship verifies are fixed.”

1.3 Skill模板系统

gstack的SKILL.md文件不是手写的，而是从 .tmpl 模板自动生成的（ARCHITECTURE.md）：

1
2
3
4
5

SKILL.md.tmpl          (人类编写的 prose + 占位符)
       ↓
gen-skill-docs.ts      (读取源代码元数据)
       ↓
SKILL.md               (提交到 git，自动生成 sections)

占位符从源代码中填充：{{COMMAND_REFERENCE}} 从 commands.ts 生成命令表，{{PREAMBLE}} 生成启动块，{{BASE_BRANCH_DETECT}} 生成动态分支检测等。

设计考虑： 这个设计解决了”文档与代码漂移”的经典问题——如果命令存在于代码中，它就出现在文档中；如果不存在，就不能出现。CI通过 gen:skill-docs --dry-run + git diff --exit-code 在merge前捕获过时文档。

取舍： 模板系统增加了贡献者门槛——修改skill需要理解模板系统、resolver模块和生成管线。但换来的是文档与代码的结构性一致性。

1.4 Preamble共享块

每个skill都以一个 {{PREAMBLE}} 块开始，这是一个约170行的bash脚本，处理五件事（ARCHITECTURE.md）：

1. Update check — 调用 gstack-update-check，报告是否有升级
2. Session tracking — 触摸 ~/.gstack/sessions/$PPID，计算活跃session数。当3+ 个session运行时，所有skill进入 “ELI16 mode”——每个问题都重新为用户建立上下文，因为他们正在多个窗口之间切换
3. Operational self-improvement — skill结束时，agent反思失败并将操作学习记录到项目的JSONL文件
4. AskUserQuestion format — 统一格式：context、question、RECOMMENDATION: Choose X because ___、字母选项
5. Search Before Building — 在构建不熟悉的模式前先搜索

Preamble的结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# === GSTACK PREAMBLE (auto-generated, do not edit) ===

# 1. Update check
gstack-update-check 2>/dev/null

# 2. Session tracking
_SESSIONS_DIR="${GSTACK_HOME:-$HOME/.gstack}/sessions"
mkdir -p "$_SESSIONS_DIR"
touch "$_SESSIONS_DIR/$PPID"
_ACTIVE=$(find "$_SESSIONS_DIR" -mmin -30 | wc -l)
if [ "$_ACTIVE" -ge 3 ]; then
  export GSTACK_ELI16=true
fi

# 3. Context Recovery
_PROJ="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}"
find "$_PROJ/ceo-plans" "$_PROJ/checkpoints" -type f -name "*.md" 2>/dev/null | head -3
[ -f "$_PROJ/${_BRANCH}-reviews.jsonl" ] && echo "REVIEWS: ..."

# 4. Search Before Building
# (injected as instructions, not bash)

# 5. Operational self-improvement (on exit)
trap 'gstack-learning-record --skill "$0" --exit-code $?' EXIT
# === END PREAMBLE ===

设计考虑： preamble是gstack的”操作系统”——它让每个skill都继承相同的基础设施（升级检查、遥测、学习、搜索），而不需要每个skill重复实现。ELI16 mode是一个独特的设计：当用户同时运行多个sprint时，每个skill自动降低假设的上下文量。这不是用户配置的，而是系统根据session数量自动激活的。

1.5多平台适配

gstack通过 hosts/ 目录下的类型化配置文件适配10个AI编码代理（README.md）：

设计考虑： 添加一个新host只需要一个TypeScript配置文件，零代码修改（docs/ADDING_A_HOST.md）。这是通过将host差异隔离到配置层（安装路径、skill前缀、工具映射）实现的。

关键文件： README.md、CLAUDE.md、ARCHITECTURE.md、ETHOS.md

2. Sprint链式传递设计

2.1链式传递的实现

gstack的链式传递不是松散的”skill之间可以互相调用”，而是通过持久化artifact + 主动读取实现的。每个skill将产出写入 ~/.gstack/projects/$SLUG/ 下的文件，下游skill在preamble阶段主动读取这些文件。

主要artifact流：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

/office-hours
  → 写入 ~/.gstack/projects/$SLUG/*-design-*.md（设计文档）

/plan-ceo-review
  → 读取 design doc（PREREQUISITE SKILL OFFER 主动检查）
  → 写入 ~/.gstack/projects/$SLUG/ceo-plans/{date}-{feature}.md（CEO 计划）

/plan-eng-review
  → 读取 design doc + CEO 计划
  → 写入 test plan（嵌入 plan 文件）

/review
  → 读取 git diff
  → 写入 ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl（审查日志）

/qa
  → 读取 test plan（从 plan 文件中）
  → 打开浏览器执行测试
  → 修复 bug + 生成回归测试（atomic commits）

/ship
  → 读取 review 日志（gstack-review-read）
  → 读取 learnings（gstack-learnings-search）
  → 读取 decisions（gstack-decision-search）
  → 执行 21 步 ship 流程
  → 写入 ship metrics 到 reviews.jsonl

设计考虑： 链式传递通过文件系统实现，不依赖context window传递。这意味着：

1. 跨session传递 — 即便session中断，artifact仍在磁盘上
2. 跨sprint传递 — 一个sprint的CEO计划可以被另一个sprint读取
3. 可审计 — 所有artifact都有时间戳和文件路径

2.2 Context Recovery

每个skill的preamble都包含Context Recovery块（plan-ceo-review/SKILL.md）：

1
2
3
4

_PROJ="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}"
find "$_PROJ/ceo-plans" "$_PROJ/checkpoints" -type f -name "*.md" | head -3
[ -f "$_PROJ/${_BRANCH}-reviews.jsonl" ] && echo "REVIEWS: ..."
[ -f "$_PROJ/timeline.jsonl" ] && tail -5 "$_PROJ/timeline.jsonl"

这会在每次skill启动时恢复最近的artifact、审查记录、时间线和活跃决策。

设计考虑： Context Recovery解决了”context compaction后丢失上下文”的问题。当Claude Code的context window被compact后，skill重启时通过读取磁盘上的artifact恢复状态。gstack传递的是工程状态（设计文档、审查记录、决策日志），而非仅仅是对话摘要。

2.3 Review Readiness Dashboard

/ship 在Step 1会展示一个Review Readiness Dashboard（ship/SKILL.md）：

1
2
3
4
5
6
7
8
9
10
11
12
13

+====================================================================+
|                    REVIEW READINESS DASHBOARD                       |
+====================================================================+
| Review          | Runs | Last Run            | Status    | Required |
|-----------------|------|---------------------|-----------|----------|
| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
| CEO Review      |  0   | —                   | —         | no       |
| Design Review   |  0   | —                   | —         | no       |
| Adversarial     |  0   | —                   | —         | no       |
| Outside Voice   |  0   | —                   | —         | no       |
+--------------------------------------------------------------------+
| VERDICT: CLEARED — Eng Review passed                                |
+====================================================================+

Dashboard从 gstack-review-read 读取审查日志，显示每种审查的运行次数、最后运行时间、状态。只有Eng Review是required（可通过 skip_eng_review 全局禁用），其他审查是informational。

设计考虑： Dashboard让链式传递的状态可视化——用户在ship前一眼看到哪些审查已运行、哪些缺失。Staleness detection还会比较审查时的commit与当前HEAD，提示审查是否可能过时。

2.4 Autoplan：自动化链式传递

/autoplan 是链式传递的自动化版本——一条命令运行CEO → design → eng → DX审查（README.md）：

“One command, fully reviewed plan. Runs CEO → design → eng review automatically with encoded decision principles. Surfaces only taste decisions for your approval.”

/autoplan 自动检测哪些审查适用（前端变更触发design review，API变更触发DX review），只将taste decisions呈现给用户。

设计考虑： autoplan解决了”用户忘记运行某个审查”的问题——一条命令覆盖所有计划阶段审查。encoded decision principles意味着gstack将一些常见的审查决策编码为自动规则，只有真正需要人类判断的taste call才暂停。

关键文件： office-hours/SKILL.md、plan-ceo-review/SKILL.md、ship/SKILL.md、review/SKILL.md、ARCHITECTURE.md

取舍： 链式传递的代价是重量级——每个skill都有170行preamble、多个on-demand section文件、复杂的artifact路径约定。但链式传递换来了跨session、跨sprint的工程状态持久化和可审计性。

3. 持久浏览器守护进程

3.1核心设计

gstack的浏览器是它的”hard part”——ARCHITECTURE.md 开篇就说：”gstack gives Claude Code a persistent browser and a set of opinionated workflow skills. The browser is the hard part — everything else is Markdown.”

核心洞察：AI agent与浏览器交互需要亚秒级延迟和持久状态。如果每次命令都冷启动浏览器，每次工具调用要等3-5秒。如果浏览器在命令间死亡，cookies、tabs和登录session全部丢失。

解决方案是长驻Chromium守护进程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Claude Code                     gstack
─────────                      ──────
                               ┌──────────────────────┐
  Tool call: $B snapshot -i    │  CLI (compiled binary)│
  ─────────────────────────→   │  • reads state file   │
                               │  • POST /command      │
                               │    to localhost:PORT   │
                               └──────────┬───────────┘
                                          │ HTTP
                               ┌──────────▼───────────┐
                               │  Server (Bun.serve)   │
                               │  • dispatches command  │
                               │  • talks to Chromium   │
                               │  • returns plain text  │
                               └──────────┬───────────┘
                                          │ CDP
                               ┌──────────▼───────────┐
                               │  Chromium (headless)   │
                               │  • persistent tabs     │
                               │  • cookies carry over  │
                               │  • 30min idle timeout  │
                               └───────────────────────┘

首次调用启动一切（~3s），之后每次调用 ~100-200ms。

设计考虑： 守护进程模型带来三个关键能力：

1. 持久状态 — 登录一次，保持登录。打开一个tab，它保持打开。localStorage跨命令持久化。
2. 亚秒级命令 — 首次调用后，每个命令只是一个HTTP POST。
3. 自动生命周期 — 首次使用自动启动，30分钟空闲后自动关闭。

3.2为什么选择Bun

ARCHITECTURE.md 解释了选择Bun而非Node.js的四个理由：

1. 编译二进制 — bun build --compile 生成 58MB单一可执行文件。运行时无需 node_modules、无需 npx、无需PATH配置。这很重要因为gstack安装到 `/.claude/skills/` 用户不期望管理Node.js项目。
2. 原生SQLite — Cookie解密直接读取Chromium的SQLite cookie数据库。Bun内置 new Database()，无需 better-sqlite3、无需原生插件编译。
3. 原生TypeScript — 开发时 bun run server.ts，无需编译步骤。
4. 内置HTTP服务器 — Bun.serve() 快速、简单，不需要Express或Fastify。

设计考虑： 瓶颈始终是Chromium，不是CLI或server。Bun的启动速度（~1ms编译二进制vs ~100ms Node）是nice-to-have，但编译二进制和原生SQLite才是选择Bun的真正原因。

3.3 Ref系统

gstack的Ref系统（@e1, @e2, @c1）是agent寻址页面元素的方式，无需写CSS选择器或XPath（ARCHITECTURE.md）：

1. Agent运行 $B snapshot -i
2. Server调用Playwright的 page.accessibility.snapshot()
3. 解析器遍历ARIA树，分配顺序ref：@e1, @e2, @e3…
4. 为每个ref构建Playwright Locator：getByRole(role, { name }).nth(index)
5. 返回带注释的树作为纯文本

为什么用Locators而非DOM修改：

• CSP — 许多生产站点阻止脚本修改DOM
• 框架水合 — React/Vue/Svelte调和可能剥离注入的属性
• Shadow DOM — 无法从外部触及shadow root

Playwright Locators独立于DOM，使用Chromium内部维护的accessibility tree。无DOM修改、无CSP问题、无框架冲突。

3.4安全模型

Localhost only — HTTP server绑定 127.0.0.1，不可从网络访问。

Bearer token auth — 每次server session生成随机UUID token，写入state file（mode 0o600）。每个修改浏览器状态的HTTP请求必须包含 Authorization: Bearer <token>。

Dual-listener tunnel architecture — 当 pair-agent 启动ngrok tunnel时，daemon绑定两个HTTP listener：

• Local listener — 始终绑定，服务完整命令面。永不转发。
• Tunnel listener — 惰性绑定，只服务锁定允许列表的端点。

安全属性来自物理端口分离：tunnel caller无法访问 /health 或 /cookie-picker，因为这些路径在那个TCP socket上不存在。

Cookie安全：

1. Keychain访问需要用户批准（macOS Keychain对话框）
2. 解密在进程内完成，明文永不写入磁盘
3. 数据库只读（复制到临时文件避免SQLite锁冲突）
4. Key缓存是per-session的（server关闭后缓存消失）
5. Cookie值永不出现在日志中

3.5 Prompt Injection防御

Chrome sidebar agent有工具（Bash、Read、Glob、Grep、WebFetch）并读取敌对网页，所以它是gstack最暴露于prompt injection的部分。防御是分层的（ARCHITECTURE.md）：

设计考虑： L6的ensemble rule是Stack Overflow误报缓解——单个分类器高置信度降级为WARN，因为”这个看起来像钓鱼”和”这是注入”难以区分。Canary leak始终BLOCK（确定性）。

3.6浏览器QA在流程中的角色

README中Garry Tan明确指出浏览器QA是他的 “massive unlock”：

“/qa was a massive unlock. It let me go from 6 to 12 parallel workers. Claude Code saying ‘I SEE THE ISSUE’ and then actually fixing it, generating a regression test, and verifying the fix — that changed how I work. The agent has eyes now.”

/qa 的完整流程：

1
2
3
4
5
6
7

1. 打开真实浏览器（复用持久 daemon）
2. 读取 test plan（从 plan-eng-review 产出）
3. 点击通过用户流程
4. 发现 bug（agent 看到 UI 不对）
5. 修复 bug（atomic commits——每个 fix 一个 commit）
6. 生成回归测试（确保 bug 不再重现）
7. 重新验证修复（再次运行用户流程确认）

设计考虑： 浏览器QA将”agent能看代码”扩展为”agent能看产品”。这是gstack的核心能力——agent拥有”眼睛”。Garry Tan声称这让他从6个并行worker扩展到12个，因为agent可以自主验证而不是依赖人工反馈。这意味着并行sprint的瓶颈从”人工验证速度”转移到了”模型API rate limit”——这是一个质的飞跃。

关键文件： ARCHITECTURE.md、BROWSER.md、browse/src/commands.ts、browse/src/server.ts

4. 设计哲学

4.1 Boil the Ocean

ETHOS.md 开篇就颠覆了传统工程智慧：

“‘Don’t boil the ocean’ was the right advice when engineering time was the bottleneck. That era is over. AI-assisted coding makes the marginal cost of completeness near-zero, so the old caution has quietly turned into an excuse.”

核心论点：当完整实现比捷径只多花几分钟时，每次都做完整的事。

Ocean, lakes first： 海洋是目的地——100% 测试覆盖率、完整功能实现、所有edge case、完整错误路径。你一个湖一个湖地到达——每个湖是一个可沸腾的单元，不是天花板。”That’s boiling the ocean” 不再是ship捷径的理由——沸腾海洋是目标。唯一仍然在scope外的是真正无关的工作：与当前任务无关的多季度平台迁移。

反模式vs正确做法：

设计考虑： Boil the Ocean哲学被注入到每个skill的preamble中。Completeness Principle 要求在选项覆盖度不同时标注 Completeness: X/10（10 = 完整，7 = happy path，3 = 捷径）。这不只是口号，而是编码到了AskUserQuestion的格式规范中——每个决策都必须标注完整性评分，让用户在选择时明确知道”我在用多少完整性换取简洁性”。

取舍： Boil the Ocean的风险是范围蔓延——“完整”的定义可能无限膨胀。gstack的缓解是”唯一在scope外的是真正无关的工作”——但判断”无关”本身是主观的。User Sovereignty原则在这里起到了制衡作用——即使用户说”只做最小版本”，用户赢。

4.2 User Sovereignty

ETHOS.md 的第三条原则是覆盖所有其他规则的一票否决权：

“AI models recommend. Users decide. This is the one rule that overrides all others.”

核心论点：两个AI模型同意一个变更是一个强信号，但不是命令。用户始终有模型缺乏的上下文：领域知识、业务关系、战略时机、个人品味、未分享的未来计划。当Claude和Codex都说”合并这两个东西”而用户说”不，保持分开”——用户是对的。总是。

generation-verification loop： AI生成推荐 → 用户验证和决策 → AI永不因为自信而跳过验证步骤。

规则： 当你和另一个模型同意改变用户已说明方向时——呈现推荐、解释为什么你们都认为更好、说明你可能缺少什么上下文、然后问。永不擅自行动。

设计考虑： User Sovereignty体现在多个层面：

• AskUserQuestion格式要求每个决策都有 Recommendation 和 (recommended) 标签，但最终选择权在用户
• /plan-ceo-review 的Expansion opt-in ceremony：每个扩展提案都是单独的AskUserQuestion，用户opt in或out
• /codex 的跨模型审查结果被标记为”recommendation, not decision”
• 这意味着即便Boil the Ocean说”做完整的事”，如果用户说”只做最小版本”，用户赢。

4.3跨模型审查

/codex skill获取来自OpenAI Codex CLI的独立审查——一个完全不同的AI看同一个diff（README.md）。三种模式：

1. review — pass/fail gate代码审查
2. adversarial challenge — 主动尝试打破你的代码
3. open consultation — 带session连续性的开放咨询

当 /review（Claude）和 /codex（OpenAI）都审查了同一分支时，gstack生成跨模型分析——显示哪些发现重叠、哪些是各自独有的。

设计考虑： 跨模型审查的核心价值是模型偏差消除——Claude可能系统性地忽略某类问题，Codex可能忽略另一类。两个不同模型的交叉验证比单个模型的两次审查更有价值。

取舍： 跨模型审查需要两个AI服务的API key，增加了成本和配置复杂度。Codex审查的E2E测试使用Codex自己的auth（~/.codex/ config），不需要 OPENAI_API_KEY env var——这降低了配置门槛但仍依赖Codex CLI安装。

4.4 Continuous Checkpoint

设置 gstack-config set checkpoint_mode continuous 后，skill在工作过程中自动commit（README.md）：

1
2
3
4
5
6
7
8

WIP: <concise description of what changed>

[gstack-context]
Decisions: <key choices made this step>
Remaining: <what's left in the logical unit>
Tried: <failed approaches worth recording> (omit if none)
Skill: </skill-name-if-running>
[/gstack-context]

• /context-restore 读取这些commit重建session状态
• /ship 在PR前过滤压缩WIP commit（保留非WIP commit），保持bisect干净
• Push是opt-in的（checkpoint_push=true）——默认只本地commit，不触发CI

设计考虑： Continuous Checkpoint解决了两个问题：

1. Crash恢复 — session崩溃后，WIP commit保留了工作进度和决策上下文
2. Context切换 — 在10-15个并行sprint之间切换时，[gstack-context] 块记录了”做到哪了、还剩什么、试过什么”

4.5 Search Before Building

ETHOS.md 的第二条原则——1000x工程师的第一反应是”有人已经解决了吗？”而非”让我从头设计”。

三层知识：

1. Layer 1: Tried and true — 标准模式、久经考验的方法。检查成本接近零。
2. Layer 2: New and popular — 当前最佳实践、博客文章、生态趋势。搜索但审视——人群对新事物和旧事物一样可能出错。
3. Layer 3: First principles — 从对特定问题的推理中得出的原创观察。最有价值。 Prize them above everything else.

Eureka Moment： 搜索的最有价值结果不是找到可复制的方案，而是：(1) 理解大家在做什么和为什么（Layer 1+2），(2) 对他们的假设应用第一性原理推理（Layer 3），(3) 发现常规方法为什么错的清晰理由。这是11 out of 10。

设计考虑： Search Before Building被注入到每个skill的preamble中。在构建不熟悉的模式前，agent被指示先搜索。当第一性原理推理与常规智慧矛盾时，agent被要求”命名eureka moment”并记录到 ~/.gstack/analytics/eureka.jsonl。

5. 并行sprint管理

5.1 Conductor并行

gstack与 Conductor 深度集成——Conductor运行多个Claude Code session并行，每个在自己的隔离workspace（README.md）：

“I regularly run 10-15 parallel sprints — that’s the practical max right now.”

Garry Tan的场景描述：一个session运行 /office-hours 探索新想法，另一个做 /review 审查PR，第三个实现功能，第四个在staging上运行 /qa，还有六个在其他分支上。全部同时进行。

5.2并行的前提：Sprint结构

README明确指出并行的前提是流程结构：

“The sprint structure is what makes parallelism work. Without a process, ten agents is ten sources of chaos. With a process — think, plan, build, review, test, ship — each agent knows exactly what to do and when to stop. You manage them the way a CEO manages a team: check in on the decisions that matter, let the rest run.”

设计考虑： 流程是并行的基础——没有流程，10个agent是10个混乱源。sprint结构让每个agent知道”做什么和何时停止”。

5.3并行基础设施

gstack为并行sprint提供了多项基础设施：

ELI16 mode： 当3+ 个session运行时，所有skill进入ELI16 mode——每个AskUserQuestion都重新为用户建立上下文（项目名、分支名、当前任务），因为用户正在多个窗口之间切换。

gstack-detach： 长running任务（如eval套件）通过 gstack-detach 运行而非普通background bash——它创建新session（逃逸process group SIGTERM）并包装在 caffeinate -i 中（阻止idle-sleep）。detached run即使watcher被回收也能在日志中检查。

Machine-wide eval lock： 共享dev box上的多个Conductor worktree会rate-limit model API。eval lock让第二个run等待而非碰撞。

Workspace-aware ship： gstack-next-version 检测其他worktree是否已claim同一版本号，避免版本冲突。

Random port selection： 浏览器daemon使用10000-60000的随机端口（最多重试5次），意味着10个Conductor workspace各自运行自己的browse daemon，零配置、零端口冲突。

5.4 Cross-session Decision Memory

gstack维护一个append-only、event-sourced的决策存储（CLAUDE.md）：

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

# 捕获持久决策
~/.claude/skills/gstack/bin/gstack-decision-log \
  '{"decision":"use PostgreSQL for audit log",
    "rationale":"need ACID + JSONB",
    "scope":"repo",
    "source":"user",
    "confidence":9}'

# 检索过去决策
~/.claude/skills/gstack/bin/gstack-decision-search --recent 5

# 反转先前决策（显式声明）
~/.claude/skills/gstack/bin/gstack-decision-log \
  '{"decision":"switch to MongoDB for audit log",
    "rationale":"write volume too high for PG",
    "supersedes":"<previous-decision-id>"}'

决策记录结构：

1
2
3

{"id":"dec-001","timestamp":"2026-03-15T10:00:00Z","decision":"use PostgreSQL for audit log","rationale":"need ACID + JSONB","scope":"repo","source":"user","confidence":9}
{"id":"dec-002","timestamp":"2026-03-16T14:00:00Z","decision":"use event sourcing pattern","rationale":"need full audit trail","scope":"branch","source":"skill:plan-ceo-review","confidence":8}
{"id":"dec-003","timestamp":"2026-03-17T09:00:00Z","decision":"switch to MongoDB for audit log","rationale":"write volume too high for PG","supersedes":"dec-001","scope":"repo","source":"user","confidence":10}

设计考虑： 决策存储解决了一个独特的并行问题——当10个sprint同时运行时，一个sprint做的架构决策不应该被另一个sprint重新讨论。决策存储让”已决定的事不再重新讨论”成为可能。--supersede <id> 允许反转先前的决策，但要求显式声明——这确保了决策变更是可审计的，而不是静默的覆盖。append-only的设计意味着历史决策永远不会被删除，只能被supersede——这为团队回顾提供了完整的决策演化轨迹。

5.5 GBrain：持久知识库

GBrain是gstack的可选持久知识库——AI agent跨session保留的记忆（README.md）：

• PGLite local — 零账号、零网络，~30秒
• Supabase existing URL — 云端agent已provisioned的brain
• Supabase auto-provision — 自动创建新项目
• Remote gbrain MCP — brain运行在另一台机器上

/sync-gbrain 将repo代码重新索引到gbrain，在CLAUDE.md中写入 ## GBrain Search Guidance 块，让agent优先使用 gbrain search 而非Grep。

Per-remote trust policy： 每个repo有三种信任级别：

• read-write — agent可以搜索brain并从这个repo写回新页面
• read-only — agent可以搜索但不能写（适合多客户顾问：搜索共享brain，不污染客户A的工作）
• deny — 无gbrain交互

设计考虑： GBrain解决了并行sprint的知识共享问题——一个sprint学到的代码库模式可以被另一个sprint搜索到。Per-remote trust policy处理了多客户场景的知识隔离。

6. 其他关键设计模式

6.1 AskUserQuestion格式

gstack定义了一套极其详细的AskUserQuestion格式规范（plan-ceo-review/SKILL.md）。这是gstack将”如何向用户提问”从隐性的最佳实践提升为显性的结构化规范的核心机制。

格式模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

D<N> — <one-line question title>
Project/branch/task: <1 short grounding sentence using _BRANCH>
ELI10: <plain English a 16-year-old could follow, 2-4 sentences, name the stakes>
Stakes if we pick wrong: <one sentence on what breaks, what user sees, what's lost>
Recommendation: <choice> because <one-line reason>
Completeness: A=X/10, B=Y/10
Pros / cons:
A) <option label> (recommended)
  ✅ <pro — concrete, observable, ≥40 chars>
  ❌ <con — honest, ≥40 chars>
B) <option label>
  ✅ <pro>
  ❌ <con>
Net: <one-line synthesis of what you're actually trading off>

实际示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

D2 — How should we handle session storage?
Project/branch: feature/auth on checkout-service
ELI10: When a user logs in, we need to remember who they are across 
requests. We can store sessions in Redis (fast, separate) or JWT 
(stateless, no lookup needed). The choice affects scaling and logout.
Stakes if we pick wrong: If we pick JWT and need server-side logout, 
we'll need a revocation list — effectively building Redis anyway.
Recommendation: A because we need instant logout for compliance.
Completeness: A=9/10, B=7/10
Pros / cons:
A) Redis-based sessions (recommended)
  ✅ Server-side logout is instant — delete the key and the session is dead
  ❌ Adds Redis as a dependency — one more thing to monitor and scale
B) JWT-based sessions
  ✅ No session store needed — stateless means horizontal scaling is trivial
  ❌ Logout is soft — token lives until expiry unless we add revocation list
Net: You're trading operational simplicity (B) for compliance control (A).

5+ 选项处理： AskUserQuestion限制每次调用最多4个选项。gstack要求永不丢弃选项——要么batch成 ≤4组，要么split成per-option调用（D3.1, D3.2, …）。split chain的question_id永不被AUTO_DECIDE——用户的选项集是神圣的。

Conductor兼容： Conductor禁用native AUQ且其MCP变体不稳定，gstack检测Conductor环境并自动切换到prose fallback——将决策brief渲染为markdown消息而非工具调用。

设计考虑： 这套格式规范解决了一个真实问题——AI的提问经常模糊、缺少推荐、无法让用户快速决策。gstack将提问结构化为”decision brief”，要求每个问题都有ELI10、推荐、完整性评分、pros/cons和net tradeoff。

6.2 Confusion Protocol

对于高风险的模糊性（架构、数据模型、破坏性scope、缺失上下文），skill被指示STOP——用一句话命名问题，呈现2-3个选项带tradeoff，然后问。不用于常规编码或明显变更。

设计考虑： Confusion Protocol是一个轻量级gate——只在”高风险模糊性”时触发。它依赖agent的判断力区分”需要STOP”和”可以继续”。

6.3 Slop-scan

gstack使用 slop-scan 检测AI生成代码的质量问题（CLAUDE.md）：

“We use slop-scan to catch patterns where AI-generated code is genuinely worse than what a human would write. We are NOT trying to pass as human code. We are AI-coded and proud of it. The goal is code quality.”

What to fix： 空catch块（用 safeUnlink() 代替）、冗余 return await、类型化异常捕获。

What NOT to fix： 错误消息字符串匹配（Playwright/Chrome可能改变措辞）、为通过slop-scan豁免而添加的注释、扩展catch-and-log转selective rethrow。

设计考虑： slop-scan的哲学是”AI代码质量，不是AI代码隐藏”——不试图伪装成人类代码，而是确保AI生成的代码不比人类写的差。这与gstack的 “AI-coded and proud of it” 立场一致。

6.4 Redaction Guard

共享redaction引擎在credentials、PII和法律/损害性内容到达外部sink（codex dispatch、GitHub issue/PR body、pushed commit）之前捕获它们（CLAUDE.md）。

三个级别：

• HIGH — 真正的秘密凭证，阻断
• MEDIUM — PII/法律/内部 + 高FP凭证形状，通过AskUserQuestion确认
• LOW — FYI

设计考虑： Redaction Guard是”guardrail, not airtight enforcement”——git push --no-verify 等方式可以绕过。它捕获事故和粗心，99% 的情况。

6.5 Domain Skills

$B domain-skill save 让agent保存per-site笔记（如”LinkedIn的Apply按钮在iframe中”），下次访问该hostname时自动触发（README.md）。

隔离 → 3次成功使用后激活 → 可选通过 $B domain-skill promote-to-global 跨项目提升。

设计考虑： Domain Skills让浏览器agent 随时间积累站点知识——第一次访问LinkedIn时发现按钮在iframe中，之后每次访问都自动知道。这是”agent变聪明”的具体体现。

6.6 /spec 五阶段spec创作

/spec 将模糊意图转化为精确、可执行的spec，分五个阶段（README.md）：

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

Phase 1: Why
  │  └── 问题陈述：为什么要做这个？解决什么痛点？
  ▼
Phase 2: Scope
  │  └── 范围定义：做什么、不做什么、边界在哪里？
  ▼
Phase 3: Technical
  │  └── 技术方案（强制代码阅读）
  │      ├── 读取现有代码理解当前架构
  │      ├── 识别需要修改的模块
  │      └── 不允许凭空设计
  ▼
Phase 4: Draft
  │  └── 草稿：整合前三个阶段的输出为完整 spec 文档
  ▼
Phase 5: File
     └── 归档到 $GSTACK_STATE_ROOT/projects/$SLUG/specs/
         └── Codex quality gate：低于 7/10 的 spec 被阻断

--execute 标志在全新worktree中spawn claude -p；/ship 在merge时自动关闭源issue。

设计考虑： /spec 的Technical阶段强制代码阅读——不允许凭空设计。这是gstack “Search Before Building” 原则在spec阶段的具体体现。Codex quality gate在File阶段前阻断低于7/10的spec——这确保了归档的spec有最低质量保障。Fail-closed secret redaction在写入前阻断HIGH级别秘密——即使spec中不小心包含了凭证，也不会被写入磁盘。

取舍： /spec 的五阶段流程比mattpocock的 to-spec（一行指令）重得多。但gstack的立场是”拥有完整流程”——spec阶段的严谨性是后续阶段质量的保证。

7. 演进中的关键教训

模式： 从单skill到并行工厂——gstack的演进主线是从单个浏览器工具（/browse、/qa），逐步扩展为覆盖完整sprint的23+ skills体系，核心驱动力是并行sprint场景带来的新约束（ELI16、detach、eval lock、decision memory）。

8. 能力边界

7.1擅长

• 全sprint覆盖：从Think到Reflect的完整7阶段流程，23+ skills覆盖每个阶段
• 浏览器QA：持久Chromium守护进程 + Ref系统 + prompt injection防御，agent有”眼睛”
• 跨模型审查：/codex 获取OpenAI独立审查，跨模型分析显示重叠和独有发现
• 设计探索：/design-shotgun（4-6个AI mockup变体 + 比较板）→ /design-html（生产质量HTML）
• 并行sprint：Conductor 10-15并行 + ELI16 mode + gstack-detach + workspace-aware ship
• 持久记忆：learnings.jsonl + decisions.jsonl + timeline.jsonl + GBrain语义搜索
• 多agent协调：/pair-agent 跨agent共享浏览器，scoped tokens + tab隔离 + rate limiting
• 安全防御：dual-listener tunnel + 6层prompt injection防御 + redaction guard
• iOS QA：/ios-qa 驱动真实iPhone（USB CoreDevice），--tailnet 暴露给远程agent

7.2不擅长

• Spec演进追踪：/spec 产出一次性spec文档，没有delta机制、没有source of truth、没有archive合并
• Brownfield增量规格化：没有”只文档化要改的部分”的能力——spec是全量的而非增量的
• 变更可审计：没有change文件夹完整保留机制——artifact分散在多个路径
• 轻量入门：23+ skills + 8 power tools + preamble + section文件，学习曲线陡峭
• 跨平台一致性：虽然适配10个host，但浏览器能力（核心卖点）依赖Playwright + Bun，在某些平台（Windows）有已知问题
• 流程弹性：sprint结构是强约束——Dashboard会显示缺失的审查，流程弹性有限

7.3演进特征

从README和CLAUDE.md可以看出gstack的演进特征：

1. 从单一skill到sprint流程：最初可能只有 /browse 和 /qa，逐步扩展到23+ skills覆盖完整sprint
2. 从Claude-only到多平台：最初只支持Claude Code，逐步适配Codex、Cursor、Factory等10个host
3. 从简单浏览器到安全浏览器：从基本Playwright驱动到6层prompt injection防御 + dual-listener tunnel + domain skills
4. 从手动到自动化：从手动运行每个skill到 /autoplan 自动化计划阶段 + Continuous Checkpoint自动commit
5. 从单sprint到并行sprint：从单session到Conductor 10-15并行 + ELI16 mode + workspace-aware ship

9. 设计决策清单

以下是从源码分析中提取的gstack的核心设计决策：

10. 总结

gstack的核心贡献不在于单个skill的设计（虽然许多skill设计精良），而在于：

1. Sprint链式传递：通过文件系统持久化artifact，实现了跨session、跨sprint的工程状态传递。每个skill的产出喂给下一个，Dashboard可视化流程状态。

2. 持久浏览器守护进程：长驻Chromium + Ref系统 + 6层prompt injection防御，让agent拥有”眼睛”——这是gstack区别于所有其他项目的核心能力。

3. 并行sprint管理：Conductor 10-15并行 + ELI16 mode + gstack-detach + workspace-aware ship + cross-session decision memory。流程是并行的基础——“without a process, ten agents is ten sources of chaos.”

4. 设计哲学体系：Boil the Ocean（完整是目标）、User Sovereignty（用户决策覆盖一切）、Search Before Building（三层知识）、跨模型审查（模型偏差消除）、Continuous Checkpoint（自动WIP commit）。这些不是口号，而是编码到了preamble、AskUserQuestion格式和skill工作流中。

5. 全栈覆盖：从设计探索（/design-shotgun）到iOS QA（/ios-qa），从安全审计（/cso）到文档同步（/document-release），23+ skills覆盖完整工程团队的所有角色。

它的局限也很明确：缺乏spec演进追踪（没有delta机制和source of truth）、重量级（学习曲线陡峭）、流程弹性有限（sprint结构是强约束）。这些局限是”拥有完整流程”立场的必然结果——如果你拥有流程，就需要维护流程的每个环节。

gstack是五个项目中最接近”虚拟工程团队”愿景的。它的设计决策围绕一个核心信念：AI时代，一个人可以做一个团队的事，但前提是工具链足够完整和自动化。 Boil the Ocean不是鼓励过度工程，而是指出”完整的边际成本接近零”这一新现实。

点击下方”阅读原文“进入我的演示网站。

日期： 2026-07-11
核心问题： 一个明确”不拥有流程”的skill集合，如何在保持小巧可组合的同时提供工程基础？它的需求澄清方法论有什么独特之处？

1. 架构拆解

1.1 Skill分类体系

mattpocock-skills的自我定位是 “Skills For Real Engineers — my agent skills that I use every day to do real engineering - not vibe coding”（README.md）。这个定位的核心信号是：这是一个个人实践工具集，不是企业框架。它由Matt Pocock（TypeScript教育者、Total TypeScript作者）以个人身份维护，每个skill都经过日常工程实践验证。

仓库结构（CLAUDE.md）：

1
2
3
4
5
6
7
8
9
10
11

mattpocock-skills/
├── skills/
│   ├── engineering/      # 日常代码工作（promoted）
│   ├── productivity/     # 日常非代码工具（promoted）
│   ├── misc/             # 保留但少用（不 promoted）
│   ├── personal/         # 个人专用（不 promoted）
│   ├── in-progress/      # 草稿（不 promoted）
│   └── deprecated/       # 已弃用
├── docs/                 # 每个 promoted skill 对应一个人面文档页
├── scripts/              # link-skills.sh, list-skills.sh
└── .claude-plugin/       # plugin manifest

设计考虑： promoted（engineering/ + productivity/）与非promoted的分界线很清晰——只有promoted skill才出现在 README.md、.claude-plugin/plugin.json 和 docs/ 中。这意味着用户看到的只是”成熟”的skill，in-progress和deprecated的不会造成噪音。CLAUDE.md 明确维护规则：添加、重命名或行为变更时需要同步README、plugin.json和docs页面。

取舍： promoted/non-promoted的分界让仓库同时充当”发布渠道”和”实验场”——好处是个人迭代和公开发布在同一个仓库，代价是仓库结构比纯发布仓库复杂。

1.2 User-invoked vs Model-invoked

这是mattpocock-skills最核心的架构决策之一。它决定了skill的触发方式、context load和在流程中的角色。

README明确指出：

“These split on one axis — who can invoke them. User-invoked skills are reachable only when you type them (e.g. /grill-me); their job is to orchestrate. Model-invoked skills can be invoked by you or reached for automatically by the agent when the task fits; they hold the reusable discipline. A user-invoked skill may invoke model-invoked skills, but never another user-invoked one.”

技术实现上，这个区分通过frontmatter中的 disable-model-invocation: true 标志控制（CLAUDE.md）。

User-invoked skill frontmatter示例：

1
2
3
4
5
6

---
disable-model-invocation: true
---
# grill-with-docs

Run a `/grilling` session, using the `/domain-modeling` skill.

Model-invoked skill frontmatter示例：

1
2
3
4
5
6
7

---
# grilling

When the user needs to clarify a vague idea, refine a design, or work through 
decisions before implementing. Trigger phrases: "grill me", "help me think through",
"I'm not sure about", "what should I do about"...
---

• User-invoked skill：设置 disable-model-invocation: true，agent无法自动触发，只有用户输入 /skill-name 才能调用。description变成人面摘要（不含触发短语）。
• Model-invoked skill：不设 disable-model-invocation，agent可以通过description自动匹配触发，用户也可以手动调用。description是机器可读的触发器，包含丰富的触发短语。

writing-great-skills/SKILL.md 和 writing-great-skills/GLOSSARY.md 将这个决策的理论基础阐述得非常透彻。

两种负荷的权衡：

选择标准：”Pick model-invocation only when the agent must reach the skill on its own, or another skill must reach it. If it only ever fires by hand, make it user-invoked and pay no context load.”

当前skill分类：

设计考虑： 分类逻辑非常清晰——编排类skill（orchestrator）是user-invoked，可复用的纪律性skill（discipline）是model-invoked。这种二分法将”人控制流程入口，agent自动执行纪律”的意图编码进了技术架构。

1
2
3
4
5
6
7
8

用户输入 /implement（user-invoked）
    │
    ├── 内部驱动 /tdd（model-invoked）
    │   └── red → green → seam
    │
    └── 内部驱动 /code-review（model-invoked）
        ├── Standards sub-agent
        └── Spec sub-agent

例如 /implement 是user-invoked（用户决定何时开始实现），但它内部驱动的 /tdd 和 /code-review 是model-invoked（implement或其他skill可以自动调用它们）。user-invoked skill可以调用model-invoked skill，但永远不能调用另一个user-invoked skill——这是架构的硬约束。

取舍： 这种二分法将”人控制流程入口，agent自动执行纪律”的意图编码进了技术架构。代价是当user-invoked skill数量增多时，用户面临cognitive load——ask-matt router skill就是为解决这个问题而引入的（见1.3）。

1.3 ask-matt Router Skill

ask-matt 是v1.0.0引入的 router skill——一个user-invoked skill，它的工作是指向其他user-invoked skill（ask-matt/SKILL.md）。

writing-great-skills/GLOSSARY.md 定义了router skill的本质：

“A router skill is a user-invoked skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no description, so nothing but the human can reach them. The cure for cognitive load when user-invoked skills multiply.”

ask-matt 将所有skill组织为一个 main flow（idea → ship）加两个 on-ramps（bugs/triage和foggy/huge/wayfinder），以及若干standalone skill。它定义了”main flow”的路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Main Flow（idea → ship）:

/grill-with-docs ──→ /to-spec ──→ /to-tickets ──→ /implement
     │                  │              │              │
     │                  │              │              ├── /tdd (model-invoked)
     │                  │              │              └── /code-review (model-invoked)
     │                  │              │
     │                  │              └── tracer-bullet tickets (垂直切片)
     │                  │
     │                  └── PRD/spec 文档
     │
     └── grilling + domain-modeling → CONTEXT.md

On-ramps:
  - bugs/triage → /triage → /implement
  - foggy/huge → /wayfinder → (tickets → /implement)

Optional branch:
  /grill-with-docs → /prototype → /to-spec → ...

还有一个 context hygiene 规则：步骤1-3保持在一个不中断的context window中，直到 /to-tickets 完成后才清理。这基于 smart zone 概念——约120k token的窗口范围内模型推理仍然敏锐。

设计考虑： ask-matt的维护规则写入了 CLAUDE.md——任何skill的添加/重命名/删除或流程变更都需要重新审查ask-matt，使其保持准确。v1.1.0的changelog记录了一次大规模的ask-matt同步：补上了之前遗漏的5个skill（tdd、diagnosing-bugs、domain-modeling、codebase-design、grilling），说明router skill的维护是一个持续的挑战。

取舍： router skill降低了cognitive load（用户只需记住一个入口），但引入了维护负担——router必须与实际skill集合保持同步，否则它会”说谎”。

1.4 “不拥有流程”的设计立场

README开篇就明确了立场：

“Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve. These skills are designed to be small, easy to adapt, and composable.”

这个立场意味着：用户拥有流程，skill是工具而非框架。修改成本极低——直接改SKILL.md即可即时生效，skill之间松散耦合可任意组合。

关键文件： README.md、ask-matt/SKILL.md

2. “不拥有流程”的设计立场

2.1立场的本质：工具而非框架

mattpocock-skills的”不拥有流程”不是消极的不作为，而是一种积极的设计选择。ask-matt/SKILL.md 中的main flow定义了一条推荐路径（grill-with-docs → to-spec → to-tickets → implement），但每个节点都可以独立使用：

• 用户可以从 /implement 直接开始（跳过grill和spec）
• 可以只用 /grill-me 整理想法然后手动实现
• 可以在已有spec的情况下直接 /to-tickets

设计考虑： “不拥有流程”意味着skill不强制执行路径。ask-matt 是”建议者”而非”执行者”——它告诉你有哪些skill可用、它们之间的关系是什么，但最终由用户决定走哪条路。

mattpocock-skills没有自动拦截机制，没有HARD-GATE，没有bootstrap hook。

取舍： 不拥有流程给了用户最大灵活性，但也意味着没有安全网——用户可以跳过grilling直接写代码，skill不会阻止。mattpocock-skills认为用户是理性的成年人，可以选择何时用哪个工具。

2.2 “小而可组合”的边界

writing-great-skills/SKILL.md 定义了skill拆分的两个标准（granularity）：

1. By invocation：当一个skill有独特的leading word需要独立触发时拆分。代价是新增一个model-invoked skill的context load。
2. By sequence：当后续步骤的存在会诱导agent跳过当前步骤（premature completion）时拆分。

反过来说，不满足这两个条件就不应该拆分。v1.1.0的changelog记录了一次重要的合并：to-prd 重命名为 to-spec，to-plan 和 to-issues 合并为 to-tickets，to-issues 被删除。这次合并的理由是：这几个skill在实际使用中总是连续调用，拆分反而增加了认知负担和上下文切换成本。

关键文件： writing-great-skills/SKILL.md、writing-great-skills/GLOSSARY.md、CHANGELOG.md v1.1.0

取舍： 合并减少了skill数量和认知负担，但合并后的单个skill复杂度增加。to-tickets 现在同时处理tracer-bullet切分和wide refactor两种场景，通过reference section而非step来组织——这是 “information hierarchy” 原则的应用。

3. Grilling式需求澄清

3.1 Grilling的核心设计

Grilling是mattpocock-skills最具特色的方法论。grilling/SKILL.md 全文仅13行，但包含4个精确的设计决策：

1. 一次一个问题：”Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.”
2. 遍历决策树：”Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.”
3. 每个问题附推荐答案：”For each question, provide your recommended answer.”
4. 事实与决策分离：”If a fact can be found by exploring the codebase, look it up rather than asking me. The decisions, though, are mine — put each one to me and wait for my answer.”

grilling/SKILL.md 全文：

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

---
# grilling

When the user needs to clarify a vague idea, refine a design, or work through 
decisions before implementing...
---

Ask the questions one at a time, waiting for feedback on each question before 
continuing. Asking multiple questions at once is bewildering.

Walk down each branch of the design tree, resolving dependencies between 
decisions one-by-one.

For each question, provide your recommended answer.

If a *fact* can be found by exploring the codebase, look it up rather than 
asking me. The *decisions*, though, are mine — put each one to me and wait 
for my answer.

grill-me 和 grill-with-docs 都是user-invoked skill，它们的实现极其简洁——grill-me/SKILL.md 全文只有”Run a /grilling session.”一行，grill-with-docs/SKILL.md 只有”Run a /grilling session, using the /domain-modeling skill.”一行。这是deliberate的设计——grilling是model-invoked的可复用原语，两个user-invoked skill只是不同的入口。

设计考虑： 13行的SKILL.md是mattpocock “小而可组合”哲学的极致体现。没有step-by-step workflow，没有elaborate的问题模板，只有4条核心规则。这种极简设计依赖于agent的内在能力——模型已经知道如何提问和遍历决策树，skill只需要锚定关键行为约束（一次一问、推荐答案、事实/决策分离）。

关键文件： grilling/SKILL.md、grill-me/SKILL.md、grill-with-docs/SKILL.md

3.2事实与决策的分离

v1.1.0的changelog记录了grilling的一个重要演进——Facts vs. Decisions 分离：

“The old blanket line — ‘if a question can be answered by exploring the codebase, explore the codebase instead’ — was written for the live-human case, but once another skill runs grilling inside a resolve-the-ticket frame it read as license to answer decisions autonomously too. Separating the two keeps a grilling agent from racing ahead and answering its own questions.”

这个教训说明：当grilling被其他skill（如 triage、wayfinder）内部调用时，原来”能从代码库推断就别问用户”的规则被过度泛化了——agent开始替用户做决策。分离后，事实（可从代码库推断的技术事实）由agent自己查，决策（产品/业务约束）必须问用户。

事实/决策分离让grilling既可用于人工对话（grill-me），也可嵌入自动化流程（triage、wayfinder）而不越界。

取舍： 代价是需要agent有足够的判断力区分”事实”和”决策”——这不是总能做到的。

3.3确认门控

v1.1.0还为grilling加了确认门控：

“The agent won’t enact the plan until you confirm the shared understanding has been reached — turning the skill’s existing ‘shared understanding’ completion criterion into an explicit stop-gate.”

这是一种轻量门控——没有拦截机制，只是grilling skill自身的完成标准。agent不会在用户确认前开始执行计划。

4. Shared Language（CONTEXT.md）

4.1 CONTEXT.md的定位

README将CONTEXT.md称为”the single coolest technique in this repo”，并将其与DDD（Domain-Driven Design）的Ubiquitous Language概念直接关联：

“With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.” — Eric Evans

domain-modeling/SKILL.md 定义了CONTEXT.md的本质：

“CONTEXT.md should be totally devoid of implementation details. Do not treat CONTEXT.md as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.”

CONTEXT-FORMAT.md 定义了格式规范：每个术语包含定义 + _Avoid_ 列表（要避免的同义词）。

CONTEXT.md格式示例：

1
2
3
4
5
6
7
8
9
10
11

## Order
A customer's request to purchase one or more items from a store.
_Avoid_: purchase, transaction, basket

## Fulfillment
The process of picking, packing, and shipping an order.
_Avoid_: delivery, dispatch, handling

## OrderPlaced
An event emitted when an order is confirmed by the customer.
_Avoid_: order-created, order-submitted

_Avoid_ 的设计是 opinionated 的——“When multiple words exist for the same concept, pick the best one and list the others under _Avoid_.” 这不是建议性的——当多个开发者使用不同词汇描述同一概念时，命名不一致会在代码库中蔓延。_Avoid_ 列表通过明确禁止同义词，在团队层面强制统一术语。

设计考虑： CONTEXT.md是纯粹的术语表，不包含实现细节。它是语言契约（只定义术语），而非行为契约。这个定位让CONTEXT.md的维护成本极低——只在有新术语确定时更新，不随代码重构而变化。

4.2 CONTEXT.md的收益

README列举了CONTEXT.md的四重收益：

1. 减少verbosity：agent不需要用20个词描述1个词能表达的概念
2. 命名一致性：变量名、函数名、文件名都使用shared language
3. 代码库可导航性：一致的命名让agent更容易在代码库中导航
4. Token效率：agent有更简洁的语言可用，思考时消耗更少token

取舍： CONTEXT.md需要持续维护——每次有新术语确定时就更新（domain-modeling/SKILL.md 要求”Update CONTEXT.md inline… Don’t batch these up — capture them as they happen”）。如果不维护，CONTEXT.md会腐化成过时文档。但维护成本被分散到了日常grilling流程中——grill-with-docs 在grilling过程中自动调用 domain-modeling 更新CONTEXT.md。

4.3 ADR（Architecture Decision Records）

domain-modeling/SKILL.md 定义了ADR的三个触发条件——必须同时满足才创建：

1. Hard to reverse — 改变主意的成本有意义
2. Surprising without context — 未来读者会好奇”为什么这么做”
3. The result of a real trade-off — 有真正的替代方案并因特定理由选择了其中一个

ADR-FORMAT.md 的设计极简——“An ADR can be a single paragraph. The value is in recording that a decision was made and why — not in filling out sections.” 与传统的ADR模板（Context、Decision、Status、Consequences等多个section）相比，mattpocock的ADR刻意追求最小化。

ADR示例：

1
2
3
4
5

## We use event sourcing for order state

We chose event sourcing over CRUD because we need full audit trails 
for regulatory compliance. The trade-off is higher write complexity 
and eventual consistency on read models.

设计考虑： ADR的极简格式降低了创建门槛——如果ADR需要填很多section，agent和人都会倾向于跳过。一句话ADR的成本接近于零，但价值在于”记录了决策存在”这个事实本身。传统ADR模板有Context、Decision、Status、Consequences四个section，但大多数实际场景中，决策和理由可以在一段话内说清楚。多section模板的问题是它鼓励填充而非思考——人们会为了填满Consequences section而编造不必要的内容。

关键文件： domain-modeling/SKILL.md、domain-modeling/CONTEXT-FORMAT.md、domain-modeling/ADR-FORMAT.md、README.md

4.4 Multi-context支持

CONTEXT-FORMAT.md 定义了单context和多context两种模式：

• 单context（大多数repo）：根目录一个 CONTEXT.md
• 多context（monorepo）：根目录 CONTEXT-MAP.md 指向各子context的 CONTEXT.md

多context模式还支持context间关系描述（如 “Ordering → Fulfillment: Ordering emits OrderPlaced events”）。这体现了DDD的Bounded Context思想在AI辅助开发中的应用。

5. Two-axis Code Review

5.1双轴设计

code-review/SKILL.md 定义了一个独特的双轴审查模型：

• Standards — 代码是否符合repo文档化的编码标准？
• Spec — 代码是否忠实实现了原始issue/PRD/spec？

两个轴作为 parallel sub-agents 独立运行，互不污染context：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

/code-review（user-invoked）
    │
    ├── Standards sub-agent（独立 context）
    │   ├── 读取 repo 编码标准
    │   ├── 读取 Fowler smell baseline
    │   └── 审查 git diff → ## Standards 报告
    │
    └── Spec sub-agent（独立 context）
        ├── 查找原始 spec/issue/PRD
        ├── 对照 spec 审查代码
        └── → ## Spec 报告

最终报告：
    ## Standards  ← 不合并、不重排
    ## Spec       ← 独立呈现

最终的报告在 ## Standards 和 ## Spec 两个标题下分别呈现，不合并、不重排。

设计考虑： code-review/SKILL.md 的 “Why two axes” 段落解释了核心洞察：

“A change can pass one axis and fail the other: Code that follows every standard but implements the wrong thing → Standards pass, Spec fail. Code that does exactly what the issue asked but breaks the project’s conventions → Spec pass, Standards fail. Reporting them separately stops one axis from masking the other.”

取舍： 双轴分离确保两个维度的问题都可见，但代价是用户需要同时阅读两份报告。不合并的设计是有意的——“the two axes are deliberately separate”。

5.2 Standards轴的Fowler Smell Baseline

v1.1.0为Standards轴增加了 always-on Fowler smell baseline——一组来自Fowler《Refactoring》第3章的代码异味清单，作为固定基线叠加在repo自己的编码标准之上：

12种smell：Mysterious Name、Duplicated Code、Feature Envy、Data Clumps、Primitive Obsession、Repeated Switches、Shotgun Surgery、Divergent Change、Speculative Generality、Message Chains、Middle Man、Refused Bequest。

两条绑定规则：

1. The repo overrides — repo文档化的标准总是优先；如果repo认可某种baseline会标记的模式，抑制该smell。
2. Always a judgement call — 每个smell是标注式启发（”possible Feature Envy”），不是硬违规。

设计考虑： Fowler smell baseline确保即使repo没有任何编码标准文档，Standards轴也有最低限度的检查基线。同时通过”repo overrides”规则避免与项目既有约定冲突。

取舍： 内联12种smell到SKILL.md增加了文件长度，但确保了sub-agent有完整的baseline可用——sub-agent没有其他访问途径。这是 writing-great-skills 中 “in-skill reference” 层级的应用。

5.3 Spec轴的追溯

Spec轴需要找到原始spec/issue/PRD。code-review/SKILL.md 定义了查找顺序：

1. commit message中的issue引用（#123、Closes #45 等）
2. 用户传入的路径
3. docs/、specs/、.scratch/ 下匹配的文件
4. 找不到则问用户；用户说没有则Spec sub-agent跳过

设计考虑： Spec轴的价值在于”需求忠实度”检查——不只是代码好不好，而是代码做的是不是被要求做的事。在整个工作完成后由独立sub-agent检查。

关键文件： code-review/SKILL.md、CHANGELOG.md v1.1.0

6. Wayfinder与Tracer-bullet Tickets

6.1 Wayfinder：超大规模工作的”雾中探索”

wayfinder/SKILL.md 是仓库中最长、最复杂的skill，用于处理”too big for one agent session”的超大工作。

核心隐喻： Wayfinder借用游戏中的 fog of war（战争迷雾）概念——你无法看到全程，只能看到眼前。不是”冲向目的地”，而是”找到去目的地的路”。

Wayfinder的Map结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Issue Tracker
└── wayfinder:map (labeled issue)
    ├── ## Destination
    │   └── "We need to migrate from monolith to microservices"
    │
    ├── ## Frontier（当前正在处理的 tickets）
    │   ├── Ticket #42 (HITL) — Define service boundaries
    │   └── Ticket #43 (AFK) — Extract user service
    │
    ├── ## Fog of War（感知到但无法精确描述的问题）
    │   ├── "Data consistency across services is unclear"
    │   └── "Auth flow needs rethinking"
    │
    └── ## Resolved（已完成的 tickets）
        └── Ticket #41 — Initial audit complete

核心设计：

1. Map（地图）：issue tracker上的一个 wayfinder:map 标签的issue，是整个努力的”索引”（不是”仓库”）。地图只gist决策并链接到ticket，决策本身只存在于一个地方——它的ticket。
2. Ticket Types：Research（AFK）、Prototype（HITL）、Grilling（HITL）、Task（HITL或AFK）。每个ticket要么需要人工（HITL），要么可以全自动（AFK）。
3. Fog of war：地图的 “Not yet specified” 区域记录”你能感知到但还无法精确描述的问题”。随着frontier推进，fog逐渐”毕业”为具体ticket。
4. Plan, don’t do：Wayfinder默认是规划工具——产出决策而非交付物。”The pull to just do the work is usually the signal you’ve reached the edge of the map and it’s time to hand off.”
5. 一次一个ticket：”never resolve more than one ticket per session”——每个session只解决一个决策。

关键文件： wayfinder/SKILL.md

设计考虑： Wayfinder的设计哲学是”渐进式探索”——不试图一开始就规划全部，而是先创建能确定的ticket，让不确定的部分留在fog中，随着探索推进逐步清晰。这与传统的WBS（Work Breakdown Structure）形成对比——WBS要求自顶向下完全分解，Wayfinder允许自底向上渐进涌现。

取舍： Wayfinder的渐进式探索适合真正模糊的超大工作，但对于中小型工作可能过重——v1.1.0 changelog记录了一个 “no-fog early exit”：如果初始breadth-first grilling没有发现fog，说明工作足够小不需要map，直接停止。

6.2 Wayfinder的演进教训

v1.1.0 changelog记录了wayfinder从 in-progress/ 毕业到 engineering/ 的重要重构：

1. 重命名：decision-mapping → wayfinder。”Decision map” 太术语化且不准确——只有一种ticket类型是真正的决策。
2. Destination作为leading word：Wayfinding找的是”去目的地的路”，不是”冲向目的地”。每个map必须有 ## Destination 字段。
3. 从本地Markdown迁移到issue tracker：Map变成tracker上的一个issue，tickets是其child issues——一个共享URL让团队可以观看。
4. Native blocking：优先使用tracker原生的依赖关系，让frontier在tracker UI中可视化。
5. HITL/AFK分类：修复了”学生报告 /wayfinder自己回答自己的grilling问题”的bug——HITL ticket只能通过人工交互解决，agent不能代人回答。
6. Claim by assignment：通过assignee而非label来claim ticket——assignee就是claim。

关键教训： HITL/AFK分类解决了agent “自问自答”的问题。这与grilling的facts/decisions分离是同一类教训——当skill被自动化调用时，需要明确区分”哪些必须人工”和”哪些可以自动”。

6.3 Tracer-bullet Tickets

to-tickets/SKILL.md 将工作分解为 tracer-bullet tickets——每个ticket是一个完整的垂直切片：

1. 垂直而非水平：每个切片穿过所有层（schema、API、UI、tests），不是按层水平切分。
2. 可独立验证：完成的切片可以独立demo或验证。
3. 一个context window：每个ticket的大小适配一个全新的context window。
4. Blocking edges：每个ticket声明它依赖哪些其他ticket——形成DAG（有向无环图）。
5. Wide refactor例外：大规模机械式变更（如重命名列）无法做垂直切片，用expand-contract模式序列化。

设计考虑： tracer-bullet的核心思想来自The Pragmatic Programmer——“tracer bullets”是打出一条从端到端的完整弹道，每一发都能看到落点。在AI辅助开发中，这意味着每个ticket产出的不是一个层（如”写所有的model”），而是一个可验证的端到端行为。

设计考虑： to-tickets/SKILL.md 明确指出：”avoid specific file paths or code snippets — they go stale fast.” tickets追求”agent可以自主判断如何实现”。

取舍： 不含代码的tickets保护了TDD的有效性（执行者需要自己写测试和实现），但要求执行者（agent）有足够的能力理解行为描述并转化为代码。

关键文件： to-tickets/SKILL.md、wayfinder/SKILL.md

7. 其他关键设计模式

7.1 Smart Zone与Context Hygiene

ask-matt/SKILL.md 引入了 smart zone 概念——约120k token的窗口范围内模型推理仍然敏锐。基于此，main flow的步骤1-3（grill-with-docs → to-spec → to-tickets）要求保持在一个不中断的context window中：

“Keep steps 1–3 in one unbroken context window — don’t compact or clear until after /to-tickets — so the grilling, spec, and tickets all build on the same thinking.”

当session接近smart zone边界时，使用 /handoff 而非 /compact——/handoff 会创建一个新session并传递handoff文档，/compact 是在同一对话中压缩。ask-matt/SKILL.md 明确区分了两者的使用场景：

“/handoff forks; /compact continues.”

设计考虑： smart zone概念将”context管理”从隐性的最佳实践变成了显性的设计约束。它承认模型的推理能力有边界，不是无限的。

7.2 TDD的简化设计

tdd/SKILL.md 在v1.1.0经历了一次重要重构——从step-by-step workflow变成reference-only skill。

重构前（step-by-step workflow）：

1
2
3
4
5
6
7
8

## Step 1: Red
Write a failing test that describes the behavior...

## Step 2: Green
Write the minimum code to make the test pass...

## Step 3: Refactor
Improve the code while keeping tests green...

重构后（reference-only）：

1
2
3
4
5
6
7
8
9

# tdd

Test only at pre-agreed seams, confirmed with the user 
before any test is written.

## Anti-patterns
1. Implementation-coupled: mock internal collaborators...
2. Tautological: assertions recompute expected values...
3. Horizontal slicing: write all tests then all implementation...

changelog记录了原因：

“The red → green → refactor loop is anchored by leading words the model already holds, so the step-by-step Workflow was largely restating the loop.”

v1.1.0还做了一个重要的决策——删除了refactor阶段：

“TDD is now red → green; refactoring belongs to the review stage, so the refactor rule and refactoring.md moved out (its home is code-review).”

同时引入了 seam 作为leading word——“test only at pre-agreed seams, confirmed with the user before any test is written.”

三个anti-patterns：

1. Implementation-coupled：mock内部协作者、测私有方法→重构时测试就坏
2. Tautological：断言用代码自己的方式重算期望值→永远通过但零信心
3. Horizontal slicing：先写所有测试再写所有实现→测的是想象中的行为

设计考虑： mattpocock的TDD设计简洁——没有Iron Law、没有Rationalization表。它依赖leading word（red、green、seam、tracer bullet）和reference来引导行为，而非强制约束。

取舍： 简化的TDD更容易被采纳，但缺乏强制保障。这反映了mattpocock的基本立场：信任用户和agent的判断力。

7.3 Skill写作方法论

writing-great-skills/SKILL.md 和 GLOSSARY.md 构成了一套完整的skill写作理论体系。这是mattpocock-skills的元贡献——不只是提供skills，还提供如何写skills的理论。

核心概念：

Information Hierarchy详解：

• In-skill step：直接写在SKILL.md中的步骤——agent一定会看到
• In-skill reference：写在SKILL.md的reference section中——agent按需读取
• External reference：指向外部文件的链接——agent需要主动读取

优先使用高层级的信息放置，因为越低层级的信息，agent读取的概率越低。

Failure Modes详解：

• Premature completion：后续步骤的存在诱导agent跳过当前步骤——解决方法是拆分为独立skill
• Duplication：同一逻辑出现在多个skill中——解决方法是提取为model-invoked原语
• Sediment：旧规则积累但不再适用——解决方法是定期review和deprecated目录
• Sprawl：skill数量膨胀失控——解决方法是合并连续调用的skill
• No-op：skill不改变agent的默认行为——解决方法是no-op检测
• Negation：”don’t think of an elephant” 会让大象更突出——解决方法是描述目标行为

Negation 的设计特别有趣——“don’t think of an elephant” 会让大象更突出，所以应该描述目标行为（”write one-line comments”）而非禁止行为（”don’t write verbose comments”）。mattpocock认为正面列出反面行为并反驳反而会强化反面行为。这个认知来自认知科学中的”讽刺过程理论”（ironic process theory）——试图抑制某个想法反而会让它更突出。

7.4 Diagnosing Bugs的反馈循环优先

diagnosing-bugs/SKILL.md 的核心设计是 Phase 1 — Build a feedback loop 先于一切：

“This is the skill. Everything else is mechanical. If you have a tight pass/fail signal for the bug — one that goes red on this bug — you will find the cause.”

设计要求在有任何hypothesis之前先建立反馈循环——“If you catch yourself reading code to build a theory before this command exists, stop — jumping straight to a hypothesis is the exact failure this skill prevents.“

10种构建反馈循环的方式按优先级排列：failing test > curl/HTTP > CLI invocation > headless browser > replay trace > throwaway harness > property/fuzz > bisection > differential > HITL bash script。

设计考虑： mattpocock的版本具体列出了10种构建循环的方式，并引入了 “tight”（快速、确定性、agent可运行）的完成标准。

8. 能力边界

8.1擅长

• 小巧可组合：~20个promoted skill，每个都很短（grilling 13行，implement 15行），可以独立使用或组合
• 需求澄清方法论：grilling的”一次一问+推荐答案+事实/决策分离”是独特且实用的设计
• 领域语言建模：CONTEXT.md + ADR的极简设计让DDD思想以最低成本落地
• 双轴代码审查：Standards + Spec的分离避免了维度互相遮蔽
• 超大规模规划：Wayfinder的fog-of-war渐进式探索适合真正模糊的大工作
• Skill写作理论：writing-great-skills 提供了一套完整的skill设计词汇表
• 工程基础扎实：TDD、debugging、codebase design、prototype各有独立的discipline skill

8.2不擅长

• 统一流程约束：不拥有流程意味着没有HARD-GATE、没有强制执行——完全依赖用户自律
• Spec演进追踪：to-spec 产出的是一次性PRD/spec文档，没有delta机制、没有source of truth、没有archive合并
• 变更可审计：没有change文件夹完整保留机制
• 自动化工具：纯Markdown skill，没有CLI工具、没有schema系统、没有validation逻辑
• 多平台适配：通过 skills.sh 安装器适配多个agent平台，但深度有限
• 并行变更管理：没有bulk archive和冲突检测机制
• 自动化触发：没有hooks系统、没有session start自动bootstrap

8.3演进模式

从CHANGELOG可以看出mattpocock-skills的演进特征：

1. 从碎片化到统一：to-prd → to-spec，to-plan + to-issues → to-tickets——减少skill数量，降低认知负担
2. 从复杂到简化：TDD从step-by-step workflow变成reference-only——“the loop is anchored by leading words the model already holds”
3. 从本地到协作：wayfinder从本地Markdown文件迁移到issue tracker——“a shared URL the team can watch”
4. 从隐性到显性：grilling的facts/decisions分离、HITL/AFK分类——当skill被自动化调用时，需要显式区分人工和自动
5. 从粗糙到精细：code-review增加Fowler smell baseline、grilling增加确认门控——逐步加强而非一步到位

9. 演进中的关键教训