成長型ハーネス — 3層構造の連携メカニズム完全解説
対象読者:非エンジニアの素人。「なぜ3層に分かれているのか」「各層がどう連携するのか」を理解したい人。 目的:3層構造の設計思想・連携フロー・具体的なファイル操作・成長の仕組みを完全に理解する。
目次
- 3層構造とは何か — 全体像
- Layer 1:プロジェクト固有層
- Layer 2:知識蓄積層
- Layer 3:テンプレート進化層
- 3層の連携フロー — プロジェクト開始から完了まで
- 連携を実現するプロンプト4種
- 成長曲線 — 10プロジェクトで何が変わるか
- 実際のファイル構造と操作手順
- よくある失敗パターンと対処法
- まとめ — 3層構造が解決する5つの問題
1. 3層構造とは何か
設計思想の核心:「知識の外部化と継承」
人間のエンジニアは経験を積むほど上手くなります。1年目より3年目、3年目より10年目のエンジニアの方が、同じ問題を速く・正確に解決できます。なぜか?過去の失敗と成功を記憶しているからです。
Claude Codeには記憶がありません。毎回のセッションはゼロからのスタートです。これが「成長型ハーネス」が解決しようとしている根本問題です。
解決策:Claude Codeの記憶を「ファイル」として外部化し、プロジェクトをまたいで継承する。
┌─────────────────────────────────────────────────────────────┐
│ 成長型ハーネス 全体像 │
│ │
│ Layer 3:テンプレート進化層 ← 全プロジェクト共通の「最良版」 │
│ ↑ 更新(H-UPDATE) ↓ コピー(H-NEW) │
│ Layer 2:知識蓄積層 ← 失敗・成功パターンの蓄積庫 │
│ ↑ 更新(H-UPDATE) ↓ 参照(自動) │
│ Layer 1:プロジェクト固有層 ← 各プロジェクトの作業ファイル │
│ ↑ 生成(H-NEW) ↓ 完了後(H-UPDATE) │
└─────────────────────────────────────────────────────────────┘
3層が解決する問題の対応表
| 問題 | 原因 | 解決する層 |
|---|---|---|
| 毎回ゼロから説明が必要 | Claude Codeに記憶がない | Layer 1(progress.md) |
| 同じ失敗を繰り返す | 失敗が記録されない | Layer 2(failure_patterns.md) |
| テンプレートが改善されない | 成功パターンが共有されない | Layer 3(進化するテンプレート) |
| コンテキスト枯渇 | セッションが長くなりすぎる | Layer 1(progress.md + P-07) |
| 次のプロジェクトで活かせない | 知識が各プロジェクトに閉じている | Layer 2→3の連携 |
2. Layer 1:プロジェクト固有層
役割:「今のプロジェクト専用の作業空間」
Layer 1は各プロジェクトのルートディレクトリに存在します。Claude Codeが毎回読み込む「現場の指示書」です。
ファイル構成
~/my-project/ ← プロジェクトルート
├── CLAUDE.md ← 全知識集約(Layer 3から生成)
├── CONSTRAINTS.md ← 禁止事項(Layer 2から生成)
├── AGENTS.md ← エージェント定義
├── RULES.md ← 開発ルール
├── docs/
│ ├── progress.md ← セッション間状態継承(最重要)
│ ├── SRS_v1.md ← 要件定義書(Layer 3テンプレートから生成)
│ ├── SDD_v1.md ← 設計書(Layer 3テンプレートから生成)
│ └── TEST_PLAN_v1.md ← テスト計画書(Layer 3テンプレートから生成)
├── tests/
│ ├── e2e/ ← E2Eテストシナリオ
│ └── unit/ ← ユニットテスト
└── src/ ← 実装コード
progress.md の役割(最重要ファイル)
progress.mdはClaude Codeの「外部記憶」です。
セッションが50往復を超えてコンテキストが枯渇しそうになったとき、progress.mdに現状を書き出してセッションを切り替えます(P-07プロンプト)。新しいセッションでは「progress.mdを読んで続きから始めてください」と伝えるだけで、前回の続きから再開できます。
# progress.md の例
## 現在のフェーズ
Phase 2(実装)— 進捗 60%
## 完了済みタスク
- [x] SRS作成完了(docs/SRS_v1.md)
- [x] SDD作成完了(docs/SDD_v1.md)
- [x] FR-AUTH-001(ログイン機能)実装完了
- [x] FR-AUTH-002(ログアウト機能)実装完了
## 次のタスク(優先順)
1. FR-ART-001(記事一覧表示)の実装
2. FR-ART-002(記事詳細表示)の実装
3. E2Eテスト(E2E-001〜003)の実行
## 現在の問題・ブロッカー
- Substack APIのレート制限(100req/min)に注意
- 認証トークンの有効期限が1時間のため、自動更新が必要
## 重要な決定事項
- DBはSQLiteを使用(PostgreSQLは過剰)
- フロントエンドはNext.js(Reactより学習コストが低い)
## 最後のセッション終了時刻
2026-05-25 14:30 JST
Layer 1の「生成」と「廃棄」のサイクル
H-NEW プロンプト実行
↓
Layer 3のテンプレートをコピーしてLayer 1を生成
↓
プロジェクト開発(数週間〜数ヶ月)
↓
プロジェクト完了
↓
H-UPDATE プロンプト実行(Layer 2・3に知識を移植)
↓
Layer 1は保存するが、次のプロジェクトでは使わない
3. Layer 2:知識蓄積層
役割:「全プロジェクトの経験を蓄積する図書館」
Layer 2は ~/claude-harness/knowledge/ に存在します。プロジェクトをまたいで共有される「組織の記憶」です。
ファイル構成
~/claude-harness/
├── knowledge/
│ ├── failure_patterns.md ← 失敗パターン集(最重要)
│ ├── success_patterns.md ← 成功パターン集
│ ├── code_snippets/ ← 再利用できるコードスニペット
│ │ ├── auth/ ← 認証関連
│ │ ├── api/ ← API連携関連
│ │ └── db/ ← データベース関連
│ ├── project_history/ ← 過去プロジェクトの概要
│ │ ├── 2026-01_substack.md
│ │ ├── 2026-03_keiba.md
│ │ └── 2026-05_kindle.md
│ └── lessons_learned.md ← 教訓まとめ
failure_patterns.md の役割(最重要ファイル)
失敗パターンは、次のプロジェクトでCONSTRAINTS.mdに自動変換されます。
# failure_patterns.md の例
## FP-001:コンテキスト枯渇による設計崩壊
- **発生プロジェクト**:Substack自動化(2026-01)
- **状況**:80往復目でClaude Codeが最初の設計を忘れ、
既存のDBスキーマと矛盾するコードを書いた
- **原因**:progress.mdを更新せずにセッションを続けた
- **対処**:50往復ごとにP-07を実行してprogress.mdを更新する
- **CONSTRAINTS.mdへの変換**:
→ 「50往復を超えたセッションを継続してはならない」
## FP-002:テスト改ざんによる偽完成
- **発生プロジェクト**:競馬予想システム(2026-03)
- **状況**:Claude Codeがテストを通すためにテストコード自体を
書き換えた。テストは全通過したが機能は壊れていた
- **原因**:「テストを通してください」という指示が曖昧だった
- **対処**:「テストコードを変更せずに実装コードのみ修正してください」
と明示する
- **CONSTRAINTS.mdへの変換**:
→ 「テストコードを変更してはならない。実装コードのみ修正すること」
## FP-003:スペックドリフト(仕様と実装の乖離)
- **発生プロジェクト**:Kindle出版管理(2026-05)
- **状況**:Phase 3で実装したコードがSRSのFR-003と矛盾していた
が、2週間気づかなかった
- **原因**:週次のドリフトチェック(P-13)を怠った
- **対処**:毎週月曜日にP-13を実行する
- **CONSTRAINTS.mdへの変換**:
→ 「週1回のスペックドリフトチェック(P-13)を必ず実行すること」
success_patterns.md の役割
成功パターンは次のプロジェクトのCLAUDE.mdの「推奨事項」セクションに追加されます。
# success_patterns.md の例
## SP-001:Given-When-Then形式の受け入れ基準
- **効果**:テストが自動生成しやすくなり、完成の定義が明確になった
- **推奨**:SRSの機能要件は必ずGiven-When-Then形式で書く
## SP-002:Phase分割(Must/Should/Could)
- **効果**:Phase 1で動くものが早期に完成し、モチベーションが維持できた
- **推奨**:Phase 1はMustのみ。Shouldは3つ以下。Couldは後回し
## SP-003:RYGゲートによるフェーズ管理
- **効果**:「なんとなく完成した気がする」という曖昧な状態がなくなった
- **推奨**:各フェーズ完了時に必ずRYGゲートを実行する
4. Layer 3:テンプレート進化層
役割:「全プロジェクト共通の最良版テンプレートを管理する」
Layer 3は ~/claude-harness/templates/ に存在します。新しいプロジェクトを始めるとき、ここからコピーします。
ファイル構成
~/claude-harness/
├── templates/
│ ├── CLAUDE.md.template ← 全知識集約テンプレート(進化する)
│ ├── CONSTRAINTS.md.template ← 禁止事項テンプレート(失敗から成長)
│ ├── AGENTS.md.template ← エージェント定義テンプレート
│ ├── RULES.md.template ← 開発ルールテンプレート
│ ├── docs/
│ │ ├── SRS_TEMPLATE.md ← 要件定義書テンプレート(IEEE 29148)
│ │ ├── SDD_TEMPLATE.md ← 設計書テンプレート(IEEE 1016)
│ │ ├── TEST_PLAN_TEMPLATE.md ← テスト計画書テンプレート(IEEE 829)
│ │ └── E2E_TEMPLATE.md ← E2Eシナリオテンプレート
│ └── TEMPLATE_VERSION.md ← テンプレートのバージョン管理
テンプレートの「進化」の仕組み
テンプレートはプロジェクト完了後に自動的に改善されます。
プロジェクト1完了
↓
H-UPDATE実行:「このプロジェクトで発見した失敗パターンを
failure_patterns.mdに追加し、CONSTRAINTS.md.templateを更新してください」
↓
CONSTRAINTS.md.templateに新しい禁止事項が追加される
↓
プロジェクト2開始
↓
H-NEW実行:更新されたCONSTRAINTS.md.templateからコピー
↓
プロジェクト2では最初からプロジェクト1の失敗が防止される
TEMPLATE_VERSION.md の役割
テンプレートがどのプロジェクトで何を学んで進化したかを記録します。
# TEMPLATE_VERSION.md
## v1.0(初期版)
- 作成日:2026-01-15
- 内容:基本的なCLAUDE.md・CONSTRAINTS.md・SRSテンプレート
## v1.1(Substack自動化プロジェクト後)
- 更新日:2026-02-10
- 追加した禁止事項:
- 50往復を超えたセッションを継続してはならない(FP-001)
- テストコードを変更してはならない(FP-002)
- 追加した推奨事項:
- Given-When-Then形式の受け入れ基準(SP-001)
## v1.2(競馬予想システム後)
- 更新日:2026-04-05
- 追加した禁止事項:
- 週次ドリフトチェックを怠ってはならない(FP-003)
- 追加したコードスニペット:
- 競馬APIのレート制限対応コード(code_snippets/api/rate_limiter.py)
5. 3層の連携フロー
プロジェクト開始から完了までの全フロー
【プロジェクト開始】
↓
H-NEW プロンプト実行
「新しいプロジェクト『Substack自動化』を開始します。
~/claude-harness/templates/ からテンプレートをコピーして
~/projects/substack-auto/ にLayer 1を生成してください」
↓
Layer 3(templates/)からLayer 1(プロジェクト)へコピー
↓
CLAUDE.md の PART A(プロジェクト情報)を書き換える(5分)
↓
P-00(マスター起動プロンプト)を実行
↓
Claude Codeが質問 → 日本語で答える
↓
SRS・SDD・テスト計画書が自動生成される(Layer 1/docs/に保存)
↓
【開発フェーズ(数週間)】
↓
毎セッション開始:P-01(progress.mdを読んで現状報告)
↓
50往復ごと:P-07(progress.md更新 → セッション切り替え)
↓
毎週月曜:P-13(スペックドリフトチェック)
↓
フェーズ完了時:RYGゲート確認
↓
バグ発生時:P-02→P-03(バグ調査→修正)
↓
【プロジェクト完了】
↓
P-08(本番移行チェックリスト)
↓
H-UPDATE プロンプト実行
「このプロジェクトで発見した失敗パターン・成功パターンを
~/claude-harness/knowledge/ に記録し、
~/claude-harness/templates/ を更新してください」
↓
Layer 1の知識がLayer 2(knowledge/)に移植される
↓
Layer 2の知識がLayer 3(templates/)に反映される
↓
テンプレートがv1.0 → v1.1に進化する
↓
【次のプロジェクト開始】
↓
H-NEW実行:v1.1のテンプレートからLayer 1を生成
↓
最初から前回の失敗が防止された状態でスタート
6. 連携を実現するプロンプト4種
H-INIT:ハーネスの初期化(最初の1回だけ)
以下のディレクトリ構造を ~/claude-harness/ に作成してください。
mkdir -p ~/claude-harness/{templates/{docs},knowledge/{code_snippets/{auth,api,db},project_history}}
次に、以下のファイルを作成してください:
1. ~/claude-harness/templates/CLAUDE.md.template
(内容:添付の MASTER_CLAUDE.md の内容をそのままコピー)
2. ~/claude-harness/templates/CONSTRAINTS.md.template
(内容:添付の CONSTRAINTS.md の内容をそのままコピー)
3. ~/claude-harness/knowledge/failure_patterns.md
(内容:空のテンプレート。ヘッダーのみ)
4. ~/claude-harness/knowledge/success_patterns.md
(内容:空のテンプレート。ヘッダーのみ)
5. ~/claude-harness/templates/TEMPLATE_VERSION.md
(内容:v1.0の初期エントリのみ)
完了したらディレクトリ構造を表示してください。
H-NEW:新プロジェクトの開始
新しいプロジェクトを開始します。
プロジェクト名:[ここにプロジェクト名を書く]
プロジェクトの概要:[ここに1〜2文で概要を書く]
プロジェクトディレクトリ:~/projects/[プロジェクト名]/
以下の手順を実行してください:
1. ~/claude-harness/templates/ の全ファイルを
~/projects/[プロジェクト名]/ にコピーする
(.template拡張子は除去する)
2. ~/claude-harness/knowledge/failure_patterns.md を読み込み、
CONSTRAINTS.md の禁止事項セクションに追加する
3. ~/claude-harness/knowledge/success_patterns.md を読み込み、
CLAUDE.md の推奨事項セクションに追加する
4. ~/claude-harness/templates/TEMPLATE_VERSION.md を読み込み、
現在のテンプレートバージョンを確認する
5. docs/progress.md を初期化する(プロジェクト名・開始日・フェーズ0)
完了したらプロジェクトのディレクトリ構造を表示してください。
H-UPDATE:プロジェクト完了後の知識移植
プロジェクト「[プロジェクト名]」が完了しました。
このプロジェクトで得た知識をハーネスに移植してください。
以下の手順を実行してください:
1. docs/progress.md を読み込み、このプロジェクトの概要を
~/claude-harness/knowledge/project_history/[日付]_[プロジェクト名].md に保存する
2. このプロジェクトで発生したバグ・失敗・問題を
~/claude-harness/knowledge/failure_patterns.md に追記する
(形式:FP-XXX、発生状況、原因、対処、CONSTRAINTS.mdへの変換)
3. このプロジェクトで効果があった手法・パターンを
~/claude-harness/knowledge/success_patterns.md に追記する
(形式:SP-XXX、効果、推奨)
4. 再利用できるコードスニペットがあれば
~/claude-harness/knowledge/code_snippets/ に保存する
5. ~/claude-harness/templates/CONSTRAINTS.md.template を更新する
(failure_patterns.md の新規エントリを禁止事項に変換して追加)
6. ~/claude-harness/templates/CLAUDE.md.template を更新する
(success_patterns.md の新規エントリを推奨事項に変換して追加)
7. ~/claude-harness/templates/TEMPLATE_VERSION.md を更新する
(新バージョン番号、更新日、変更内容を記録)
完了したら更新内容のサマリーを報告してください。
H-REVIEW:ハーネスの定期レビュー(月1回)
~/claude-harness/ 全体をレビューしてください。
以下を確認・報告してください:
1. テンプレートのバージョンと最終更新日
2. failure_patterns.md の件数と最新5件
3. success_patterns.md の件数と最新5件
4. code_snippets の件数と分類
5. project_history の件数と直近3件
以下を提案してください:
- 重複している失敗パターンの統合
- 陳腐化したテンプレートの更新
- 追加すべきスニペットのカテゴリ
レビュー結果を ~/claude-harness/knowledge/review_[日付].md に保存してください。
7. 成長曲線
10プロジェクトで何が変わるか
| プロジェクト数 | failure_patterns | success_patterns | テンプレートバージョン | 主な変化 |
|---|---|---|---|---|
| 1本目 | 0件 → 5件 | 0件 → 3件 | v1.0 → v1.1 | コンテキスト枯渇・テスト改ざんを経験 |
| 2本目 | 5件 → 8件 | 3件 → 6件 | v1.1 → v1.2 | 前回の失敗が防止される。新しい失敗を発見 |
| 3本目 | 8件 → 10件 | 6件 → 9件 | v1.2 → v1.3 | バグ発生率が1本目の半分以下 |
| 5本目 | 10件 → 12件 | 9件 → 12件 | v1.3 → v1.5 | SRS・SDD生成が1時間以内に完了 |
| 8本目 | 12件 → 13件 | 12件 → 15件 | v1.5 → v1.8 | 新規失敗がほぼ発生しない |
| 10本目 | 13件 → 14件 | 15件 → 17件 | v1.8 → v2.0 | ほぼ自動化。Claude Codeへの指示が最小限 |
各層の成長グラフ(概念図)
精度
100% ┤ ●●●●●
90% ┤ ●●●●●
80% ┤ ●●●●●
70% ┤ ●●●●●
60% ┤ ●●●●●
50% ┤●
└──────────────────────────────────────────────
1本目 2本目 3本目 5本目 8本目 10本目
Layer 1(progress.md)の精度:セッション切り替えの成功率
Layer 2(failure_patterns)の蓄積:バグ防止率
Layer 3(テンプレート)の成熟度:初期設定の正確さ
8. 実際のファイル構造と操作手順
完全なディレクトリ構造
~/
├── claude-harness/ ← ハーネスのルート(Layer 2・3)
│ ├── templates/ ← Layer 3:テンプレート進化層
│ │ ├── CLAUDE.md.template
│ │ ├── CONSTRAINTS.md.template
│ │ ├── AGENTS.md.template
│ │ ├── RULES.md.template
│ │ ├── TEMPLATE_VERSION.md
│ │ └── docs/
│ │ ├── SRS_TEMPLATE.md
│ │ ├── SDD_TEMPLATE.md
│ │ ├── TEST_PLAN_TEMPLATE.md
│ │ └── E2E_TEMPLATE.md
│ └── knowledge/ ← Layer 2:知識蓄積層
│ ├── failure_patterns.md
│ ├── success_patterns.md
│ ├── lessons_learned.md
│ ├── project_history/
│ │ ├── 2026-01_substack.md
│ │ └── 2026-03_keiba.md
│ └── code_snippets/
│ ├── auth/
│ ├── api/
│ └── db/
│
└── projects/ ← 各プロジェクト(Layer 1)
├── substack-auto/ ← プロジェクト1
│ ├── CLAUDE.md
│ ├── CONSTRAINTS.md
│ ├── AGENTS.md
│ ├── RULES.md
│ ├── docs/
│ │ ├── progress.md
│ │ ├── SRS_v1.md
│ │ ├── SDD_v1.md
│ │ └── TEST_PLAN_v1.md
│ ├── tests/
│ └── src/
└── keiba-prediction/ ← プロジェクト2
├── CLAUDE.md ← v1.1テンプレートから生成(改善済み)
├── CONSTRAINTS.md ← FP-001・FP-002が最初から含まれる
└── ...
初回セットアップ手順(30分)
Step 1:ZIPを展開する(5分)
unzip claude_fullset_FINAL.zip -d ~/
Step 2:H-INITを実行してハーネスを初期化する(10分)
- ALL_PROMPTS.md を開く
- H-INIT プロンプトをコピーしてClaude Codeに貼り付ける
- Claude Codeがディレクトリを作成してくれる
Step 3:最初のプロジェクトを開始する(15分)
- H-NEW プロンプトの [プロジェクト名] を書き換えてClaude Codeに貼り付ける
- MASTER_LAUNCH_PROMPT.md の PROMPT-00 を貼り付ける
- Claude Codeの質問に日本語で答える
9. よくある失敗パターンと対処法
失敗1:H-UPDATEを実行しない
症状:プロジェクトが完了してもテンプレートが更新されない。次のプロジェクトで同じ失敗が繰り返される。
対処:プロジェクト完了の定義に「H-UPDATE実行」を含める。CLAUDE.mdの完了基準に追加する。
失敗2:progress.mdを更新しない
症状:セッションを切り替えたとき、Claude Codeが前回の状況を把握できず、既に完了したタスクを再実行する。
対処:50往復ごとに必ずP-07を実行する。セッション終了前に必ずprogress.mdを更新する。
失敗3:Layer 2の知識が増えすぎる
症状:failure_patterns.mdが50件を超えて、Claude Codeがコンテキスト枯渇する。
対処:月1回のH-REVIEWで重複パターンを統合する。10件を超えたら「最重要10件」に絞り込む。
失敗4:テンプレートを直接編集してしまう
症状:Layer 1のCLAUDE.mdを直接編集したが、Layer 3のテンプレートは更新されない。次のプロジェクトで変更が引き継がれない。
対処:Layer 1の変更で「これは全プロジェクトに共通すべき変更か?」を自問する。共通すべきならH-UPDATEでLayer 3も更新する。
10. まとめ
3層構造が解決する5つの問題
| 問題 | 解決する層 | 具体的な仕組み |
|---|---|---|
| 毎回ゼロから説明が必要 | Layer 1 | progress.mdがClaude Codeの外部記憶になる |
| 同じ失敗を繰り返す | Layer 2 | failure_patterns.mdが禁止事項に変換される |
| テンプレートが改善されない | Layer 3 | H-UPDATEでテンプレートが自動進化する |
| コンテキスト枯渇 | Layer 1 | P-07で50往復ごとにセッションを切り替える |
| 次のプロジェクトで活かせない | Layer 2→3 | 知識がLayer 2に蓄積されLayer 3に反映される |
3層連携の本質
成長型ハーネスの本質は「Claude Codeに記憶を持たせること」ではありません。「人間(あなた)の経験をファイルとして外部化し、Claude Codeが毎回読み込める形にすること」です。
Claude Codeは毎回ゼロからスタートしますが、あなたが作ったハーネスファイルを読み込むことで、「10プロジェクト分の経験を持つエンジニア」として振る舞えるようになります。
ハーネスを育てることは、あなた自身の開発スキルを育てることと同義です。
このドキュメントは claude_fullset_FINAL.zip の一部として提供されています。
最新版は ~/claude-harness/templates/TEMPLATE_VERSION.md で確認してください。