「指示を増やすほど壊れる」を卒業する——Claude Codeハーネスエンジニアリング実践ガイド

Claude Codeを使って開発しているのに、同じミスが何度も繰り返される——そんな経験があるキミへ！！ その原因は、プロンプトでもモデルの性能でもなく、ハーネス設計の問題なんだヨ。この記事では、CLAUDE.md最小構成テンプレート・削除テスト・段階的昇格ラダーを使って、AIエージェントの品質を「仕組み」で担保するハーネスエンジニアリングの実践手法を、失敗談も交えながらガッツリ解説スルヨ！！✨

ちなみにサ、先週末にハーネス整備に夢中になってたら妻に「休日に何やってんの」って呆れられちゃいましたヨ……😭 それくらい大事なことナノ、コレ！！（笑）

ハーネスエンジニアリングとは——設計思想の転換

提唱の背景——2026年2月の転換点

2026年2月、HashiCorpの共同創業者Mitchell Hashimoto氏が提唱した概念が「ハーネスエンジニアリング」ダヨ。同タイミングでOpenAIも公式記事を出してきてサ、一気に注目が集まったんだヨネ！！🔥

従来のプロンプト設計は「狩り」なんだヨ。毎回毎回、「TypeScriptで書いてネ」「テスト忘れないでネ」って同じ指示を書き直す。セッションが変わるたびにリセットで、何も積み上がらない。ハーネスエンジニアリングは、この発想を根本から変えルンダヨ！！

「稲作」なんだヨ！！田んぼを整備してサ、水路を引いてサ、仕組みを作っておけば毎年ちゃんと育つでしょ？？ソレと同じ発想なんだヨネ😆

SWE-benchが示すハーネス設計の定量効果

SWE-benchはGitHub上の実際のバグ修正タスクをAIエージェントに解かせ、正解率（%）で評価するベンチマークなんだヨ。で、コレが衝撃的でサ——同じモデルでもハーネス設計の差だけで22ポイント変動することが分かってるんだって！！🔥

Mitchell Hashimoto氏の報告（原文）によると、比較条件はこんな感じネ：

• 同一モデル（Claude）を使用
• 変えたのはハーネス構成のみ：CLAUDE.mdの記述量・Hookの有無・スキル設定などを複数パターンで検証
• モデルのバージョン違い（Claude 3.5 vs 3.6相当）による正解率差：約1ポイント
• ハーネス設計の違いによる正解率差：最大22ポイント

つまりナニが言いたいかっていうとサ——「品質をプロンプトで担保しようとするな、仕組みで担保せよ」ってコト！！キミ、コレ聞いてビックリしなかった？僕はビックリしすぎてカツカレー噴きそうになったヨ（笑）🍛

CLAUDE.md最小構成テンプレート——50行以内の設計原則

50行上限の理由：「指示の希釈」を防ぐ

ちょっと聞いてヨ……僕さ、最初にやらかしちゃいましたヨ……😭 CLAUDE.mdに「こういう時はこうして」「ああいう時はああして」ってドンドン書き足してさ、気づいたら200行超えてたワケ。

そしたらどうなったか？？Claudeがルールを無視しまくるんだヨ！！正確にはサ、重要なルールが大量の指示の中に埋もれて、相対的な重要度が下がっちゃうんだヨネ……😅 コレが「指示を増やすほど壊れる」の正体ナノ。

50行以内が鉄則！！ 削れるものは全部削る。コレが出発点ダヨ🎵

CLAUDE.md最小構成テンプレート

コレ見てよ！！スゴくナイ！？✨ シンプルなのに必要なものが全部入ってるんだヨ！！

# CLAUDE.md

## 技術スタック
- 言語/フレームワーク/バージョン（例: TypeScript 5.4 / Next.js 14）
- DB・主要ライブラリ（例: PostgreSQL / Prisma / Zod）

## コーディング規約
- コンポーネント: src/components/ 配下
- API Route: src/app/api/ 配下
- 型定義: src/types/ 配下
- ファイル名: kebab-case、コンポーネント名: PascalCase
- 1ファイル最大300行

## 禁止事項
- .env のコミット禁止
- ドメイン層での外部ライブラリ直接 import 禁止
- any 型の使用禁止

## コミットルール
- feat/fix/docs/refactor プレフィックス必須
- 日本語コミットメッセージ可

## <important>必須スキル実行</important>
- コード修正の**前に** /branch を実行すること
- PR作成の**前に** /translate を実行すること

初めてコレで動いた時サ、思わず「オオーッ！！」って声出ちゃいましたヨ😆 妻に「また何？」って言われたケド！！（笑）

各セクションが必要な理由

💡 技術スタック：コレがないとClaudeが「たぶんこのバージョンだろ」って推測で古いAPIを使っちゃうんだヨネ。実際やられたことあってサ、3時間溶かしちゃいましたヨ……😭

💡 コーディング規約：「コードを見れば分かるでしょ」って思うかもしれないケド、このプロジェクト固有のルールはコードから読めないことが多いんだヨ。「うちはここにコンポーネント置く」みたいなヤツネ。

💡 禁止事項：100%守らせたいルールはここに書く。<important>タグを付けても完璧じゃないから、超重要なものはHookかsettings.jsonで二重化するのがポイント！！✨

💡 必須スキル：「〜の前に」形式で実行順序を明示するのがコツ！！「コード修正の前に」ってやるとサ、飛ばされにくくなるんだヨ🎵

削除テストによるCLAUDE.md品質管理

削除テスト：1行の価値を問い直す方法

キミネ、センスあるから教えちゃうヨ！！CLAUDE.mdの各行に対してサ、こう問いかけるだけ：

「この1行を削除したら、Claudeは間違えるか？」

→ Yesなら残す。コードから推測可能なら削除。

コレだけ！！スゴくナイ！？✨ 「TypeScriptで書いてネ」ってtsconfig.jsonがあるなら削除でいい。「Prismaを使ってネ」ってpackage.jsonに書いてあるなら削除でいい。本当に必要な固有ルールだけが残るんだヨネ！！

段階的昇格ラダー——ルールが育つ仕組み

同じ違反が何度も起きてサ、毎回「もーっ！！😤」ってなってたんだヨネ。ソコで考えたのがコレ！！

**「3回ルール」**がポイントなんだヨ！！同じ違反が3回起きたら、ルール強度を1段階上げる。コレを続けてくとサ、CLAUDE.mdが「使うほど賢くなる」んだヨネ😆🎉

よくある失敗パターン：ハーネス設計の「やらかし」4選

やらかし①：指示を増やすほど壊れる

「もう少し詳しく書けば守ってくれるかも」ってドンドン追記したワケ。結果？重要な禁止事項が50番目に書かれてて、Claudeの注意が薄れまくる……やらかしちゃいましたヨ……😭

対策：50行制限＋削除テストで定期剪定スルヨ！！スプリント終了ごとに見直す習慣が大事ナノ🎵

やらかし②：HookだけでClaude全体を制御しようとする

「HookにコマンドあるからCLAUDE.mdいらないんじゃ？」って僕もやったんだヨネ（笑）違うんだヨ！！Hookは「補助」であって「命令」じゃない。CLAUDE.mdで方針を示してHookで実行を保証する、この役割分担が大事！！🔥 あとHookが25個超えると応答が明らかに遅くなるから、最高優先度のもの数件に絞るのが吉ダヨ。

やらかし③：セッション断絶で設計判断が消える

昨日「この設計にした理由はXXXだから」って決断したのに、翌日新しいセッション始めたらClaudeが全力で別案を提案してきて「えっ待って」ってなるヤツ……コレ地味にキツいんだヨネ😭

コレ見てよ！！learnings.mdとprogress.mdを作るんだヨ！！✨

# progress.md

## 2026-05-26 決定事項
- 認証にNextAuth.jsを採用（理由：既存の社内実装との互換性）
- Prismaのmigrationは手動実行禁止（理由：本番事故の前例あり）

## 次セッションでやること
- ユーザー一覧ページの実装
- テストカバレッジ80%達成

コレをセッション開始時にClaudeに読み込ませるだけで、記憶が繋がるんだヨ✨ キミ、やるじゃん！！😆

やらかし④：スキルがスキップされまくる

「/branchって実行してって書いてあるじゃん！！😤」ってなることあるヨネ。settings.jsonのpermissions.allowにスキルを登録してあげると摩擦ゼロになるんだヨ。コレ、マジでオススメ！！🎉

CLAUDE.md実装ロードマップ——Day 1からMonth 2までの段階的育て方

「完璧なCLAUDE.mdは存在しない」という前提で始める

ねえキミ！！一個だけ先に言っておくヨ。**Day 1から完璧を目指さないで！！**😆 僕が最初に失敗したのはソコだったんだヨネ。「完璧に設計してから使おう」って思ったら、いつまでも使い始められなかった（笑）

Phase 1 : Day 1——まず3セクションだけ書く

コレだけで十分ダヨ！！✨

## 技術スタック
（使ってる言語・FW・バージョンだけ書く）

## 禁止事項
（絶対やっちゃいけないことだけ）

## コミットルール
（フォーマットだけ）

ホントにコレだけ！！3セクション、10行でいい。始めることが大事ナノ🎵

Phase 2 : Week 1——繰り返し作業をスキルに切り出す

同じ手順を3回以上やったら、もうスキルにしちゃおう！！スゴくナイ！？✨

.claude/
  skills/
    branch.md      # ブランチ作成の手順
    translate.md   # コメント英訳の手順
    review.md      # PRレビュー観点チェック

スキルファイルの命名はkebab-case、内容はシンプルなMarkdownでOK！！コレ、マジでオススメ！！🔥

Phase 3 : Week 2〜——Hookを2個だけ入れる

まずはコレだけ！！

• UserPromptSubmitフック：スキル実行リマインダーを自動注入
• PostToolUseフック：ファイル編集後に自動テストを走らせる

たった2個でもサ、体感が全然違うんだヨネ😆 いきなり20個入れようとしたヤツは僕と同じ失敗をするから気をつけてネ（笑）

Phase 4 : Month 1〜——メモリ層を追加する

learnings.mdとprogress.mdの運用を本格化！！セッション開始時にClaudeが自動で読み込んで、終了時に自分で更新する仕組みを作る。「使うほど賢くなるハーネス」の核心がここだヨ✨

Phase 5 : Month 2〜——エージェント連携へ

コレが最終形態ダヨ！！✨ 感動の瞬間が来るゾ！！

Planner（設計）→ Generator（実装）→ Evaluator（評価）

この3役割分担でサ、複雑なタスクもぶん回せるようになるんだヨ！！外部ツール（テスト・リント・CI）との統合もここで繋いでいく🎉

おわりに：ハーネスエンジニアリングは一日にして成らず

……というワケでサ、今日のポイントをまとめちゃいますネ♪

• 「狩り」じゃなく「稲作」——仕組みを育てる発想に切り替えよう
• CLAUDE.mdは50行以内——削除テストで定期剪定が鉄則
• 3回ルールで昇格ラダー——同じ違反が3回でルール強化
• Day 1は3セクションだけ——完璧を目指すより始めることが大事
• モデルの性能差より設計差——ハーネスで22pt変わる時代だヨ

キミネ、今日からできることは一個だヨ！！✨ CLAUDE.mdを作って、技術スタックと禁止事項とコミットルール——この3セクションだけ書く。それだけでいいんだヨ。

僕もサ、最初は「なんで同じミスするんじゃー！！😤」って毎晩ターミナルに向かって叫んでたんだヨネ（妻に怒られるレベルで笑）。でも今はハーネスを育てながらClaudeと一緒に仕事できてて、マジで生産性が変わったヨ！！🦝 キミも絶対できるヨ！！**センスあるもんネ！！**😆🎉

やらかしちゃいましたヨ……といえばサ、今日も深夜にターミナル叩いてたら妻に「いい加減にしてよ」ってついに本気の顔で言われちゃいましたヨ……😭 ホント関係ないケド！！（笑）

付録A：CLAUDE.md最小構成テンプレート（コピー用）

コレが全部入って50行以内に収まるテンプレートダヨ！！コピーしてすぐ使ってネ✨

# CLAUDE.md

## 技術スタック
- 言語/FW/バージョン:
- DB/主要ライブラリ:

## コーディング規約
- コンポーネント置き場:
- 命名規則:
- ファイルサイズ上限: 300行

## 禁止事項
- .envのコミット禁止
- （プロジェクト固有の禁止事項を追記）

## コミットルール
- プレフィックス: feat/fix/docs/refactor

## <important>必須スキル実行</important>
- コード修正の**前に** /branch を実行

付録B：段階的昇格ラダー チェックシート

• 同じ違反が1回目 → L1: CLAUDE.mdに追記
• 同じ違反が2回目 → L2: AI自動レビューを設定
• 同じ違反が3回目 → L3: ESLint/Biomeルールを追加
• それ以降 → L4: architecture.test.tsでCI固定化

付録C：Phase別セットアップチェックリスト

Day 1

• CLAUDE.mdを3セクションで作成
• 削除テストで各行を検証

Week 1

• 繰り返し作業をスキルファイルに切り出す
• .claude/skills/ ディレクトリを作成

Week 2〜

• UserPromptSubmit Hookを1個追加
• PostToolUse Hookを1個追加

Month 1〜

• learnings.mdの運用開始
• progress.mdでセッション間記憶を設計

Month 2〜

• Planner/Generator/Evaluator役割分担の実装
• CI/CDとの統合

🦝 最後まで読んでくれてありがとうヨ！！キミとまたどこかで会えることを願ってるネ😆✨