ループの話ばかりが盛り上がっている。しかし、そのループが何の上で動いているのかを語る人はほとんどいない。10 人のビルダーのうち 9 人が、Claude Code をデフォルトのハーネス（ルールなし、サブエージェントなし、フックなし、メモリなし）で実行している。
そして、なぜループが粗悪なアウトプットを生み出すのかと不思議がる。真実は単純だ。ループの良し悪しは、その下にあるハーネス次第である。ここでは、ハーネスの 14 ステップのロードマップを紹介する——1 つのエージェントから、自己改善するシステムへ。
最新の AI アルファ情報を受け取るには、私の Substack をフォローしてください：
ループエンジニアリング——エージェントをスケジュールに従ってプロンプトするシステムを構築すること——が今月注目を集めた。しかし、ループに関する長文記事を書いた Addy Osmani 氏は、その下にあるものを指摘することに注意を払っていた。
「ループエンジニアリングはハーネスの 1 つ上の階層に位置する。ハーネスとは、単一のエージェントが内部で動作する環境のことだ。ループとは、ハーネスにタイマーが付き、ヘルパーを生成し、自己給餌するものである」
ハーネスエンジニアリングとは、その環境を設計することだ。すなわち、モデル、ツール、権限、コンテキスト、メモリである。
これは地味な階層だが、その上のすべてが機能するかどうかを決定する。優れたループも、粗悪なハーネスの上では、ゴミを大規模に生産する早道にすぎない。
14 ステップ。3 つの階層。その他すべてが立つ基盤。
パート 1 · ハーネスとは何か
01. ハーネスとは、1 つのエージェントが内部で動作する環境である。
専門用語を取り除けば、ハーネスは 4 つの要素から成る：思考を担うモデル、アクセス可能なツール、それらのツールに対する権限、そして各実行の開始時に読み込むコンテキストだ。
これが全体像である。それ以外のもの——サブエージェント、フック、メモリ——は、これら 4 つの要素のいずれかを形作る手段にすぎない。
ハーネスが人々の考え以上に重要な理由：エージェントは while True ループであり、ツールを選択し、実行し、結果を確認し、次の動作を決定する。
ハーネスは、どのツールが存在し、エージェントに何が許可され、開始時に何を知っているかを定義する。 同じモデルでも、異なるハーネスなら、まったく異なるエージェントになる。
02. ハーネス全体は 1 つのフォルダ .claude/ に収まる。
エージェントを形作るすべては、プロジェクトルートの 1 つのディレクトリに格納される。このレイアウトを覚えれば、誰のハーネスも一目で読めるようになる：
1.claude/2├─ CLAUDE.md # 恒久的な事実 — 毎セッション読み込まれる3├─ settings.json # 権限、モデル、フック4├─ .mcp.json # 外部ツール接続5├─ rules/ # パススコープの振る舞い6│ ├─ tests.md7│ └─ python-types.md8├─ agents/ # サブエージェント定義（各約 30 行）9│ ├─ reviewer.md10│ └─ eval-runner.md11├─ skills/ # 再利用可能なワークフロー12│ └─ pr-checklist/13│ └─ SKILL.md14└─ agent-memory/ # 実行間で保持されるもの15 └─ STATE.md
クリーンなハーネスと混乱したハーネスを分ける 1 つのルール：すべてのファイルの存在理由を説明できる程度に小さく保つこと。 ルール、フック、サブエージェントが何のためにあるのか言えなければ、削除する。
03. ハーネス vs ループ vs システム。3 つの階層、混同するな。
「エージェント設定が混乱している」という問題のほとんどは、3 つの階層を混同することから生じる。整理しておこう：
- ハーネスは、1 つのエージェントが存在するランタイムである。静的な設定：モデル、ツール、権限、コンテキスト。本号のテーマ。
- ループは、エージェントをタイマーでプロンプトし、ヘルパーを生成し、自己給餌する。ハーネスの上で動作する。
- 自己改善システムは、ループにメモリを加えたもので、累積効果を生む——実行のたびに次の実行がよりシャープになる。
実践的なバージョン：恒久的な事実はコンテキストに、強制はフックに、手順はスキルに、分離はサブエージェントに置く。
これらを混同する——強制事項を CLAUDE.md に、手順でコンテキストを膨らませる——ことが、一貫性がなくコストのかかるエージェントの根本原因である。
04. デフォルトのハーネス。箱から出してすぐに使えるもの。
Claude Code をインストールし、フォルダを開けば、すでにハーネスが存在する——ただ空っぽのものだが。デフォルトでは、有能なモデル、組み込みツール（読み取り、書き込み、bash、検索）、およびリスクのあるすべての操作に対する承認プロンプトが提供される。プロジェクトコンテキストもカスタムサブエージェントもメモリもない。
1 回限りのタスクにはデフォルトで十分だ。しかし、複数回行うことに対しては、デフォルトではエージェントが毎セッションゼロからプロジェクトを再導出し、安全な操作にも許可を求め、ターミナルを閉じるとすべてを忘れてしまう。
次の 10 のステップは、そのギャップを埋めることにある。
05. CLAUDE.md：恒久的な事実、簡潔に保つ。
CLAUDE.md は毎セッションの開始時に読み込まれる。これはエージェントのプロジェクトに関する恒久的な知識である——規約、アーキテクチャ、「あのインシデントのせいでこうはしない」。
最もよくある間違い：これを巨大な手順書にしてしまい、すべてのセッションを肥大化させること。
毎日これを実行している実践者からのルール：メインのメモリファイルは ~500 トークン未満に保つ。 恒久的な事実はここに置く。
複数ステップの手順はスキル（ステップ 8）に。パス固有の振る舞いは、適用されるスコープに応じて rules/ ファイルに。CLAUDE.md のセクションが事実ではなく手順になっているなら、それは別の場所に属する。
CLAUDE.md を声に出して読んでみよう。すべての行は、エージェントがすべてのセッションで必要とする
事実
であるべきだ（「pnpm を使う、npm ではない」）。もしある行が
手順
（「機能を追加するには、まず…」）なら、スキルに移動する。
それが1 つのフォルダのルールなら、rules/ に移動する。
06. settings.json：権限とモデルを 1 回設定する。
デフォルトのハーネスは、リスクのあるすべてのアクションの前に確認を求める。これは、あなたが監視しているときは正しいが、そうでないときは間違っている。settings.json は、安全なものを事前承認し、危険なものを拒否し、どのモデルを実行するかを選択する場所だ。
1{2 "model": "claude-sonnet-4-6",3 "permissions": {4 "autoApprove": [5 "Read(*)", "Grep(*)",6 "Bash(npm test)", "Bash(git status)"7 ],8 "deny": [9 "Bash(rm -rf*)", "Bash(git push*)",10 "Edit(.env*)", "Edit(secrets/*)"11 ]12 }13}
何を自動承認するかの判断基準：これが失敗した場合、元に戻すのはどれほど困難か？ 元に戻すのが簡単 → 自動承認。
元に戻すのが高くつく（force-push、ファイルの削除、機密情報へのアクセス） → 常に拒否またはプロンプト表示。ログを取るなら、中間領域は自動承認でも構わない。
07. サブエージェント：汚れ仕事のための隔離されたコンテキスト。
サブエージェントは、メインエージェントから起動される独立した Claude セッションである——独自のコンテキストウィンドウ、独自のツールリストを持つ。目的は並列性そのものではない。重要なのはメインのコンテキストからノイズを排除することだ。
40 ファイルを読む調査タスク、新鮮な視点が必要なレビューパス、ログの壁を生成する評価実行——これらはサブエージェントに任せ、メインスレッドを汚染しないようにする。
GIF
あらゆるハーネスで最も価値のあるサブエージェントは、メインエージェントが行った作業をチェックするものだ。モデルが自分のアウトプットをレビューするのは甘すぎる。
別のコンテキストウィンドウを持つ独立したレビュアーが、書き手が自分で納得させてしまったミスをキャッチする。これこそが書き手対チェッカーの分割であり、ハーネス上のすべてのループを信頼できるものにする。
08. スキル：エージェントが再利用する手順。
スキルとは、エージェントが実行する SKILL.md ファイルである——/スキル名 で呼び出すか、タスクがその説明に一致したときに自動的に実行される。
サブエージェントとは異なり、同じコンテキストウィンドウ内で実行される。セッションの一部となる再利用可能な指示にすぎない。
作成のトリガー：新しい会話のたびに同じ指示を貼り付けていることに気づいたとき。 それはスキルになるのを待っている。PR チェックリスト、評価手順、リリースプロセス——一度書けば、永久に呼び出せる。
そして、スキルは再利用可能な単位であるため、ハーネスを時間とともに改善するものとなる。手順が新しい方法で失敗するたびに、教訓をスキルに追加し、次の実行がそれを継承する。
09. フック：モデルが幻覚を起こせない決定論的ルール。
ここまでのすべては、モデルが指示を理解することに依存している。フックはそうではない。
フックとは、エージェントのライフサイクルの決まったポイント（ツール実行前、ファイル変更後、セッション終了時）で発動するシェルコマンドであり、その終了コードでアクションをブロックできる。フックは強制であり、CLAUDE.md は提案である。
ほとんどすべてのハーネスで役割を果たす 2 つのフック：
- PreToolUse ゲート：危険なコマンドを決定論的にブロックする——rm -rf、.env の読み取り、main へのプッシュなど。終了コード 2 で呼び出しが発生する前に停止する。モデルはごまかして通過できない。
- PostToolUse フォーマッター：編集後にリンターやフォーマッターを実行する。エージェントがフォーマットされていないコードを出荷することは決してない。なぜならハーネスが自動的にフォーマットするからだ。
1"hooks": {2 "PreToolUse": [{3 "matcher": "Bash",4 "command": "./.claude/hooks/block-dangerous.sh"5 // exit 2 = 呼び出しが実行される前にブロック6 }],7 "PostToolUse": [{8 "matcher": "Edit|Write",9 "command": "prettier --write \"$CLAUDE_FILE_PATH\""10 }]11}
フックは必ず起こさなければならないこと、または決して起こしてはならないこと（安全性、フォーマット、監査ログ）に使用する。
判断を要することには使用しない。それはモデルの役目だ。優れたハーネスには、鋭利なフックが 1 つか 2 つあればよく、20 も必要ない。
パート 3 · 累積効果を生む
10. ループを追加する。今やハーネスはタイマーで動作する。
設定済みのハーネスは、依然としてあなたが入力を待つ。ループがあれば、自律的に動作する。最も単純なバージョンは Claude Code の /loop で、一定間隔で繰り返されるプロンプトだ。
/loop に /goal を組み合わせると、ループは客観的な条件が真になるまで継続し、その条件はエージェント自身ではなく独立した評価者によってチェックされる。
1> /loop 30m /goal すべてのテストがパスし、lint がクリーンであること。2 新しい失敗をトリアージし、claude/ ブランチで修正案を作成する。34▲ Claude はあなたが構築したハーネスを使用する：5 - rules/ で規約を6 - reviewer サブエージェントで各修正をチェック7 - PreToolUse フックで main へのプッシュをブロック8✓ ループ中。独立した評価者が「完了」を判断する。
ここで何が起こったかに注目してほしい。ループは知能を追加したわけではない。ハーネス内のすべてを再利用した——ルール、レビューアサブエージェント、安全フック。優れたハーネスはループを些細なものにする。これがまさに、基盤を先に構築する理由である。
11. 動的ワークフローを追加する。ハーネスが自らのオーケストレーションを書く。
単一のループには複雑すぎるタスク——大規模並列、高度に構造化、敵対的——に対して、Claude はその場で独自の JavaScript ハーネスを書くことができる。
これが動的ワークフローである：spawn には agent()、ファンアウトには parallel()、ストリームには pipeline()。ハーネスが定義するサブエージェントを、ファンアウト＆シンセサイズや敵対的検証などのパターンに合成する。
ハーネスエンジニアリングとの関連：動的ワークフローの良し悪しは、それが呼び出せるサブエージェントとスキル次第である。
ハーネスに鋭いレビューアサブエージェントと適切に書かれた評価スキルがあれば、ワークフローはオーケストレーションするための良い部品を持つ。ハーネスが空なら、ワークフローは使えるものがない。
ワークフローは指揮者であり、ハーネスはオーケストラである。
12. メモリを追加する。エージェントが忘れるものを、ハーネスが記憶する。
これは、設定済みのハーネスを実際に改善されるシステムに変えるステップである。エージェントは実行間ですべてを忘れる。ハーネスはそうである必要はない。
状態ファイル——agent-memory/ 内のマークダウンファイル、または Linear ボード——は、試したこと、うまくいったこと、失敗したこと、生き残ったルールを記録する。
最も強力なエージェントの使い方から導き出された、メモリが累積効果を生むパターン：
- 離れる前に書き込む。 各実行は状態ファイルを更新して終了する——学んだ教訓、検証済みの事実、次にやること。
- 開始時に読み込む。 各実行は状態ファイルと関連スキルを読み込んで開始するため、再起動ではなく再開する。
- スキルに抽出する。 教訓が一般的な場合（「Windows ランナーは PowerShell ではなく bash が必要」）、状態ファイルからスキルに昇格させ、将来のすべてのプロジェクトに適用されるようにする。
1# プロジェクトメモリ23## 検証済みの事実 # これらについて推測するのをやめる4- prc はセントではなくドル単位（SELECT MIN/MAX で確認済み）5- 認証ミドルウェアの順序：rate_limit -> jwt -> rbac67## 学んだ教訓 # 一般的なものはスキルに抽出する8- Windows CI ランナーは PowerShell で TLS 1.2 に失敗する — bash を使用すること9- 100 万行を超えるテーブルのマイグレーションは 1 万件ずつバッチ処理する必要がある1011## 前回のセッション # 再起動せずに再開する122026-06-11 · 3 件の修正をマージ、2 件をエスカレーション。次：レート制限修正を検証する。
13. ループを閉じる。アウトプット → 教訓 → スキル → より良いアウトプット。
ここで 3 つの階層が連動し、自己改善する何かになる。各実行はアウトプットを生成する。レビューアサブエージェント（ステップ 7）がそれをチェックする。
その結果——合格したもの、失敗したもの、学んだこと——はメモリに書き込まれる（ステップ 12）。一般的な教訓はスキル（ステップ 8）に抽出される。
次の実行は、よりシャープなスキルとより豊かなメモリを継承する。
これが自己改善ループの全体であり、すべてハーネスの部品から構築されていることに注目してほしい：
- サブエージェントが作業を評価する——客観的なチェック、新鮮なコンテキスト。
- メモリが判定を記録する——実行間で保持される。
- スキルが教訓をカプセル化する——一般化して将来の作業に適用。
- ループが再実行する——前回の実行で学んだすべてを備えて。
モデルは決して変わっていない。その周りのハーネスがよりシャープになった。これが「自己改善」が実際に意味することだ——学習するモデルではなく、蓄積するハーネスである。
14. ハーネスを出荷する。パッケージ化する。共有する。再利用する。
1 つのプロジェクトで機能するハーネスは資産である。
スキル、サブエージェント、ルールをプラグインにまとめれば、チーム全員が同じ設定を 1 ステップでインストールできる——同じ規約、同じ安全フック、同じレビューア。
ハーネスは個人の設定ではなくなり、共有インフラになる。
構築の順序をもう一度、順序こそが教訓なので：まず、クリーンなハーネス上で 1 回の手動実行を信頼できるものにする。
コンテキストと権限を追加する。レビューアサブエージェントを追加する。メモリを追加する。そして、その後に初めてループでラップする。 優れたハーネスの上のループは累積効果を生む。粗悪なハーネスの上のループは、ただ速く出血するだけだ。
§ すべてのループを悪化させるハーネスのミス
- デフォルトで実行する。 コンテキストもルールもメモリもない——エージェントが毎セッションプロジェクトを再導出する。
- 肥大化した CLAUDE.md。 手順が恒久的なコンテキストに詰め込まれ、すべての実行を膨らませる。スキルに移動する。
- 強制を CLAUDE.md で行い、フックを使わない。 モデルは提案を無視できる。終了コード 2 のフックは無視できない。
- 1 つのエージェントが自分の作業を書き、評価する。 新鮮なコンテキストウィンドウを持つレビューアサブエージェントを追加する。
- メモリがない。 すべての実行がゼロから再起動する。状態ファイルこそが、明日を再開可能にするものだ。
- 粗悪なハーネスにループをかける。 ループはゴミをより速く生産するだけだ。まず基盤を構築する。
- 20 個のフック。 1 つか 2 つの鋭いフックが、誰も理解しない山積みに勝る。
- スキャンせずにハーネスを出荷する。 漏洩した機密情報や過度に広い権限が、インストールする全員に拡散する。
まとめ：
ループが栄光を手にする。ハーネスが仕事をする。
ループエンジニアリングはエキサイティングな部分だ——エージェントが自分自身をプロンプトし、あなたが寝ている間に動作する。しかし、ループとはタイマーが付いたハーネスにすぎない。
アウトプットが良いかゴミかを決定するすべては、1 階層下、つまりあなたが選んだモデル、許可したツール、書いたコンテキスト、追加したレビューア、保持したメモリにある。
その階層をしっかりと構築すれば、その上のすべてが累積効果を生む：ループはサブエージェントを再利用し、ワークフローはスキルをオーケストレーションし、メモリは各実行を前回よりシャープにする。
自己改善は決してモデルの特性ではなかった。それは、あなたがモデルの周りに構築するハーネスの特性である。
まだやっていないことを 1 つ選んで——おそらくレビューアサブエージェント、安全フック、または状態ファイル——今日追加しよう。ハーネスを説明できる程度に小さく保つ。そしてその上にループを置き、基盤が仕事をするのを見守ろう。
