← AI開発 資料アーカイブ
成長型ハーネス

成長型ハーネス — 3層構造の連携メカニズム完全解説

元ファイル: システム要件定義の分析と汎用化方法/成長型ハーネス — 3層構造の連携メカニズム完全解説.md

要約

成長型ハーネスの3層(Layer1プロジェクト固有層/Layer2知識蓄積層/Layer3テンプレート進化層)が、なぜ分かれているか・どう連携するかを非エンジニア向けに完全解説した文書。各層のファイル構成と役割を詳述し、H-NEWで生成→開発→H-UPDATEで知識を上位層へ移植という循環フローを図示する。連携プロンプト4種、成長曲線、初回セットアップ手順、よくある失敗4種と対処も収録。

要点

成長型ハーネス3層構造連携メカニズムprogress.mdfailure_patternsTEMPLATE_VERSION外部記憶

成長型ハーネス — 3層構造の連携メカニズム完全解説

対象読者:非エンジニアの素人。「なぜ3層に分かれているのか」「各層がどう連携するのか」を理解したい人。 目的:3層構造の設計思想・連携フロー・具体的なファイル操作・成長の仕組みを完全に理解する。


目次

  1. 3層構造とは何か — 全体像
  2. Layer 1:プロジェクト固有層
  3. Layer 2:知識蓄積層
  4. Layer 3:テンプレート進化層
  5. 3層の連携フロー — プロジェクト開始から完了まで
  6. 連携を実現するプロンプト4種
  7. 成長曲線 — 10プロジェクトで何が変わるか
  8. 実際のファイル構造と操作手順
  9. よくある失敗パターンと対処法
  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.mdPROMPT-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 で確認してください。

↑ トップへ戻る