Claude Code に学ぶ「AIエージェントを支える12の設計パターン」の記事をまとめてみた。 ※前提知識も説明してあるので読んでみてほしい。 ■先に押さえておくポイント（3つ） - AIエージェントの出来を左右するのは、AIモデルの賢さだけではない。 モデルの周りを囲む「仕組み」の設計も同じくらい重要である。 - その仕組みは、記憶・作業の流れ・ツールと権限・自動化の4分野、全12パターンに整理できる。 - どのパターンにも利点と代償がある。 一部を真似るより、「何を仕組みに任せ、何をAIに任せるか」という考え方を持ち帰ることが本題である。 --- ■前提知識 - AIエージェント： 質問に答えるだけでなく、ファイルを読み、コードを書き換え、コマンドを実行して、自分で作業を進めるAIのことである。 - Claude Code： Anthropic社が作った、プログラミング作業をこなすAIエージェントである。 - ハーネス（harness）： 元は馬具の意味で、モデルを包み込んで制御する外側の仕組みを指す。モデルがエンジンなら、ハーネスはハンドル・ブレーキ・ナビを含む車体である。 - コンテキスト： AIが一度に読める作業用の記憶である。容量に上限があるため、何を入れて何を捨てるかが重要になる。 - MCP： AIに外部ツールを追加でつなぐための共通規格である。 元記事の図には「Claude Code の流出ソースコードから学んだ」という副題がある。 12パターンは理想論ではない。 実際に動いている製品の内部設計から抜き出したものである。 --- ■記憶とコンテキスト（5つ） AIは会話のたびに記憶がリセットされ、作業用の記憶にも上限がある。 この2つの弱点を補うためのパターンである。 1. 常設の指示ファイル： ビルド方法や命名規則などを書いたファイル（CLAUDE.md など）を毎回最初に読ませる。 毎回ゼロから始めずに済む。ただし内容が古くなると、AIは間違ったことを自信満々に実行してしまう。 2. 範囲別のコンテキスト組み立て： 組織・ユーザー・リポジトリ・ディレクトリの各階層にルールを置き、作業中の場所に関係するルールだけを組み合わせて読ませる。 大規模なリポジトリで有効である。 一方で、ルール同士がぶつかったときに、最終的にどの指示が効いているのか分かりにくくなる。 3. 階層型メモリ： すべての記憶を同じ扱いにはしない。 小さな「索引」は常に読み込み、話題別のファイルは必要なときだけ読む。 会話の全記録はディスクに置いておき、検索で引き出す。 4. 夢の整理（記憶の統合）： 人が眠っている間に記憶を整理するように、空き時間に裏で記憶の重複・矛盾・古い情報を掃除する。いわば記憶のごみ収集である。消しすぎると、ユーザーがまだ必要としている情報まで失う危険がある。 5. 段階的なコンテキスト圧縮： 直近の会話はそのまま残し、少し前の会話は軽く要約し、かなり前の会話は大きく縮める。 完璧に覚えることは目指さない。作業を続けるのに必要な決定事項と現在の状態を残すことが目的である。 ■作業の流れと分担（3つ） 6. 探索 → 計画 → 実行： 最初は読むだけでコードを調べ、次に方針を合意し、そこで初めて編集を許す。 簡単な作業には手間が増えるが、よく知らないコードをいきなり壊す事故を防げる。 7. コンテキストを隔離したサブエージェント： 調査や見直しなどを、別の作業用記憶を持つ子エージェントに任せ、結論だけを受け取る。 本体の記憶が雑多な情報で埋まらずに済む。その代わり、引き継ぎの質や調整の手間が課題になる。 8. 分岐・合流による並列化： 互いに独立した作業なら、複数のエージェントを別々の作業コピー（worktree）で同時に動かし、最後に結果をまとめる。 ただし速くなるのは担当範囲がきれいに分かれているときだけである。 同じ場所を編集すると、統合作業に追われることになる。 ■ツールと権限（3つ） 9. 段階的なツール追加： 最初から全部のツールを見せない。 少数の基本ツールから始め、必要なときにMCPや外部機能を追加する。選び間違いと記憶の消費が減る。 ただし「今ツールが必要だ」とハーネス側が気づける必要がある。 10. コマンドのリスク分類： 実行前にコマンドを解析し、危険度で「自動で実行・人に確認・禁止」に振り分ける。 図の例では、npm test は自動実行、git push --force は確認、rm -rf / は禁止である。 毎回確認を求められて疲れる問題を防げるが、新しいコマンドが出るたびにルールの手直しが要る。 11. 単機能ツールの設計： 何でもできるシェルでファイル操作を工夫させるより、「読む・編集する・検索する・一覧を出す」といった専用ツールを用意する。 用途が狭い道具の方が、AIにも権限チェックにも判断しやすい。シェルは例外的な場面の予備として残す。 ■自動化（1つ） 12. 決まった時点で動くフック： コマンドを実行する前の安全確認、編集した後の整形、作業場所が変わったときの設定の再読み込み、作業記録の保存などを、プロンプト（AIへの指示文）ではなく仕組みとして自動で必ず実行させる。 絶対に忘れてはいけないことを、AIの記憶に頼ってはいけないというのが核心である。 代わりに、フックという別の実行層が増えるため、動きを見える化し、不具合を調べられるようにしておく必要がある。 --- ■この記事が本当に伝えたいこと これらは一時しのぎのプロンプトの小技ではない。 長く通用する設計上の判断である。 モデルがどれだけ賢くなっても、記憶の容量、誤操作の危険、作業の分担という問題はなくならない。 だから優れたAIエージェントを作るには、モデル選びと同じくらい、その周りのハーネスを丁寧に設計する必要がある。 #Agentic #Harness #Claudecode #Calude