protocol-authoring

协议编写

概述

编写协议就是将测试驱动开发应用于流程文档。

个人协议存放在特定 Agent 的目录中（Claude Code 使用 ~/.claude/skills，Codex 使用 ~/.agents/skills/）

你需要设计测试场景（与子 Agent 一起进行基于压力的练习），观察失败（基线行为），编写协议（文档），观察是否遵循（Agent 是否遵循协议），并加以完善（堵住漏洞）。

核心原则： 如果你从未观察到 Agent 在没有协议时失败，就无法知道协议需要预防什么。

必备背景知识： 使用此技能前，你必须了解 godmode:test-first。该技能定义了基础的 RED-GREEN-REFACTOR 循环。此技能将 TDD 应用于文档。

什么是协议？

协议是经验证的技术、模式或工具的参考指南。协议帮助未来的 Claude 实例发现并应用有效的方法。

协议包括： 可复用的技术、模式、工具和参考指南

协议不包括： 讲述你曾如何一次性解决某个问题的叙述

协议的 TDD 对应关系

TDD 概念	协议创建
测试用例	与子 Agent 一起进行的压力场景
生产代码	协议文档（SKILL.md）
测试失败（RED）	Agent 在没有协议时违反规则（基线）
测试通过（GREEN）	提供协议后，Agent 遵循规则
重构	在保持合规的同时堵住漏洞
先编写测试	在编写协议之前运行基线场景
观察失败	记录 Agent 使用的确切理由
最少代码	编写协议，针对这些具体违规行为进行处理
观察通过	确认 Agent 现在会遵循规则
重构循环	找出新的理由，堵住漏洞，再次验证

整个协议创建过程都遵循 RED-GREEN-REFACTOR。

何时创建协议

适合创建的情况：

• 这项技术对你来说并非直观易懂
• 你会在多个项目中再次参考它
• 该模式适用范围广（而非仅适用于特定项目）
• 其他人也能从中受益

不适合创建的情况：

• 一次性解决方案
• 其他地方已有充分文档说明的标准实践
• 特定项目的约定（将其写入 CLAUDE.md）
• 机械性约束（如果可以用正则表达式或验证来强制执行，就将其自动化——文档留给需要判断的情况）

协议类别

技术

包含具体步骤的方法（event-based-waiting、root-cause-tracing）

模式

用于解决问题的认知框架（flatten-with-flags、test-invariants）

参考资料

API 文档、语法指南、工具文档（office docs）

目录布局

skills/
  protocol-name/
    SKILL.md              # Primary reference (required)
    supporting-file.*     # Only when necessary

扁平命名空间——所有协议都放在一个可搜索的命名空间中

单独存放以下内容：

1. 大量参考资料（100 行以上）——API 文档、全面的语法说明
2. 可复用工具——脚本、实用程序、模板

内嵌以下内容：

• 原则和概念
• 代码模式（少于 50 行）
• 其他所有内容

SKILL.md 结构

Frontmatter（YAML）：

• 仅支持两个字段：name 和 description
• 总长度最多 1024 个字符
• name：只能使用字母、数字和连字符（不能使用括号或特殊字符）
• description：使用第三人称，只描述何时使用（而非其功能）
  • 以“Use when...”开头，聚焦触发条件
  • 包含具体症状、情况和上下文
  • 绝不要概述协议的流程或工作流（见“发现优化”一节）
  • 尽可能控制在 500 个字符以内

---
name: Protocol-Name-With-Hyphens
description: Use when [specific trigger conditions and symptoms]
---

# Protocol Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for dense reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

发现优化

对提升可见性至关重要： 未来的 Claude 实例必须能够找到你的协议。

1. 丰富的描述字段

用途： Claude 会读取描述，以决定要加载哪些协议。描述应回答：“我现在应该阅读此协议吗？”

格式： 以“在……时使用”开头，重点说明触发条件。

关键：描述 = 何时使用，而不是协议的作用

描述只能说明触发条件。不要概述协议的工作流程。

原因： 测试发现，如果描述概述了工作流程，Claude 可能会遵循描述，而不是阅读完整协议。描述中提到“在任务之间审查”，导致 Claude 只进行了一次审查，尽管协议的流程图清楚地展示了两次审查（先检查规范符合性，再检查代码质量）。

将描述改为“在执行包含独立任务的实施计划时使用”（不含工作流程概述）后，Claude 正确阅读了流程图，并遵循了两阶段审查流程。

陷阱： 概述工作流程的描述会形成捷径，让 Claude 直接采用。这样一来，协议正文就成了 Claude 会跳过的文档。

# BAD: Summarizes workflow - Claude may follow this instead of reading protocol
description: Use when executing plans - launches subagent per task with review between tasks

# BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# GOOD: Just trigger conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# GOOD: Trigger conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

内容：

• 使用具体的触发条件、症状和情境，说明何时适用此协议
• 描述问题（竞态条件、行为不一致），而非特定技术的症状（setTimeout、sleep）
• 除非协议本身与特定技术有关，否则让触发条件不依赖具体技术
• 如果协议与特定技术有关，请明确说明
• 使用第三人称（内容会注入系统提示词）
• 绝不要概述协议的过程或工作流程

# BAD: Too abstract, vague, no trigger conditions
description: For async testing

# BAD: First person
description: I can help you with async tests when they're flaky

# BAD: Mentions technology but protocol isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky

# GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# GOOD: Technology-specific protocol with explicit trigger
description: Use when using React Router and handling authentication redirects

2. 关键词覆盖范围

使用 Claude 可能会搜索的词语：

• 错误消息：“Hook timed out”、“ENOTEMPTY”、“race condition”
• 症状：“flaky”、“hanging”、“zombie”、“pollution”
• 同义词：“timeout/hang/freeze”、“cleanup/teardown/afterEach”
• 工具：实际命令、库名称、文件类型

3. 描述性命名

使用主动语态，动词开头：

• creating-protocols，而不是 protocol-creation
• event-based-waiting，而不是 async-test-helpers

动名词（-ing）适用于流程：

• creating-protocols、validating-protocols、debugging-with-logs
• 表达主动性，描述正在执行的操作

4. 精简 Token（关键）

问题： 入门指南和经常引用的协议会加载到每次对话中。每个 Token 都很重要。

目标字数：

• 入门工作流：每篇少于 150 个词
• 经常加载的协议：总计少于 200 个词
• 其他协议：少于 500 个词（仍应简洁）

技巧：

将详细信息交由工具帮助说明：

# BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

使用交叉引用：

# BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# GOOD: Reference other protocol
Always use subagents (50-100x context savings). REQUIRED: Use [other-protocol-name] for workflow.

精简示例：

# BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent -> synthesis]

消除冗余：

• 不要重复交叉引用的协议中已有的内容
• 不要解释命令本身显而易见的内容
• 同一模式不要提供多个示例

验证：

wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total

根据实际操作或核心见解命名：

• event-based-waiting > async-test-helpers
• using-protocols，而不是 protocol-usage
• flatten-with-flags > data-structure-refactoring
• root-cause-tracing > debugging-techniques

5. 交叉引用其他协议

编写引用其他协议的文档时：

只使用协议名称，并明确标注要求：

• GOOD：**REQUIRED SUB-PROTOCOL:** Use godmode:test-first
• GOOD：**REQUIRED BACKGROUND:** You MUST understand godmode:fault-diagnosis
• BAD：See skills/testing/test-first（不清楚是否为必需）
• BAD：@skills/testing/test-first/SKILL.md（会强制加载，消耗上下文）

为什么不用 @ 链接： @ 语法会立即强制加载文件，在你需要之前就消耗 200k+ 上下文。

流程图用法

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

仅在以下情况下使用流程图：

• 不明显的决策点
• 可能过早终止的流程循环
• “何时使用 A，何时使用 B”的决策

绝不要在以下情况下使用流程图：

• 参考资料 → 使用表格、列表
• 代码示例 → 使用 Markdown 代码块
• 线性说明 → 使用编号列表
• 没有语义意义的标签（step1、helper2）

有关 Graphviz 样式规则，请参阅此目录中的 graphviz-conventions.dot。

为你的人类伙伴生成可视化： 使用此目录中的 render-graphs.js 将协议的流程图渲染为 SVG：

./render-graphs.js ../some-protocol           # Each diagram separately
./render-graphs.js ../some-protocol --combine # All diagrams in one SVG

代码示例

一个出色的示例胜过许多平庸的示例

选择最相关的语言：

• 测试技术 → TypeScript/JavaScript
• 系统调试 → Shell/Python
• 数据处理 → Python

优秀示例：

• 完整且可运行
• 注释完善，说明原因
• 源自真实场景
• 清楚展示模式
• 便于改编（而非通用模板）

避免：

• 用 5 种以上语言实现
• 创建填空式模板
• 编写牵强的示例

你擅长移植代码——一个出色的示例就足够了。

文件组织

独立协议

defense-in-depth/
  SKILL.md    # Everything inline

适用情况：所有内容都能容纳，且不需要密集的参考资料

带可复用工具的协议

event-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

适用情况：工具是可复用代码，而不仅仅是叙述内容

带密集参考资料的协议

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

适用情况：参考资料过于庞大，不适合内嵌

首要原则（与 TDD 相同）

NO PROTOCOL WITHOUT A FAILING TEST FIRST

这适用于新协议，也适用于对现有协议的修改。

先编写再测试？删除它，重新开始。 未经测试就编辑？同样违反原则。

没有例外：

• 不能以“简单的补充内容”为由例外
• 不能以“只是添加一个章节”为由例外
• 不能以“更新文档”为由例外
• 不要将未经测试的更改留作“参考”
• 不要在运行测试时“顺便改编”
• 删除就是删除

必读背景： godmode:test-first 协议解释了这件事为何重要。相同原则也适用于文档。

测试所有协议类型

不同类型的协议需要采用不同的测试方法：

规范约束型协议（规则/要求）

示例： TDD、completion-gate、design-before-coding

测试方式：

• 理论问题：他们是否理解规则？
• 压力场景：他们在压力下是否遵守规则？
• 组合压力：时间 + 沉没成本 + 疲惫
• 找出合理化借口，并添加明确的反制内容

成功标准： Agent 在最大压力下仍遵守规则

技术型协议（操作指南）

示例： event-based-waiting、root-cause-tracing、defensive-programming

测试方式：

• 应用场景：他们能否正确运用该技术？
• 变化场景：他们能否处理边缘情况？
• 信息缺失测试：说明中是否存在漏洞？

成功标准： Agent 能成功地将该技术应用于新场景

模式型协议（思维模型）

示例： reducing-complexity、information-hiding concepts

测试方式：

• 识别场景：他们能否识别何时适用该模式？
• 应用场景：他们能否运用该思维模型？
• 反例：他们是否知道何时不应使用？

成功标准： Agent 能正确判断何时以及如何应用该模式

参考型协议（文档/API）

示例： API 文档、命令参考、库指南

测试方式：

• 检索场景：他们能否找到正确的信息？
• 应用场景：他们能否正确使用找到的信息？
• 覆盖度测试：是否涵盖常见用例？

成功标准： Agent 能找到并正确应用参考信息

跳过测试的认知陷阱

合理化说辞	事实
“协议显然很清楚”	对你来说清楚，不代表对其他 Agent 也清楚。测试一下。
“这只是参考资料”	参考资料可能存在缺漏和表述不清的部分。测试检索效果。
“测试有点小题大做”	未经测试的协议总会有问题。15 分钟的测试可以避免数小时的困惑。
“如果出现问题，我再测试”	出现问题就意味着 Agent 无法使用该协议。部署前务必测试。
“测试太繁琐了”	与其在生产环境中调试糟糕的协议，不如先测试。
“我确信它没问题”	过度自信必然会带来问题。无论如何都要测试。
“学术审查就足够了”	阅读不等于使用。测试应用场景。
“没时间测试”	部署未经测试的协议，只会浪费更多时间在之后修复问题上。

以上说辞都意味着：部署前务必测试。没有例外。

防止协议被合理化说辞绕过

强制执行纪律的协议（如 TDD）必须能够抵御合理化说辞。Agent 很聪明，在压力下会找到漏洞。

明确封堵每个漏洞

不要只陈述规则，还要明确禁止具体的规避方法：

# Insufficient
Author code before test? Delete it.

# Sufficient
Author code before test? Delete it. Start over.

**No exceptions:**
- Do not keep it as "reference"
- Do not "adapt" it while writing tests
- Do not look at it
- Delete means delete

预先驳斥“重精神还是重字面”的争论

尽早加入一条根本原则：

**No exceptions. No workarounds. No shortcuts.**

这会堵住“我遵循了精神”的所有这类合理化说辞。

制作合理化说辞表

记录基线测试中的合理化说辞。Agent 给出的每个借口都要列入表中：

| Rationalization | Truth |
|-----------------|-------|
| "Too simple to test" | Simple code breaks. Testing takes 30 seconds. |
| "I'll test afterward" | Tests that pass immediately prove nothing about design. |
| "Tests-after achieve the same result" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

创建防护栏清单

让 Agent 在出现合理化说辞时可以轻松自查：

## Guardrails - HALT and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

在描述中补充违规征兆

在描述中加入即将违反规则时出现的征兆：

description: Use when implementing any feature or bugfix, before writing implementation code

针对协议的 RED-GREEN-REFACTOR

遵循 TDD 循环：

RED：编写失败的测试（基线测试）

在不使用协议的情况下，让子 Agent 执行压力场景。记录其确切行为：

• 它做出了哪些选择？
• 它使用了哪些合理化说辞（原话）？
• 哪些压力引发了违规？

这就是“观察测试失败”——编写协议之前，必须先观察 Agent 自然而然会怎么做。

GREEN：编写最精简的协议

编写协议，针对这些具体的合理化说辞。不要为假设的情况添加内容。

使用协议再次运行相同的场景。此时 Agent 应当遵守规则。

REFACTOR：封堵漏洞

Agent 找到了新的合理化说辞？添加明确的反制措施。重新测试，直到滴水不漏。

**测试方法：**完整的测试方法请参阅 @testing-skills-with-subagents.md：

• 如何设计压力场景
• 压力类别（时间、沉没成本、权威、疲惫）
• 系统性地封堵漏洞
• 元测试技巧

反模式

叙事性示例

“在 2025-10-03 的会话中，我们发现空的 projectDir 导致了……” **为什么不好：**过于具体，无法复用

多语言稀释

example-js.js、example-py.py、example-go.go **为什么不好：**质量平庸，维护负担重

流程图中的代码

step1 [label="import fs"];
step2 [label="read file"];

**为什么不好：**无法复制粘贴，难以阅读

通用标签

helper1、helper2、step3、pattern4 **为什么不好：**标签应当具有语义含义

停下：继续下一个协议之前

编写任何协议后，都必须停下并完成部署流程。

请勿：

• 不逐一测试每个协议，就批量创建多个协议
• 当前协议尚未验证，就开始编写下一个协议
• 以“批量处理效率更高”为由跳过测试

下方的部署检查清单对每个协议都是强制要求。

部署未经测试的协议 = 部署未经测试的代码。这违反质量标准。

协议创建检查清单（改编自 TDD）

RED 阶段——编写失败测试：

• 创建压力场景（纪律型协议至少包含 3 种组合压力）
• 在不使用协议的情况下运行场景——逐字记录基线行为
• 找出合理化说辞和失败中的模式

GREEN 阶段——编写最精简的协议：

• 名称仅使用字母、数字和连字符（不使用括号或特殊字符）
• YAML frontmatter 仅包含 name 和 description（最多 1024 个字符）
• 描述以 "Use when..." 开头，并包含具体触发条件／症状
• 使用第三人称撰写描述
• 全文包含便于发现的关键词（错误、症状、工具）
• 概述清晰，并阐明核心原则
• 针对 RED 阶段发现的具体基线失败进行处理
• 代码以内联形式提供，或链接到单独的文件
• 提供一个出色的示例（不使用多种语言）
• 使用协议运行场景——验证 Agent 现在是否遵守要求

REFACTOR 阶段——堵住漏洞：

• 找出测试中出现的新的合理化说辞
• 添加明确的反制措施（如果是纪律型协议）
• 根据所有测试迭代构建合理化说辞对照表
• 创建防护措施清单
• 反复重新测试，直到无懈可击

质量检查：

• 仅在决策不明显时提供简短流程图
• 提供速查表
• 包含常见错误部分
• 不要采用叙事性讲述
• 仅在涉及工具或内容密集的参考资料时提供辅助文件

部署：

• 将协议提交到 git，并推送到你的 fork（如果已配置）
• 考虑通过 PR 回馈社区（如果具有广泛用途）

发现工作流

Claude 未来发现你的协议的过程：

1. 遇到问题（"测试不稳定"）
2. 找到协议（描述与问题匹配）
3. 浏览概述（是否相关？）
4. 查看模式（速查表）
5. 加载示例（仅在实施时）

针对这一流程进行优化——尽早并频繁地使用可搜索的术语。

总结

创建协议就是针对流程文档进行 TDD。

同一条最高指令：没有先行失败测试，就不创建协议。 同一个循环：RED（基线） -> GREEN（编写协议） -> REFACTOR（堵住漏洞）。 同样的收益：更高质量、更少意外、结果无懈可击。

如果你对代码采用 TDD，也要对协议采用 TDD。这是将同一种规范应用于文档。