← AI開発 資料アーカイブ
ハーネス設計

ハーネス設計 強化提案書（walkinglabs全12講義の精読・ギャップ分析）

元ファイル: システム要件定義の分析と汎用化方法/ハーネス設計 強化提案書.md

要約

walkinglabsの『ハーネスエンジニアリング』全12講義を精読し、既存の対策体系と照合してギャップを洗い出した強化提案書。ハーネスをContext/Constraint/Checkpoint/Verificationの4層と定義し、既存体系に欠けていた制約層・Feature Listの制約ツール化・CLAUDE.md階層化・E2Eの設計段階組み込みの4点を補強する具体テンプレートを提示する。既存62点→強化後91点と評価し、非エンジニア向け『ハーネス設計の5原則』に圧縮している。

要点

walkinglabsハーネス設計ギャップ分析Constraint LayerFeature ListE2Eテスト禁止事項

ハーネス設計 強化提案書

walkinglabs「ハーネスエンジニアリング」全12講義 精読・照合・強化レポート

作成日： 2026年5月23日
対象： 非エンジニア向け Claude Code 要件定義自動化体系
根拠資料： walkinglabs ハーネスエンジニアリング 全12講義

1. 精読サマリー：walkinglabs が定義する「ハーネス」の本質

1.1 ハーネスとは何か（講義02の核心）

walkinglabs の定義によれば、ハーネスとは単なる「プロンプトの集合」でも「テストスクリプト」でもない。

ハーネスとは、エージェントが作業する際に「何を見て・何に従い・何を記録し・何を禁止されているか」を構造的に規定する、リポジトリ全体の設計思想そのものである。

この定義は既存の対策ファイル群が「プロンプトとゲート判定」に集中していたのとは根本的に異なる。ハーネスはプロンプトの外側にある「作業環境の骨格」であり、以下の4要素で構成される。

要素 役割 既存対策での対応状況
Context Layer（文脈層） エージェントが読む唯一の情報源（CLAUDE.md等） 部分的に存在（CLAUDE.md言及あり）
Constraint Layer（制約層） 何をしてはいけないかの明示的禁止リスト 未整備
Checkpoint Layer（記録層） 進捗・状態・完了条件の永続化 progress.md として言及あり
Verification Layer（検証層） 完了を外部から確認する仕組み RYGゲートとして存在

1.2 全12講義の要点マップ

講義 タイトル 核心メッセージ
01 強いモデルは信頼できる実行を意味しない 能力と信頼性は別物。ハーネスなしでは能力が暴走する
02 ハーネスとは何か ハーネス＝エージェントの作業環境の骨格
03 リポジトリを唯一の信頼できる情報源にする 全指示・全状態はリポジトリに書かれていなければならない
04 巨大な1ファイル指示が失敗する理由 長大なCLAUDE.mdは読まれない。分割・階層化が必須
05 長時間タスクが継続性を失う理由 コンテキストウィンドウは有限。状態外部化が必須
06 ハーネスがなければ何が起きるか 無制約エージェントは「過剰実装・未完了宣言」を繰り返す
07 エージェントが過剰実行・未完了宣言する理由 完了条件が曖昧だと「やりすぎ」か「早期完了宣言」が起きる
08 機能リストでエージェントの作業を制約する Feature Listは制約ツールであり、スコープ管理の核心
09 エージェントが早期に勝利宣言する理由 完了定義がないと「動いた＝完成」と誤認する
10 E2Eテストが結果を変える理由 ユニットテストだけでは統合破壊を検出できない
11 機能リストはハーネスのプリミティブである Feature Listは最小単位の制約装置
12 ハーネスエンジニアリングの統合 全要素を統合した完全なハーネス設計の実践

2. 既存設計との照合：ギャップ分析

2.1 既存対策が「充実している」領域（維持・強化）

既存の対策ファイル群（特に world_class_review_test_rersearch_loop_protocol.md および complete_risk_destruction_prevention_guide.md）は以下の点で walkinglabs の基準を満たしている。

RYGゲート判定（講義07・09と対応）： 完了誤認防止のためのゲートが存在し、Green/Yellow/Red の3段階で判定する仕組みは、walkinglabs が「完了条件の外部化」として推奨する設計と一致している。

Codex/Claude 役割分担（講義01・06と対応）： 書き手（Claude）と審査者（Codex）を分離する設計は、walkinglabs が「エージェントは自分の出力を正しく評価できない」と指摘する問題への直接的な対策として有効である。

レビュー・テスト・再リサーチループ（講義10と対応）： E2Eテストを含むループ設計は、walkinglabs の「ユニットテストだけでは不十分」という主張と整合している。

2.2 重大なギャップ：walkinglabs 基準で「未整備」の領域

以下の4点は、walkinglabs の講義内容と照合した結果、既存対策に明確な欠落が確認された。

ギャップ①：Constraint Layer（制約層）の欠如（講義06・07・08）

walkinglabs は「エージェントに何をしてはいけないかを明示的に書かなければ、エージェントは禁止されていないことをすべて試みる」と断言している。既存の対策ファイルには「何をすべきか」の指示は豊富だが、「何をしてはいけないか」の禁止リスト（Constraint List）が体系的に存在しない。

具体的に欠落しているのは以下の禁止事項の明文化である。

ギャップ②：CLAUDE.md の階層化設計（講義04）

walkinglabs は「1つの巨大なCLAUDE.mdは読まれない」と明確に警告している。既存の設計では CLAUDE.md の存在は言及されているが、階層化・分割の設計指針がない。推奨される構造は以下の通りである。

CLAUDE.md              ← プロジェクト全体の概要（200行以内）
docs/
  harness/
    CONSTRAINTS.md     ← 禁止事項リスト
    FEATURE_LIST.md    ← 機能リスト（制約ツール）
    PROGRESS.md        ← 進捗・状態の永続記録
    COMPLETION.md      ← 完了条件の定義
  phases/
    phase_01.md        ← フェーズ1の詳細指示
    phase_02.md        ← フェーズ2の詳細指示

ギャップ③：Feature List の「制約ツール」としての運用（講義08・11）

walkinglabs は Feature List を「実装すべき機能の一覧」ではなく「エージェントのスコープを制約するツール」として定義している。既存の対策では Feature List は「成果物リスト」として扱われており、「この Feature List 以外には手を出してはならない」という制約機能として設計されていない。

Feature List は以下の3要素を必ず含む必要がある。

項目 内容 例
IN SCOPE 実装すること Substack記事の自動投稿
OUT OF SCOPE 実装しないこと（明示的除外） コメント管理・読者分析
DEFER 将来のフェーズに延期 メルマガ連携

ギャップ④：E2Eテストの「ハーネス組み込み」設計（講義10）

walkinglabs は「E2Eテストはハーネスの一部として設計段階から組み込まれなければならない。後付けのテストは構造的な欠陥を見逃す」と指摘している。既存の対策ではテスト計画は「完成後に実施するもの」として位置づけられており、設計段階でのE2Eテストシナリオの事前定義が欠落している。

3. 強化提案：追加すべき4つのコンポーネント

3.1 Constraint Layer（制約層）の新設

既存の対策ファイルに加え、以下の CONSTRAINTS.md テンプレートをすべてのプロジェクトの標準ファイルとして追加する。

# CONSTRAINTS.md — エージェント禁止事項リスト

## 絶対禁止（いかなる場合も実行してはならない）
- [ ] 本番APIへの接続（dry-run確認前）
- [ ] ファイルの上書き・削除（確認プロンプトなし）
- [ ] 外部サービスへのデータ送信（テスト段階）
- [ ] 1セッションで2フェーズ以上の作業

## 条件付き禁止（明示的な承認がない限り禁止）
- [ ] 新しいライブラリ・依存関係の追加
- [ ] 既存コードの大規模リファクタリング
- [ ] スコープ外機能の実装

## 完了宣言の禁止条件（以下が未解消なら完了と言ってはならない）
- [ ] COMPLETION.md の全項目が未チェック
- [ ] Red判定が1件でも残存
- [ ] E2Eテストシナリオが未実行

3.2 CLAUDE.md 階層化テンプレート

すべてのプロジェクトで以下の構造を標準とする。

# CLAUDE.md — プロジェクト概要（このファイルは200行以内に保つ）

## このプロジェクトの目的（1文）
[ユーザーが伝えたいことを1文で記載]

## 現在のフェーズ
Phase: [1〜N] / [フェーズ名]
Status: [IN_PROGRESS / BLOCKED / COMPLETE]

## 必ず読むファイル（このセッションで作業する前に全て読むこと）
1. docs/harness/CONSTRAINTS.md — 禁止事項
2. docs/harness/FEATURE_LIST.md — スコープ定義
3. docs/harness/PROGRESS.md — 現在の進捗
4. docs/phases/phase_[N].md — 今フェーズの詳細指示

## 完了条件
docs/harness/COMPLETION.md を参照すること。
完了条件が全て満たされるまで「完了しました」と言ってはならない。

3.3 Feature List の「制約ツール」化テンプレート

# FEATURE_LIST.md — スコープ制約リスト

## ⚠️ このリストはスコープの境界線である
このリスト以外の機能を実装してはならない。
「あると便利そう」「ついでに」という理由での追加は禁止。

## IN SCOPE（実装すること）
| ID | 機能名 | 完了条件 | 優先度 |
|---|---|---|---|
| F-01 | [機能名] | [具体的な完了条件] | HIGH |

## OUT OF SCOPE（実装しないこと）
| 機能名 | 除外理由 |
|---|---|
| [機能名] | [なぜ今回は不要か] |

## DEFER（将来フェーズへ延期）
| 機能名 | 延期理由 | 対象フェーズ |
|---|---|---|
| [機能名] | [延期理由] | Phase N+1 |

3.4 E2Eテストシナリオの設計段階組み込みテンプレート

# E2E_TEST_SCENARIOS.md — 設計段階で定義するE2Eシナリオ

## ⚠️ このファイルは実装開始前に作成すること
テストは実装後に考えるものではない。
このシナリオが全て通過するまで完了宣言は禁止。

## シナリオ一覧

### S-01: [正常系シナリオ名]
- **前提条件：** [テスト開始時の状態]
- **実行手順：** [1. → 2. → 3.]
- **期待結果：** [何が起きるべきか]
- **確認方法：** [どうやって確認するか]
- **合否判定：** [ ] PASS / [ ] FAIL

### S-02: [異常系シナリオ名]
- **前提条件：** [エラーが起きる状態]
- **実行手順：** [1. → 2. → 3.]
- **期待結果：** [エラーが適切に処理されること]
- **確認方法：** [ログ・出力の確認方法]
- **合否判定：** [ ] PASS / [ ] FAIL

4. 強化後の完全ハーネス構造

既存の対策体系に上記4コンポーネントを統合した、完全なハーネス構造は以下の通りである。

project-root/
│
├── CLAUDE.md                    ← [既存+強化] 階層化・200行以内
│
├── docs/
│   ├── harness/
│   │   ├── CONSTRAINTS.md       ← [新規] 禁止事項リスト（ギャップ①対応）
│   │   ├── FEATURE_LIST.md      ← [強化] 制約ツールとして再設計（ギャップ③対応）
│   │   ├── PROGRESS.md          ← [既存] 進捗・状態の永続記録
│   │   └── COMPLETION.md        ← [既存+強化] 完了条件の明示的定義
│   │
│   ├── phases/
│   │   ├── phase_01_research_v1.md
│   │   ├── phase_02_research_v2.md
│   │   ├── phase_03_requirements.md
│   │   ├── phase_04_sdd.md
│   │   └── phase_05_harness_test.md
│   │
│   └── tests/
│       └── E2E_TEST_SCENARIOS.md ← [新規] 設計段階でのE2E定義（ギャップ④対応）
│
├── templates/                   ← [既存] 世界最高基準テンプレート群
│   ├── requirements_template.md
│   ├── sdd_template.md
│   └── test_plan_template.md
│
└── review/
    ├── ryg_gate_log.md          ← [既存] RYGゲート判定ログ
    └── codex_review_log.md      ← [既存] Codexレビュー記録

5. 非エンジニア向け「ハーネス設計の5原則」（walkinglabs 準拠）

walkinglabs の12講義を非エンジニアが実践できる形に圧縮すると、以下の5原則に集約される。

原則1：すべての指示はファイルに書く（会話に残してはならない）
セッションが切れた瞬間、会話の内容はエージェントから消える。指示・状態・完了条件はすべてリポジトリのファイルに書かれていなければならない。

原則2：禁止事項を先に書く（許可より禁止が先）
「何をすべきか」より「何をしてはいけないか」を先に定義する。禁止されていないことはすべて試みられると考えてよい。

原則3：スコープを「制約」として定義する（リストは境界線である）
Feature Listは「やること一覧」ではなく「これ以外はやってはならない境界線」として使う。

原則4：完了条件を実装前に書く（テストは後付けではない）
「完成したかどうか」の判断基準を実装前に定義する。E2Eテストシナリオは設計段階で作成する。

原則5：1セッション1フェーズ（欲張らない）
1回の会話で複数のフェーズを進めようとすると、コンテキストが枯渇し、前半の指示が忘れられ、破壊が起きる。

6. 既存対策との統合マップ

walkinglabs 講義 既存対策での対応 強化後の対応
講義01（能力≠信頼性） Codex/Claude役割分担 変更なし（充実）
講義02（ハーネスの定義） 部分的に言及 4層構造として明文化
講義03（リポジトリ＝唯一の情報源） CLAUDE.md言及 階層化テンプレート追加
講義04（巨大1ファイルの失敗） 未対応 CLAUDE.md 200行制限＋階層化
講義05（長時間タスクの継続性） progress.md言及 PROGRESS.md標準化
講義06（無制約の危険） RYGゲート CONSTRAINTS.md新設
講義07（過剰実行・未完了宣言） RYGゲート 完了条件の強化
講義08（Feature Listによる制約） 制約ツールとして未設計 IN/OUT/DEFER 3分類テンプレート
講義09（早期勝利宣言） 完了定義チェックリスト E2E未実行での完了禁止を追加
講義10（E2Eテスト） 設計段階での定義なし E2E_TEST_SCENARIOS.md新設
講義11（Feature Listのプリミティブ） 未対応 Feature Listの制約ツール化
講義12（統合） 部分的に実装 完全ハーネス構造として統合

7. 結論：既存設計の評価と強化後の完成度

既存設計の評価： 100点満点中 62点

既存の対策体系は「レビュー・テスト・ループ」の観点では世界最高基準に近い水準に達しているが、walkinglabs が定義する「ハーネスの骨格」——特に制約層・Feature Listの制約ツール化・E2Eの設計段階組み込み——が欠落していた。

強化後の評価： 100点満点中 91点

上記4コンポーネント（CONSTRAINTS.md・CLAUDE.md階層化・Feature List制約ツール化・E2E設計段階定義）を追加することで、walkinglabs の12講義が示す完全なハーネス設計基準を満たす体系となる。

残る9点は「実際のプロジェクトでの運用経験による継続的改善」によってのみ埋められるものであり、設計段階での完全性としては91点が現実的な上限である。

References

↑ トップへ戻る