protocol-authoring

プロトコルの作成

概要

プロトコルの作成は、プロセス文書に適用するテスト駆動開発です。

個人用プロトコルは、エージェントごとのディレクトリに保存します（Claude Code では ~/.claude/skills、Codex では ~/.agents/skills/）。

サブエージェントを使ったプレッシャーに基づく演習でテストシナリオを設計し、失敗を観察し（ベースラインの動作）、プロトコルを作成し（文書化）、遵守状況を観察し（エージェントがプロトコルに従うか確認）、抜け穴を塞いで強化します。

基本原則： プロトコルなしでエージェントが失敗するところを観察したことがなければ、プロトコルで何を防ぐべきかは分かりません。

必須の事前知識： このスキルを使う前に、godmode:test-first を必ず理解してください。このスキルでは、基礎となる RED-GREEN-REFACTOR サイクルを定義しています。このスキルでは、TDD を文書化に応用します。

プロトコルとは

プロトコルとは、実証済みの技法、パターン、またはツールをまとめたリファレンスガイドです。プロトコルは、今後の Claude インスタンスが効果的なアプローチを見つけて適用するのに役立ちます。

プロトコルに含まれるもの： 再利用可能な技法、パターン、ツール、リファレンスガイド

プロトコルに含まれないもの： 一度だけ行った解決方法の説明

プロトコルにおける TDD の対応関係

TDD の概念	プロトコルの作成
テストケース	サブエージェントを使ったプレッシャーシナリオ
プロダクションコード	プロトコル文書（SKILL.md）
テスト失敗（RED）	プロトコルなしでエージェントがルールを破る（ベースライン）
テスト成功（GREEN）	プロトコルがあるとエージェントが従う
リファクタリング	遵守状況を維持しながら抜け穴を塞ぐ
先にテストを書く	プロトコルを作成する前にベースラインシナリオを実行する
失敗を観察する	エージェントが使う正確な正当化の言葉を記録する
最小限のコード	その特定の違反に対処するプロトコルを作成する
成功を観察する	エージェントが遵守するようになったことを確認する
リファクタリングサイクル	新たな正当化の言葉を見つけ、それを塞ぎ、再検証する

プロトコル作成の全工程は、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 の構成

フロントマター（YAML）：

• サポートされているフィールドは name と description の 2 つのみです
• 合計 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 はプロトコル全体を読まずに説明に従う場合があることがわかりました。「タスク間でレビューする」と記載した説明では、プロトコルのフローチャートに「仕様への準拠確認」と「コード品質確認」の2回のレビューが明確に示されているにもかかわらず、Claude は1回しかレビューしませんでした。

説明を「独立したタスクを含む実装計画を実行する場合に使用」とだけ記載し（ワークフローの要約を含めずに）変更したところ、Claude はフローチャートを正しく読み、2段階のレビュー手順に従いました。

落とし穴： ワークフローを要約した説明は、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」、「競合状態」
• 症状：「不安定」、「ハング」、「ゾンビ」、「汚染」
• 同義語：「タイムアウト／ハング／フリーズ」、「クリーンアップ／後処理／afterEach」
• ツール：実際のコマンド、ライブラリ名、ファイルの種類

3. わかりやすい命名

能動態を使い、動詞から始めます：

• protocol-creationではなくcreating-protocols
• async-test-helpersではなくevent-based-waiting

プロセスには動名詞（-ing形）が適しています：

• creating-protocols、validating-protocols、debugging-with-logs
• 能動的で、実行するアクションを表します

4. トークン効率（重要）

問題： 入門用のプロトコルや頻繁に参照されるプロトコルは、すべての会話に読み込まれます。トークンは一つ残らず重要です。

目標とする単語数：

• 入門用ワークフロー：それぞれ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

実行すること、または中心となる考え方に基づいて命名します：

• async-test-helpersよりevent-based-waiting
• protocol-usageではなくusing-protocols
• data-structure-refactoringよりflatten-with-flags
• debugging-techniquesよりroot-cause-tracing

5. 他のプロトコルとの相互参照

他のプロトコルを参照するドキュメントを書く場合：

プロトコル名のみを使い、明示的な必須マーカーを付けます。

• GOOD：**必須サブプロトコル：** godmode:test-firstを使用
• GOOD：**必須の前提知識：** godmode:fault-diagnosisを理解している必要があります
• BAD：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

コード例

優れた例を1つ示すほうが、平凡な例をたくさん示すより効果的です。

最も関連性の高い言語を選んでください。

• テスト手法 -> TypeScript/JavaScript
• システムのデバッグ -> Shell/Python
• データ処理 -> Python

優れた例：

• 完全で、実行可能である
• WHY を説明するコメントが十分にある
• 実際のシナリオに基づいている
• パターンを明確に示している
• 汎用テンプレートではなく、すぐに応用できる

避けること：

• 5つ以上の言語で実装する
• 空欄を埋めるテンプレートを作成する
• 不自然な例を書く

移植のスキルがあるなら、優れた例を1つ示せば十分です。

ファイル構成

自己完結型プロトコル

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

次の方法でテストします。

• 学術的な質問：ルールを理解しているか？
• プレッシャーのかかるシナリオ：ストレス下でも従うか？
• 複数のプレッシャーを組み合わせる：時間 + サンクコスト + 疲労
• 正当化の言い分を特定し、それに対する明示的な反論を追加する

成功基準： 最大限のプレッシャーがかかっても、エージェントがルールに従う

テクニックプロトコル（ハウツーガイド）

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

次の方法でテストします。

• 適用シナリオ：テクニックを正しく適用できるか？
• バリエーションシナリオ：エッジケースに対応できるか？
• 情報不足テスト：指示に抜けがないか？

成功基準： エージェントが新しいシナリオにテクニックをうまく適用する

パターンプロトコル（メンタルモデル）

例： reducing-complexity、information-hiding の概念

次の方法でテストします。

• 認識シナリオ：パターンを適用すべき場面を認識できるか？
• 適用シナリオ：メンタルモデルを使えるか？
• 反例：適用すべきでない場面を理解しているか？

成功基準： エージェントが、パターンを適用する場面と方法を正しく特定する

参照プロトコル（ドキュメント／API）

例： API ドキュメント、コマンドリファレンス、ライブラリガイド

次の方法でテストします。

• 情報検索シナリオ：適切な情報を見つけられるか？
• 適用シナリオ：見つけた情報を正しく使えるか？
• 網羅性テスト：一般的なユースケースをカバーしているか？

成功基準： エージェントが参照情報を見つけ、正しく適用する

テストを省略するための認知的な落とし穴

正当化	実態
「プロトコルは明らかにわかりやすい」	あなたにわかりやすくても、ほかのエージェントにもわかりやすいとは限りません。テストしてください。
「ただの参考資料です」	参考資料には抜けや不明瞭な箇所がある場合があります。情報の取得をテストしてください。
「テストはやりすぎです」	テストしていないプロトコルには問題があります。必ずです。15 分のテストで、何時間もの混乱を防げます。
「問題が起きたらテストします」	問題が起きれば、エージェントはプロトコルを使えません。デプロイする前にテストしてください。
「テストは面倒すぎます」	本番環境で不適切なプロトコルをデバッグするより、テストのほうが面倒ではありません。
「しっかりしていると確信しています」	過信は問題を確実に招きます。それでもテストしてください。
「学術的なレビューで十分です」	読むことと使うことは違います。適用シナリオをテストしてください。
「テストする時間がありません」	テストしていないプロトコルをデプロイすると、後から修正するためにもっと時間がかかります。

これらすべてが意味することは、デプロイ前にテストすることです。例外はありません。

正当化に屈しないプロトコルの強化

TDD のように規律を徹底させるプロトコルは、正当化に屈しないものでなければなりません。エージェントは高度な能力を持ち、プレッシャーの下では抜け穴を見つけます。

すべての抜け穴を明示的に塞ぐ

ルールを述べるだけでなく、具体的な回避策を禁止してください。

# 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.**

これにより、「精神に従っている」という正当化の一連のパターンを封じます。

正当化の一覧表を作成する

ベースラインテストで確認した正当化を記録します。エージェントが述べた言い訳はすべて表に追加してください。

| 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?" |

ガードレールのリストを作成する

正当化しようとしているときに、エージェントが簡単に自己チェックできるようにしてください。

## 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：失敗するテストを書く（ベースライン）

プロトコルを使わずに、サブエージェントでプレッシャーシナリオを実行します。正確な動作を記録してください。

• どのような選択をしましたか？
• どのような正当化を使いましたか（原文のまま）？
• どのようなプレッシャーが違反を引き起こしましたか？

これは「テストが失敗するのを確認する」段階です。プロトコルを作成する前に、エージェントが自然に何をするかを観察しなければなりません。

GREEN：最小限のプロトコルを作成する

確認した正当化に対処するプロトコルを作成します。仮定上のケース向けの内容は追加しないでください。

プロトコルを使って同じシナリオを実行します。今度はエージェントが従うはずです。

REFACTOR：抜け穴を塞ぐ

エージェントが新たな正当化を見つけましたか？明示的な対抗策を追加してください。抜け穴がなくなるまで再テストします。

テスト方法： 完全なテスト方法については、@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 フロントマターには name と description のみを含める（最大 1024 文字）
• description は「Use when...」で始め、具体的なトリガーや症状を含める
• description は三人称で書く
• 見つけやすくするためのキーワード（エラー、症状、ツール）を全体に含める
• 中核となる原則を含む、明確な概要を記載する
• RED で特定した具体的なベースラインの失敗に対処する
• コードをインラインで記述するか、別ファイルへのリンクを記載する
• 優れた例を 1 つ用意する（複数の言語を使わない）
• プロトコルを使ってシナリオを実行し、エージェントが指示に従うようになったことを確認する

REFACTOR フェーズ — 抜け穴を塞ぐ：

• テストで新たに見つかった合理化を特定する
• 明示的な対抗策を追加する（規律プロトコルの場合）
• すべてのテスト反復から合理化の表を作成する
• ガードレールのリストを作成する
• 抜け穴がなくなるまで再テストする

品質チェック：

• 判断が自明でない場合に限り、小さなフローチャートを使う
• クイックリファレンステーブルを用意する
• よくある間違いのセクションを設ける
• 物語形式の説明を使わない
• 補助ファイルはツールまたは大量の参考資料に限る

デプロイ：

• プロトコルを git にコミットし、自分のフォークにプッシュする（設定されている場合）
• 広く役立つ場合は、PR でのコントリビューションを検討する

発見のワークフロー

今後 Claude がプロトコルを見つける流れ：

1. 問題に遭遇する（「テストが不安定」）
2. PROTOCOL を見つける（description が一致する）
3. 概要をざっと確認する（関連性があるか）
4. パターンを読む（クイックリファレンステーブル）
5. 例を読み込む（実装時に限る）

この流れに合わせて最適化する — 検索可能な用語を早い段階から繰り返し含めてください。

要点

プロトコルの作成は、プロセス文書化のための TDD です。

同じ最優先指針：失敗するテストなしにプロトコルを作成しない。 同じサイクル：RED（ベースライン） -> GREEN（プロトコルの作成） -> REFACTOR（抜け穴を塞ぐ）。 同じメリット：品質の向上、予想外の事態の減少、抜け穴のない成果。

コードに TDD を適用するなら、プロトコルにも適用してください。文書化に同じ規律を適用するということです。