【2026年版】Claude Codeエージェント開発5ステップ｜自然言語で作る自律型AI

結論から言うと、AIエージェントの開発に複雑なプログラミングはもう必要ない。自然言語で書かれたマークダウンファイルを用意するだけで、自律的に動くAIを構築できる。この記事では、Claude Codeを使って、賢いAIエージェントを作るための5つのステップを解説する。

LLMエージェント開発の前提知識

必要なものはClaude Codeの実行環境と、使い慣れたテキストエディタだけだ。高度なPythonの知識や、複雑なAPIの連携コードを書く必要は一切ない。プロジェクトのディレクトリ内に特定のマークダウンファイルを配置していくだけで、AIが勝手にルールを読み込んで賢くなっていく。初心者でも順番に進めれば確実に設定できる。

ステップ1: LLMエージェントの基本設計思想（サンドイッチ構造）を理解する

AIエージェントを安定して動かすための最大の秘訣は「サンドイッチ構造」にある。これは、自然言語で書いた曖昧さを許容する指示と、その結果を処理する決定論的なプログラムを交互に挟み込む設計手法のことだ。

初心者がやりがちな失敗は、1回のプロンプトに「要件定義から実装、テストまですべてやって」と複雑な指示を詰め込んでしまうことだ。これをやると、AIの推論品質は一気に低下する。LLMの特性として、一度に多くのコンテキストを与えすぎると重要な指示を見落とす傾向があるからだ。

正しいアプローチは、タスクを細かく分割することだ。たとえば「ログファイルからエラー文言を抽出する」という自然言語のステップの次に、「抽出した文字列をデータベースの検索クエリに変換する」という固定のプログラム処理を挟む。そして最後に「検索結果から解決策を提案する」という自然言語のステップに戻す。

このように役割を小さく保つことで、AIの出力は驚くほど安定する。Claude Codeでもこの思想は同じだ。複雑な処理を1つのファイルにまとめるのではなく、役割ごとにマークダウンファイルを分割して指示を出すことが、優秀なエージェントを作る第一歩になる。

ステップ2: MEMORY.mdによるプロジェクトの自動学習と記憶管理

AIと開発していると、「昨日教えたルールをまた忘れている」とイライラすることがあるはずだ。これを改善するのが、Claude Codeの自動学習機能だ。

プロジェクトのルートディレクトリに配置する「CLAUDE.md」は、チーム全体で共有する絶対的なルールを記す指示書として機能する。コーディング規約やテストの方針など、絶対に守るべき事項をここに書く。

一方で、AIが自律的に学んだことを記録するのが「MEMORY.md」だ。これはAI専用の学習ノートと言える。デバッグ中に見つけたエラーの解決法や、ユーザーの好みの書き方などを、AIが会話の中から自動で判断してこのファイルに書き込んでいく。

情報量が増えてくると、AIは自動的にトピック別のファイルを作成する。たとえばデバッグ専用のファイルや、アーキテクチャ専用のファイルなどを生成し、MEMORY.mdをインデックスとして整理し始める。この自律的な記憶の整理機能により、人間が手動でドキュメントをメンテナンスする手間から解放される。この2つのファイルを使い分けることで、セッションをまたいでも記憶喪失が起きない、専用の賢いAIに育っていく。

しんたろー：
Claude Codeで毎日コードを書いている身からすると、このメモリ機能が一番使いやすかった。
理由はシンプルで、毎回「このプロジェクトではTypeScriptを使って」と指示する手間が完全に消滅したからだ。自動で学習ノートを作ってくれる感覚は本当に心地よい。

ステップ3: AI Skillsを用いたプロジェクト固有のベストプラクティス導入

AIは一般的なコードを書くのは得意だが、あなたのプロジェクトに特有の「正解」を知らない。新しいフレームワークやライブラリを導入したとき、AIが古いバージョンの書き方をしてエラーになるのはよくある話だ。

そこで活躍するのが「AI Skills」という仕組みだ。これは、AIに「このプロジェクトではこうやって書くのが正解だ」と教え込むためのファイル群だ。特定のディレクトリ、たとえば「.claude/skills」の中にベストプラクティスをまとめたマークダウンファイルを配置するだけでいい。

たとえば、「データベースの検索処理を書くときは、必ずこの特定のライブラリを使う」といったルールを書いておく。するとAIは、新しい機能を実装する際にそのスキルファイルを自動で読み込み、経験豊富なシニアエンジニアのように適切な技術選定を行ってくれる。

毎回チャットで「あのライブラリを使って」と指示する必要はなくなる。公式のドキュメントや、チームで決めた最新の実装パターンをスキルファイルとして保存しておけばいい。スキルファイルは人間が読んでも勉強になるほど実践的な内容になることが多く、AIだけでなく新しくチームに入った人間のメンバーにとっても最高の手引書になる。

ステップ4: サブエージェント機能による複数ペルソナの作成

AIの壁打ち相手が常に肯定してくるイエスマンになっていないだろうか。人間同士の会議でも全員が賛成するアイデアは危険なことが多いように、全員が同じ視点で会話していると重大なリスクを見落とす危険がある。

Claude Codeのサブエージェント機能を使えば、それぞれ独立した考え方を持つ複数のペルソナを作ることができる。「.claude/agents」ディレクトリにマークダウンファイルを配置するだけで、異なる視点を持つAIを生み出せる。AIを単なるコーディングアシスタントから「思考のパートナー」に引き上げる重要なステップだ。

ここで重要なのは、単なる役割名ではなく「何を最も恐れるか（損失関数）」を明確に定義することだ。損失関数とは、AIが何を最も避けるべきかという評価基準のことだ。

たとえば、機会損失を恐れる「推進役」、技術負債を恐れる「品質役」、そして議論の前提そのものを疑う「破壊役」を作る。推進役には「デッドラインまでの残り時間」を判断基準として与え、品質役には「テストカバレッジの低下」を監視させる。そして破壊役には「そもそも全員が共有している暗黙の仮定はないか」を常に問わせる。この3つの視点を定義するだけで、AI同士が健全な対立意見を出し合い、プロジェクトのリスクを多角的に検証できるようになる。

ステップ5: カスタムスキルを活用した「AI合議システム」の実装

複数のペルソナを作ったら、次はそのペルソナたちを議論させる仕組みを作る。これが「AI合議システム」だ。合議システムを機能させるためには、各ペルソナが独立したコンテキストで思考することが不可欠だ。全員が同じ会話履歴を見ていると、どうしても前の発言に引きずられて意見が同調してしまう。

「.claude/skills/consensus/SKILL.md」というファイルを作成し、そこに合議の手順を記述する。たとえば「スラッシュコマンドの /consensus と入力されたら、推進役・品質役・破壊役の3名を呼び出し、それぞれの視点から意見を出させる」といった具合だ。各サブエージェントを個別の空間で起動し、それぞれに同じ問いを投げかける仕組みを作る。

このシステムを導入すると、何か重要な技術選定やアーキテクチャの変更を行う前に、AIたちが議論を始めてくれる。推進役が「早くリリースしよう」と言えば、品質役が「テストが足りない」と待ったをかけ、破壊役が「そもそもこの機能は本当に必要か」と根源的な問いを投げる。

それぞれの回答を持ち寄って最終的な結論を導き出すプロセスを自動化することで、まるで優秀なシニアエンジニア3人にコードレビューを依頼しているかのような体験が得られる。人間が一人で考えるよりも深く、偏りのない意思決定が可能になり、手戻りが減ってコードの堅牢性が高まるはずだ。

ファイルごとの役割比較表

ここで、エージェント開発に使う各ファイルの違いを整理しておく。

| ファイル名 / ディレクトリ | 主な役割 | 管理方法 | 更新タイミング |

| --- | --- | --- | --- |

| CLAUDE.md | 絶対的な指示書（コーディング規約など） | Gitでチーム共有 | 人間が手動で更新 |

| MEMORY.md | 学習ノート（デバッグ履歴や好み） | ローカルのみ | AIが会話から自動更新 |

| .claude/skills/ | ベストプラクティスの定義 | Gitでチーム共有 | スキル追加時に手動更新 |

| .claude/agents/ | ペルソナ（サブエージェント）の定義 | Gitでチーム共有 | ペルソナ追加時に手動更新 |

しんたろー：
サブエージェントによる合議システムは本当に強力だ。
1人で開発しているとどうしても視野が狭くなるが、破壊役のAIが「その実装方針、前提から間違ってないか」と指摘してくれる仕組みは、手戻りを防ぐうえで非常に有効だ。

つまずきポイント

初心者がエージェント開発でハマりやすい罠を3つ紹介する。

1. 1回のプロンプトに全てを詰め込む

「要件定義から実装、テストまですべてやって」と一度に頼むと、AIは確実に混乱する。タスクは小さく分割し、マークダウンの指示と固定のプログラム処理を交互に挟む「サンドイッチ構造」を意識するといい。

2. 機密情報がメモリに記録されてしまう

MEMORY.mdはAIが自動で書き込むため、APIキーやパスワードが記録されるリスクがゼロではない。定期的に「/memory」コマンドで内容を確認し、見られたくない情報は手動で削除する運用を心がけるといい。

3. ペルソナの指示が曖昧でイエスマンになる

サブエージェントを作るとき、「あなたは優秀なレビュアーだ」と書くだけでは不十分だ。「テストがないコードが世に出ることを最も恐れる」のように、損失関数（何を恐れるか）を明確に書かないと、結局あなたの意見に同調するだけのAIになってしまう。

FAQ

よくある質問に答えていく。

Q1: CLAUDE.mdとMEMORY.mdはどのように使い分ければいいか？

CLAUDE.mdは「指示書」としてGitでチーム共有し、コーディング規約やテスト方針など絶対的なルールを記述する。一方、MEMORY.mdはローカルに保存される「学習ノート」として、AIがデバッグの知見やユーザーの好みを自動で記録・参照するために使うものだ。

Q2: 機密情報がMEMORY.mdに記録されてしまわないか心配だ。

AIが会話の中から自動で判断して記録するため、APIキーやパスワードなどの機密情報が書き込まれるリスクはゼロではない。定期的に「/memory」コマンドを実行して記録内容を確認し、不要または機密性の高い情報は手動で削除する運用が有効だ。

Q3: サブエージェント（ペルソナ）を作る際、どのような指示を書けば効果的か？

単なる役割名だけでなく、「何を最も恐れるか（損失関数）」や「いつ反対意見を言うか」「何を基準に判断するか」を明確に記述することが重要だ。これにより、AIがユーザーの意見に同調するだけのイエスマンにならず、健全な対立意見を出せるようになる。

Q4: AI Skillsはどのようにインストールして使うのか？

スキルを定義したディレクトリ（たとえば「.claude/skills」）にマークダウンファイルを配置するだけで完了する。起動時に自動で読み込まれるため、チャット中に特別なコマンドで呼び出す必要はなく、自然な会話の中でAIがスキルを参照してくれる。

Q5: 複雑なタスクをAIに依頼すると、出力の品質が下がってしまう。

1回のプロンプト（指示）に多くの要件を詰め込むと、LLMの推論品質が低下しやすくなる。タスクを「抽出」と「評価」のように複数のステップに分割し、マークダウンの指示と固定の処理を交互に挟む「サンドイッチ構造」で設計すると動作が安定するはずだ。

まとめ

Claude Codeを使ったAIエージェント開発は、決して難しくない。マークダウンファイルで自然言語のルールを定義するだけで、専用の優秀な開発チームを作り上げることができる。

まずはプロジェクトのルートディレクトリに「CLAUDE.md」を置き、基本的なルールを書くところから始めるといい。そして「/memory」コマンドでAIの自動学習を体験してみるといい。AIに適切なペルソナとルールを与えれば、1人開発でも多角的な視点を持った強力なチームを手に入れられる。

👉 ThreadPostでSNS運用を自動化する