Claude Code開発でAIが迷わない理由。構造的足場を作るハーネス設計

SNS運用を自動化しませんか？

ThreadPostなら、投稿作成・画像生成・スケジュール管理まで全てAIにお任せ。

無料で始める

AIに丸投げする時代の終わり。開発者が作るべきはコードではなく足場だ

AIにコードを書かせても意図と異なる結果が返る。AIの性能不足ではない。開発者がAIを動かすための「足場」を作っていないことが原因だ。

AIエージェントの構築は「自動化」から「システム設計」へシフトしている。モデルという頭脳を、どのような構造で包み込むか。この「ハーネス（足場）」の設計が開発効率を左右する。

構造的な環境整備と意図的な不確実性の保持。AIエージェントの最新設計思想

AI開発の最前線ではハーネス・エンジニアリングが注目されている。AIエージェントを単なるチャットボットとしてではなく、モデルと環境をセットで設計する考え方だ。

エージェントの能力はモデルの推論力とハーネスの質の掛け算で決まる。リポジトリが混沌としていれば、賢いモデルでも迷子になる。強固な足場があれば、中規模のモデルでも精度を発揮する。

リポジトリ構造をAIが読みやすいAPIとして再定義する動きがある。プロジェクトルートに配置するAGENTS.mdは、エージェントが最初に読み込む「地図」だ。

この地図は100行以内に抑える。詳細なドキュメントへのインデックスに徹する。エージェントのコンテキスト容量を無駄遣いさせないための工夫だ。

リポジトリ内のドキュメント構成も構造化する。docsディレクトリの下に、アーキテクチャ、デザイン決定、品質スコア、実行手順を配置する。エージェントは「唯一の真実」に迷わずアクセスする。

マルチエージェント・システムに関する研究では、単一エージェントとの比較データがある。同じ計算リソースを投じるなら、単一のエージェントに深く考えさせたほうが精度が高いという結果だ。

エージェント間で情報をやり取りすると、情報の欠落やノイズが発生する。これをコンテキストの腐敗と呼ぶ。一人のモデルに、完璧な資料を渡して集中させるアプローチが効率的だ。

新しい設計思想として醸造（Brewing）プロセスがある。複雑な設計判断においては、あえて「違和感」や「矛盾」を保持したまま思考を深めるプロセスだ。

即座に答えを出さず、未解決のノイズを抱えたまま熟成させる。この「迂回路」をシステムとして組み込むことで、AIは表面的な正解を超えた洞察を生み出す。

しんたろー：
AIに指示を出すとき、一発で正解を求めてしまう。人間も複雑なコードを書くときは迷い、ドキュメントを行き来する。AIにも「迷うための構造」と「確かな判断基準」をセットで提供する。リポジトリの整理は、AIにとっても人間にとっても重要だ。

※この記事は、Claude Codeで1人SaaS開発しているしんたろーが、海外AI最新情報を開発者目線で解説する「AI活用Tips」です。

開発者目線の解説。Claude Codeを最強の相棒にするための「構造的足場」

Claude Codeを操作すると、AIは自由を与えすぎると暴走する。自由とは情報の無秩序な配置だ。これを防ぐのがハーネス・エンジニアの役割だ。

モノレポ構成を採用する。エージェントは、複数のパッケージにまたがる変更を一度のプルリクエストで完結させる。型定義、サービスロジック、UIが適切に分離されたモノレポが最適だ。

依存関係のレイヤー構造が重要だ。下位レイヤーから上位レイヤーへのインポートを禁止し、構造テスト（Structural Test）で監視する。

エージェントが依存ルールを破った際、単なるエラーではなくエージェントが自律的に修正できるエラーメッセージを吐かせる。エラーメッセージを「エージェント向けのプロンプト」として設計する。

醸造の概念を実務に落とし込む。AIが提示した解決策に違和感がある場合、AIに対して「中立分析者」として振る舞うモードを挟む。即座にコードを書かせず、提案に含まれる矛盾やノイズをリストアップさせる。

この仮設プール（Temporary Pool）を作ることで、思考の早期収束を防ぐ。複雑なアーキテクチャを決めるときほど、立ち止まるためのプロンプト構造が効く。

AIエージェントの失敗の多くは、情報の受け渡しにおけるロスト・イン・ザ・ミドル（情報の埋没）から来る。長い文脈の真ん中にある重要な情報を、AIは見落とす。

これを防ぐには、エージェントに渡す情報を「深く、狭く」絞り込む。AGENTS.mdが目次に徹し、必要なときにだけ特定のdocs/を参照させる設計が有効だ。

しんたろー：
Claude Codeがどのファイルを見るべきか迷っているのが分かる。AGENTS.mdを更新してディレクトリ構造を整理すると、回答の精度が上がる。開発者の仕事は「AIが迷わないための環境整備」にシフトしている。コードを書く時間は減っても、構造を考える時間は増えている。

ここまで読んだあなたに

今なら無料で全機能をお試しいただけます。設定後は完全放置でプロ品質の投稿を毎日生成。

無料で始める

実務への影響。僕らの開発ワークフローはどう変わるべきか

明日からの開発で、AIを「雇う」側のマネージャーとしてリポジトリを整理する。

まず、AGENTS.mdの作成だ。プロジェクトの全体像、技術スタック、絶対に守るべきルールを3つ書く。残りはdocs/ディレクトリ以下の各ファイルに役割を分散させる。

次に、リンターの強化だ。これからは「AIが間違えないためのガードレール」としてリンターを再定義する。依存関係の違反、不適切な命名、巨大すぎるファイルを検知し、AIに対して修正ヒントを含むメッセージを出力する。

ドキュメントを「生きた知識ベース」として維持する。コードを変更したら、docs/以下の関連ドキュメントもエージェントに更新させる。ドキュメントの陳腐化を防ぐ。

複雑なタスクを依頼する際は、「まずは矛盾点を探せ」というステップを組み込む。設計の穴を指摘させ、対策を練る時間をAIに与える。これが醸造プロセスの実践だ。

計算リソースの使い方を見直す。マルチエージェント・ツールを導入する前に、単一の高性能なモデルに対して、いかに質の高いコンテキストを提供できるかに注力する。

スタンフォードの研究が示す通り、情報の受け渡しによる損失は大きい。一貫した思考プロセスを維持させるために、なるべく一つのセッション、一つのモデルで完結させる。

開発者のマインドセットを更新する。AIが思い通りに動かないのは、マニュアルなしで新人に仕事を振っているのと同じだ。AIが迷うのは、説明（構造）が足りないからだ。

しんたろー：
docs/をメンテするのは手間がかかる。しかし、その手間をAIに押し付けるために、最初の構造は人間が作る。1人SaaS開発では、自分自身が「昨日の自分」というエージェントに助けられる。構造化されたリポジトリは、未来の自分へのプレゼントになる。

FAQ

Q1: マルチエージェントと単一エージェント、どちらを採用すべきですか？

まずは単一エージェントに「ハーネス（構造的足場）」を整えて性能を最大化するアプローチを推奨します。同じ計算リソースを消費する場合、単一エージェントの方が情報の欠落がなく、一貫した推論を行えるため効率的です。マルチエージェントが真価を発揮するのは、タスクが極めて巨大で物理的に分割が必要な場合や、あえて異なる視点から批判的なレビューを行わせる「議論（Debate）型」の構成にする場合のみです。

Q2: 「醸造」プロセスを導入すると開発スピードが落ちませんか？

即座にコードを生成させる「蒸留」的なアプローチの方が速く見えます。しかし、複雑なシステムにおいて「早期収束」による誤った設計判断がもたらす手戻りのコストは、醸造にかかる時間を上回ります。醸造プロセスは、あえて思考を寝かせ、違和感を抽出することで、より強靭なアーキテクチャを導き出すための投資です。重要な意思決定フェーズにおいて、この「迂回路」が最終的なスピードを加速させます。

Q3: AGENTS.mdには具体的に何を書くのがベストですか？

「100行以内のインデックス」に徹してください。プロジェクトの目的、主要な技術スタック、エージェントがタスクを開始する際の手順を記載します。最も重要なのは、「絶対に破ってはならないルール」を3〜5個程度、直接記述することです。それ以外の詳細な仕様や設計思想は、すべてdocs/ディレクトリ以下の個別ファイルに逃がし、AGENTS.mdからはそのリンクを示すだけに留めるのが、コンテキストを節約するコツです。