成長型ハーネス — 設計思想と貢献の完全解説
対象読者：非エンジニアの素人。Claude Codeを使ってシステム開発を始めたばかりの人。 目的：「成長型ハーネス」が何であり、なぜ必要で、どう使うと効果があるかを理解する。
1. そもそも「ハーネス」とは何か
1-1. 語源と意味
「ハーネス（harness）」とは、馬具の「馬勒（ばろく）」から来た言葉です。馬に装着して、馬の力を正しい方向に制御するための道具です。
ソフトウェア開発における「テストハーネス」も同じ意味を持ちます。AIの力（Claude Codeの能力）を正しい方向に制御するための仕組みです。
ハーネスなしでClaude Codeを使うと： - AIが好き勝手な方向に走り出す - 毎回ゼロから説明が必要 - 前回の失敗を次回に活かせない - プロジェクトをまたいで知識が消える
ハーネスありでClaude Codeを使うと： - AIが決められたレールの上を走る - セッション開始時に「前回の続き」から始められる - 失敗パターンが自動的に禁止事項に追加される - 次のプロジェクトで同じ失敗を繰り返さない
2. 「成長型」の意味 — 静的ハーネスとの違い
2-1. 静的ハーネス（従来型）
従来の開発ドキュメントは「静的」です。
プロジェクトA → CLAUDE.md作成 → 開発完了 → CLAUDE.mdは捨てる
プロジェクトB → CLAUDE.md作成（ゼロから） → 開発完了 → CLAUDE.mdは捨てる
プロジェクトC → CLAUDE.md作成（ゼロから） → ...
問題点：プロジェクトAで学んだことがBに活かされない。毎回同じ失敗をする。
2-2. 成長型ハーネス（本体系）
成長型ハーネスは「生きたドキュメント」です。
プロジェクトA → CLAUDE.md作成 → 開発完了 → 学びをハーネスに蓄積
↓
プロジェクトB → ハーネスからCLAUDE.mdを生成 → 開発完了 → 学びを追加蓄積
↓
プロジェクトC → ハーネスからCLAUDE.mdを生成（Aの失敗もBの失敗も禁止事項に入っている）
効果：プロジェクトを重ねるほど、Claude Codeへの指示が精度を増す。
3. 成長型ハーネスの3層構造
┌─────────────────────────────────────────────────────────┐
│ Layer 3: テンプレート進化層（~/claude-harness/templates/）│
│ ─ 全プロジェクト共通のテンプレートが蓄積される │
│ ─ SRS・SDD・テスト計画の「最良版」が常に更新される │
│ ─ 新プロジェクト開始時にここからコピーする │
├─────────────────────────────────────────────────────────┤
│ Layer 2: 知識蓄積層（~/claude-harness/knowledge/） │
│ ─ 失敗パターン集（failure_patterns.md） │
│ ─ 成功パターン集（success_patterns.md） │
│ ─ 技術スタック別のコツ（tech_notes/） │
│ ─ よく使うコードスニペット（snippets/） │
├─────────────────────────────────────────────────────────┤
│ Layer 1: プロジェクト固有層（~/my-project/） │
│ ─ CLAUDE.md（Layer 2・3から生成） │
│ ─ CONSTRAINTS.md（失敗パターンから自動追加） │
│ ─ docs/progress.md（セッション間状態継承） │
│ ─ docs/srs.md・sdd.md・test_plan.md │
└─────────────────────────────────────────────────────────┘
3-1. Layer 1：プロジェクト固有層
各プロジェクトに存在する、そのプロジェクト専用のファイル群です。
| ファイル | 役割 |
|---|---|
CLAUDE.md |
Claude Codeへの全指示（Layer 2・3から生成） |
CONSTRAINTS.md |
禁止事項（過去の失敗から自動追加） |
docs/progress.md |
現在の進捗・次のタスク（セッション切り替え時に更新） |
docs/srs.md |
要件定義書（P-00プロンプトで自動生成） |
docs/sdd.md |
設計書（P-16プロンプトで自動生成） |
docs/test_plan.md |
テスト計画書（P-17プロンプトで自動生成） |
3-2. Layer 2：知識蓄積層
プロジェクト完了後に「学び」を蓄積する場所です。
~/claude-harness/knowledge/failure_patterns.md の例：
## 失敗パターン集
### FP-001（2024-01-15 Substack自動化プロジェクト）
**状況**：Substack APIのレート制限を無視して実装した
**結果**：本番環境でAPIが429エラーを返し続けた
**対策**：今後は必ずAPIドキュメントのレート制限セクションを確認してから実装する
**CONSTRAINTS.mdへの追記**：「外部APIを使う前に必ずレート制限を確認すること」
### FP-002（2024-02-03 メール配信プロジェクト）
**状況**：テストデータに本番のメールアドレスを使った
**結果**：テスト中に実際のユーザーにメールが送信された
**対策**：テスト環境では必ずダミーメールアドレスを使う
**CONSTRAINTS.mdへの追記**：「テスト時は必ず @test.example.com ドメインを使うこと」
~/claude-harness/knowledge/success_patterns.md の例：
## 成功パターン集
### SP-001（2024-01-15 Substack自動化プロジェクト）
**状況**：セッション開始時にprogress.mdを読ませた
**効果**：前回の続きから即座に開始でき、コンテキスト枯渇問題が解消された
**再現手順**：P-01プロンプトを毎回使う
### SP-002（2024-02-03 メール配信プロジェクト）
**状況**：E2Eシナリオを先に書いてから実装した
**効果**：「完成の定義」が明確になり、手戻りが0回だった
**再現手順**：P-17プロンプトで先にE2Eシナリオを生成してから実装を開始する
3-3. Layer 3：テンプレート進化層
プロジェクトを重ねるごとに「最良版テンプレート」が更新される場所です。
~/claude-harness/templates/
├── CLAUDE.md.template ← 全プロジェクト共通の最良版
├── CONSTRAINTS.md.template ← 蓄積された全禁止事項
├── srs_template.md ← 最良版SRSテンプレート
├── sdd_template.md ← 最良版SDDテンプレート
├── test_plan_template.md ← 最良版テスト計画テンプレート
└── e2e_scenarios_template.md ← 最良版E2Eシナリオテンプレート
4. 成長のメカニズム — プロジェクト完了後の5アクション
プロジェクトが完了したら、必ず以下の5アクションを実行します。これが「成長」の核心です。
アクション1：失敗パターンの記録（10分）
【P-14-A プロンプト】
このプロジェクトで発生した問題・バグ・手戻りを全て列挙してください。
各問題について：
1. 何が起きたか（事実）
2. なぜ起きたか（原因）
3. 次回どう防ぐか（対策）
4. CONSTRAINTS.mdに追記すべき禁止事項
を整理してください。
アクション2：成功パターンの記録（5分）
【P-14-B プロンプト】
このプロジェクトで特に効果的だったアプローチを列挙してください。
各成功について：
1. 何をしたか（手順）
2. なぜ効果があったか（理由）
3. 次回も再現できるか（再現性）
を整理してください。
アクション3：CONSTRAINTS.mdの更新（5分）
アクション1で特定した「次回の禁止事項」を ~/claude-harness/templates/CONSTRAINTS.md.template に追記します。
次のプロジェクトでは、この更新されたテンプレートからCONSTRAINTS.mdを生成するので、過去の失敗が自動的に禁止事項として機能します。
アクション4：テンプレートの更新（10分）
このプロジェクトで「こう書けばよかった」と気づいたSRS・SDD・テスト計画の改善点を、テンプレートに反映します。
アクション5：スニペットの保存（5分）
このプロジェクトで作った「汎用的に使えるコード」をスニペット集に保存します。
~/claude-harness/knowledge/snippets/
├── api_rate_limiter.py ← レート制限対応のAPIクライアント
├── email_validator.py ← メールアドレス検証
├── retry_decorator.py ← リトライ処理のデコレータ
└── ...
5. 成長の可視化 — プロジェクト数と精度の関係
成長型ハーネスを使い続けると、以下のような成長曲線を描きます。
Claude Codeへの指示精度
100% ┤ ●●●●
90% ┤ ●●●●●●●●
80% ┤ ●●●●●●●●
70% ┤ ●●●●●●●●
60% ┤ ●●●●●●●●
50% ┤●●●●
40% ┤
└────────────────────────────────────────────────
1 2 3 4 5 6 7 8 9 10
プロジェクト数
| プロジェクト数 | 主な成長内容 |
|---|---|
| 1〜2本目 | ハーネスの基礎が整う。失敗パターンが5〜10件蓄積される |
| 3〜5本目 | 禁止事項が充実し、バグ発生率が半減する |
| 6〜8本目 | テンプレートが洗練され、SRS・SDD生成精度が向上する |
| 9本目以降 | ほぼ自動化。Claude Codeへの指示が最小限で済む |
6. コンテキスト枯渇問題との関係
Claude Codeには「コンテキスト上限」があります。長い会話を続けると、AIが「最初に何を言ったか」を忘れます。
6-1. コンテキスト枯渇が起きると何が起きるか
セッション開始
↓
会話10往復：「Substack APIを使って記事を自動投稿する」と説明
↓
会話30往復：Claude Codeが「Substack APIって何でしたっけ？」と聞いてくる
↓
会話50往復：最初の要件を完全に忘れ、全く別の実装を始める
↓
会話70往復：「このコードは何のためのものですか？」と聞いてくる ← 崩壊
6-2. 成長型ハーネスによる解決
docs/progress.md が「記憶の外部化」として機能します。
# progress.md（セッション切り替え時に更新）
## プロジェクト概要
Substack記事自動配信システム。毎週月曜日9時に記事を自動投稿する。
## 現在のフェーズ
Phase 2（投稿スケジューラー実装中）
## 完了済みタスク
- [x] Substack API認証（2024-01-15）
- [x] 記事下書き取得API（2024-01-16）
- [x] 投稿APIのラッパー関数（2024-01-17）
## 次のタスク（優先順）
1. スケジューラーのcron設定
2. エラー時のSlack通知
3. 投稿ログのDB保存
## 既知の問題
- Substack APIのレート制限：1時間に60リクエストまで
- 認証トークンの有効期限：24時間（自動更新実装済み）
## 使用技術スタック
- Python 3.11
- APScheduler（スケジューラー）
- SQLite（ログDB）
- Slack Webhook（通知）
新しいセッションを開始するとき、P-01プロンプトを使うと：
このプロジェクトのCLAUDE.mdとdocs/progress.mdを読んで、
現在の状況を把握してください。
把握できたら「現在のフェーズ：〇〇、次のタスク：〇〇」と報告してください。
Claude Codeは progress.md を読むだけで、前回の続きから即座に開始できます。コンテキスト枯渇が起きても、progress.md を読み直すだけで復元できます。
7. スペックドリフト防止との関係
「スペックドリフト」とは、実装が仕様書からズレていく現象です。
仕様書：「記事は毎週月曜日9時に投稿する」
↓ 実装開始
実装中：「月曜日9時だと投稿が遅い気がするので日曜日23時にしよう」（勝手な変更）
↓ さらに実装
実装中：「23時だと翌日の日付になるので月曜日0時にしよう」（さらに変更）
↓ 完成
完成物：「月曜日0時に投稿」← 仕様書と全く違う
成長型ハーネスの CLAUDE.md には「スペックドリフト防止ルール」が含まれています：
## スペックドリフト防止ルール（CLAUDE.mdのPART C）
1. 仕様書（docs/srs.md）に記載のない変更は、必ず私に確認してから実施すること
2. 仕様変更が必要な場合は、コードを変更する前にdocs/srs.mdを更新すること
3. 週1回（毎週月曜日）、P-13プロンプトで実装と仕様書の一致を確認すること
4. 「仕様書に書いていないが便利そうな機能」は実装しないこと
さらに、週1回のドリフトチェック（P-13プロンプト）で自動的に検出します：
【P-13 スペックドリフトチェックプロンプト】
docs/srs.mdの全機能要件（FR-XXX）について、
現在の実装との一致を確認してください。
各要件について：
- ✅ 一致：実装済みで仕様通り
- ⚠️ 乖離：実装済みだが仕様と異なる
- ❌ 未実装：まだ実装されていない
乖離がある場合は、仕様書を修正すべきか実装を修正すべきかを提案してください。
8. E2Eテストとの連携
成長型ハーネスは、E2Eテストシナリオも「成長」させます。
8-1. E2Eシナリオの蓄積
プロジェクトAで書いたE2Eシナリオは、ハーネスのテンプレートに追加されます。
~/claude-harness/templates/e2e_scenarios_template.md
## 汎用E2Eシナリオ（全プロジェクト共通）
### SC-COMMON-001：外部API失敗時のリトライ
Given: 外部APIが500エラーを返す
When: システムがAPIを呼び出す
Then: 3回リトライし、3回失敗したらエラーログを記録してSlack通知する
### SC-COMMON-002：認証トークン期限切れ
Given: 認証トークンの有効期限が切れている
When: APIを呼び出す
Then: 自動的にトークンを更新してから再試行する
### SC-COMMON-003：データベース接続失敗
Given: DBへの接続が失敗する
When: データの読み書きを試みる
Then: エラーをログに記録し、ユーザーに適切なエラーメッセージを表示する
これらの「汎用シナリオ」は、次のプロジェクトでも自動的に含まれます。プロジェクトを重ねるほど、テストの網羅性が上がります。
9. 他のプロジェクトへの展開
成長型ハーネスの最大の価値は「横展開」です。
9-1. 新プロジェクト開始時の手順
# 1. 新プロジェクトフォルダを作成
mkdir ~/new-project && cd ~/new-project
# 2. ハーネスからテンプレートをコピー（H-NEWプロンプト）
cp ~/claude-harness/templates/CLAUDE.md.template ./CLAUDE.md
cp ~/claude-harness/templates/CONSTRAINTS.md.template ./CONSTRAINTS.md
# 3. CLAUDE.mdのPART Aだけ書き換える（5分）
# プロジェクト名・目的・技術スタックを記入
# 4. P-00プロンプトを貼り付ける
# → SRS・SDD・テスト計画が自動生成される
9-2. 他人のPCへの展開
claude_fullset_FINAL.zip を渡すだけです。
あなたのPC（ハーネス蓄積済み）
~/claude-harness/templates/CLAUDE.md.template（10プロジェクト分の知識）
~/claude-harness/knowledge/failure_patterns.md（30件の失敗パターン）
↓
ZIPにエクスポート
↓
他人のPC（新規）
claude_fullset_FINAL.zipを展開
→ 即座に「10プロジェクト分の知識」を持った状態で開発開始
10. まとめ：成長型ハーネスが解決する5つの問題
| 問題 | 解決策 | 効果 |
|---|---|---|
| 毎回ゼロから説明が必要 | CLAUDE.mdがコンテキストを提供 | セッション開始時間が5分→30秒 |
| コンテキスト枯渇 | progress.mdが記憶を外部化 | 50往復ごとに切り替えても継続可能 |
| 同じ失敗を繰り返す | failure_patterns.mdが禁止事項に変換 | バグ発生率がプロジェクトごとに半減 |
| スペックドリフト | 週1回のP-13チェック | 仕様と実装の乖離を早期発見 |
| 次のプロジェクトで活かせない | テンプレート進化層が知識を継承 | 10プロジェクト後には半自動化 |
付録：ハーネス管理プロンプト4種
H-INIT（初回のみ）：ハーネスを初期化する
以下のディレクトリ構造を作成してください：
~/claude-harness/
├── templates/
│ ├── CLAUDE.md.template
│ ├── CONSTRAINTS.md.template
│ ├── srs_template.md
│ ├── sdd_template.md
│ ├── test_plan_template.md
│ └── e2e_scenarios_template.md
├── knowledge/
│ ├── failure_patterns.md
│ ├── success_patterns.md
│ └── snippets/
└── projects/
└── index.md
各ファイルには、claude_fullset_FINAL.zipの対応するテンプレートの内容を使用してください。
H-NEW（新プロジェクト開始時）：テンプレートからプロジェクトを生成する
新しいプロジェクト「[プロジェクト名]」を開始します。
~/claude-harness/templates/ から以下をコピーしてください：
- CLAUDE.md.template → ./CLAUDE.md
- CONSTRAINTS.md.template → ./CONSTRAINTS.md
- srs_template.md → ./docs/srs.md
- sdd_template.md → ./docs/sdd.md
- test_plan_template.md → ./docs/test_plan.md
- e2e_scenarios_template.md → ./docs/e2e_scenarios.md
コピー後、CLAUDE.mdのPART Aに以下を記入してください：
- プロジェクト名：[プロジェクト名]
- 目的：[目的]
- 技術スタック：[技術スタック]
H-UPDATE（プロジェクト完了後）：学びをハーネスに蓄積する
このプロジェクトの振り返りを行い、ハーネスを更新してください。
1. 発生した問題・バグ・手戻りを全て列挙し、
~/claude-harness/knowledge/failure_patterns.md に追記してください。
2. 特に効果的だったアプローチを列挙し、
~/claude-harness/knowledge/success_patterns.md に追記してください。
3. 失敗パターンから導き出した禁止事項を
~/claude-harness/templates/CONSTRAINTS.md.template に追記してください。
4. 汎用的に使えるコードスニペットがあれば
~/claude-harness/knowledge/snippets/ に保存してください。
5. ~/claude-harness/projects/index.md にこのプロジェクトの記録を追加してください。
H-REVIEW（月1回）：ハーネスの品質を確認する
~/claude-harness/ の内容を確認し、以下を報告してください：
1. 蓄積された失敗パターンの数と主なカテゴリ
2. 蓄積された成功パターンの数と主なカテゴリ
3. CONSTRAINTS.md.templateの禁止事項の数
4. テンプレートの最終更新日
5. 改善が必要な箇所（古くなった情報・矛盾している記述等）
報告後、改善が必要な箇所があれば修正してください。
最終更新：2026-05-25 | バージョン：v2.0 | 準拠基準：Anthropic公式SDD + Google SRE