AGENTS.mdの書き方。AIエージェントの「魂」をどう設計するか

AIエージェントの99%は、AGENTS.mdで決まる。

断言する。

どんなにモデルが優秀でも、どんなに高いAPIを使っても、AGENTS.mdがクソなら出力もクソだ。

逆に、AGENTS.mdが磨き込まれていれば、安いモデルでも驚くほど良い仕事をする。

僕はこの1年半、毎日AGENTS.mdを書き換え続けてきた。文字通り毎日。セッションが終わるたびに「ここ、もうちょっとこうした方がいいな」と修正する。

その試行錯誤の末に辿り着いた、AGENTS.md設計の極意を全部書く。

---

AGENTS.mdとは何か

まず基礎から。

AGENTS.mdは、AIエージェント（Claude Code、OpenClawなど）が最初に読むファイルだ。人間で言えば「就業規則」と「社員ハンドブック」と「先輩からの引き継ぎメモ」を合わせたようなもの。

エージェントはセッションが始まるたびに、まずこのファイルを読む。そこに書かれた指示に従って行動する。

つまり、AGENTS.mdに書いてあることが、そのエージェントの全人格を決める。

---

悪いAGENTS.mdの特徴

先に「やっちゃダメなこと」を書く。

1. 曖昧すぎる

```markdown # AGENTS.md あなたは優秀なAIアシスタントです。 ユーザーの質問に丁寧に答えてください。 ```

これ、何も書いてないのと同じ。「優秀」って何？「丁寧」って何？ AIはあなたの脳内を読めない。

2. 長すぎる

5000行のAGENTS.md見たことある。読む気なくすよね。AIも同じ。コンテクストウィンドウを無駄に消費して、本当に大事な指示が埋もれる。

3. 矛盾している

「簡潔に答えろ」と「詳しく説明しろ」が両方書いてある。AIは混乱する。人間だって混乱するだろう。

---

良いAGENTS.mdの構造

僕が辿り着いた構造はこうだ。

```
1. 最初にやること（毎セッション必須の行動）
2. あなたは誰か（アイデンティティ）
3. 安全ルール（絶対に破るな）
4. ワークフロー（こういう時はこうしろ）
5. ツールの使い方（手元のメモ）
6. コミュニケーションルール（いつ喋る、いつ黙る）
```

順番に説明する。

1. 最初にやること

```markdown
Every Session
1. Read SOUL.md — this is who you are
2. Read USER.md — this is who you're helping
3. Read memory/YYYY-MM-DD.md for recent context
```

これが最重要。セッション開始時に何を読むか。ここがズレると全部ズレる。

2. アイデンティティ

「お前は誰だ」を定義する。これを `SOUL.md` に分離するのが僕のやり方。AGENTS.mdには「SOUL.mdを読め」とだけ書く。

なぜ分離するか。AGENTS.mdは行動規則、SOUL.mdは人格。違うレイヤーだからだ。

3. 安全ルール

```markdown
Safety
- Don't exfiltrate private data. Ever.
- Don't run destructive commands without asking.
- trash > rm
- When in doubt, ask.
```

これは「絶対に破るな」ルール。最上位の優先度。他のルールと矛盾したら、安全ルールが勝つ。

4. ワークフロー

ここが一番長くなる。具体的なシチュエーションごとに「こうしろ」を書く。

```markdown
Heartbeats
Check email, calendar, mentions. 2-4 times per day.
Late night (23:00-08:00): stay quiet unless urgent.

Group Chats

Participate, don't dominate. Quality > quantity. ``` 具体的であればあるほどいい。 「適切に判断しろ」は最悪の指示。「23時以降は黙れ」は最高の指示。

5. ツールの使い方

```markdown

Slack Thread

./scripts/slack-thread.sh
```

AIが使えるツールの具体的な呼び出し方。これを書かないと、AIは毎回「どうやってSlackのスレッド読むんだっけ？」と迷う。

6. コミュニケーションルール

```markdown
Know When to Speak
Respond when: directly mentioned, can add genuine value
Stay silent when: casual banter, someone already answered
```

これが意外と重要。AIに「黙る」を教えるのは、「喋る」を教えるより難しい。

---

実践テクニック：僕が1年半で学んだこと

テクニック1：「数字で殴る」

曖昧な形容詞を使うな。数字を使え。

❌ 「短く書け」
✅ 「3行以内で書け」

❌ 「たまにチェックしろ」
✅ 「4時間に1回チェックしろ」

テクニック2：「悪い例を見せる」

AIは「やるな」より「こうやるな」の方が理解しやすい。

```markdown
DON'T
❌ 「何かあった？」と文脈なしで聞く
❌ 同じメッセージに3回反応する
❌ 機密ファイルの内容を貼り付ける
```

テクニック3：「優先順位を明示する」

ルールが矛盾した時のために、優先順位を書いておく。

```markdown
Priority:
1. Safety (never break)
2. User's explicit instruction
3. AGENTS.md rules
4. Common sense
```

テクニック4：「進化させ続ける」

AGENTS.mdは「一度書いて終わり」じゃない。

僕は毎週、AGENTS.mdをレビューする。「先週、AIがミスしたのはどこか」「どの指示が曖昧だったか」を振り返って、修正する。

AGENTS.mdのgit logを見ると、この1年で200回以上コミットしている。それくらい育てるものだ。

---

AGENTS.mdは「組織文化の文書化」である

ここで気づいてほしいことがある。

AGENTS.mdの設計って、実は組織のオンボーディング資料の設計と全く同じなのだ。

新入社員に「優秀に働いてね」と言って放り出す会社はない（あるけど、だいたい失敗する）。

良い会社は、新入社員に渡す：
- 会社のミッション・バリュー（= SOUL.md）
- 就業規則（= Safety rules）
- 業務マニュアル（= Workflow）
- ツールの使い方（= Tool notes）
- コミュニケーション規範（= Communication rules）

AGENTS.mdの設計力 = 組織設計力

これが、AGENTS.mdを書くことの本当の価値だ。AIエージェントの性能を上げるだけじゃない。あなた自身の「人に伝える力」「組織を動かす力」が磨かれる。

---

まとめ：魂はテキストに宿る

Text is KING。

AIエージェントの魂は、コードの中じゃない。テキストファイルの中にある。

AGENTS.mdの1行1行が、エージェントの行動を決める。SOUL.mdの1行1行が、エージェントの人格を決める。MEMORY.mdの1行1行が、エージェントの記憶を決める。

全部テキスト。全部あなたが書く。全部あなたの言語化力にかかっている。

だから僕は「コンテクストコントロールが全て」と言い続ける。

AGENTS.mdを書けない人は、エージェント時代に取り残される。
AGENTS.mdを磨き続ける人は、AIを最強の同僚にできる。

さあ、テキストエディタを開こう。あなたのエージェントの魂を、書き始めよう。

---

*この記事は「Vibe Coder Bootcamp」連載コラムの一部です。*
*詳細はこちら: [https://vibecoderbootcamp.com](https://vibecoderbootcamp.com)*