TL;DR
- エージェントが迷う原因は「地図の欠如」。
.agents/ディレクトリに憲法・原則・DoDを集約するだけで、自律性と安全性が両立する。 - プロンプトは使い捨てにせず
plans/にMarkdownで蓄積する。エージェントは過去の計画を参照でき、人間は「なぜこの実装になったか」を後から追える。 - 既存のCLI（例:
pnpm gen）を "Skill" としてラップすると、エージェントは自然言語の指示だけでツールを自分の手足のように使いこなす。 - このリポジトリ自体が実例。企画→執筆→レビューを複数エージェントが並列で回し、人間は最後の承認（Merge）だけを担当する構成になっている。
こんにちは、みねです。
第1回（自動化戦略）、第2回（思考転換）に続き、今回はシリーズ完結編として**「具体的な実装パターン」**を解説します。
「エージェントに任せたいけど、リポジトリをどう整えればいいかわからない」というエンジニアのために、私が実際に notionnext-blog で採用しているディレクトリ構成と運用ルールを公開します。Skill の設計思想についてはエージェントスキルの定義方法とAgent Skill Hub 構想も併せて参照すると、本記事のパターンがより立体的に理解できるはずです。
1. エージェントが迷わない「地図」を作る (Directory Structure)
エージェントが迷う最大の原因は「どこを見ればいいかわからない」ことです。これを防ぐために、物理的な配置で役割を定義します。
憲法を守る砦 .agents/
.agents ディレクトリを作り、ここに「絶対的なルール」を集約します。
.agents/
├─ RULES.md # エージェントへの禁止事項（node_modules触るな、等）
├─ PRINCIPLES.md # プロジェクトの思想（品質基準、SEO方針）
└─ DEFINITIONS.md # 完了の定義 (Definition of Done)
これを置くだけで、AntigravityやCursorのエージェントは「あ、自分はこの憲法に従えばいいんだ」と理解し、暴走を防ぐガードレールが機能し始めます。リポジトリ全体を「AIが読みやすい」状態に整えるという発想については、AI-Legible リポジトリ設計論でより体系的に掘り下げています。
戦術を集める plans/
エージェントへの指示（Prompt）をその場限りのチャットで終わらせず、plans/ ディレクトリにMarkdownとして保存します。
- 良い点：エージェントが「前回の計画」を参照して自律的に動ける。
- 良い点：人間が後から「なぜこの実装にしたか」を追える。
- 良い点：PRレビュー時に「計画 → 実装 → レビュー」の因果を辿れる。
2. エージェントに道具を渡す (Skill Definition)
エージェントは何でもできるわけではありません。「何をしていいか」を定義した道具（Skill）が必要です。
Scripts as Skills
例えば、pnpm gen というコマンドがあるなら、それを「記事の骨子を作るスキル」としてエージェントに認識させます。
「新しい記事を書きたい」と言われたら、まずは
pnpm genを実行してJSONを得ること。
このように自然言語でラップしてあげるだけで、エージェントはCLIツールを「自分の手足」として使いこなします。pnpm に統一するのはパッケージマネージャー混在による lockfile 破壊や CI 失敗を避けるためで、エージェントに触らせるコマンドほど規約の一貫性が重要になります。
3. 【実践】記事自動生成システムの裏側公開
本ブログの自動運用も、実はこのパターンで動いています。
- User: 「自動化の記事書きたい」と投げる。
- Plan Agent:
.agents/PRINCIPLES.mdを読み、「一次情報が必要ですね」と判断して構成案を作成。 - Writer Agent:
plans/の構成案に従い執筆。 - Review Agent:
.agents/DEFINITIONS.mdのDoD（完了条件）に基づき、SEOや誤字をチェック。
これらが、私がコーヒーを飲んでいる間に並行して行われます。私がやるのは、最後の「承認ボタン（Merge）」を押すことだけです。
4. まとめ：あなたのリポジトリをエージェントの「住処」にする
エージェントエンジニアリングとは、「人間が読みやすいコード」を書くことから、「エージェントが動きやすい環境」を作ることへのシフトです。
まずは .agents/RULES.md を1つ作ることから始めてみてください。あなたのリポジトリが、単なるコード置き場から、エージェントたちが生き生きと働く「オフィス」へと変わるはずです。
このシリーズ記事（全3回）は、マルチエージェントシステムによって企画・執筆・レビューされました。
