AGENTS.md / CLAUDE.mdに何を書くべきか: AIエージェント用ルールの最小形

AIエージェントの精度を上げる一番地味で効く方法は、毎回チャットで説明していることをリポジトリに書くことです。Claude Codeのドキュメントでは、CLAUDE.md は永続的な指示、auto memory はエージェントが学習したメモとして整理されています。OpenAIのAgents SDK発表でも、AGENTS.md がエージェントシステムの共通プリミティブの一つとして扱われています。

書くべきこと

最初に書くのは、抽象的な思想ではなく、作業に直結する制約です。

# Agent Instructions

## Commands
- Build: npm run build
- Lint: npm run lint
- Test: npm test

## Edit scope
- Source files: src/
- Do not edit: dist/, node_modules/, generated files

## Workflow
- Inspect relevant files before editing.
- Keep changes scoped to the requested task.
- Run the narrowest useful verification before reporting done.

## Safety
- Do not publish, deploy, or send external requests without explicit approval.
- Do not print secrets, tokens, cookies, or private customer data.

この程度でも、毎回のやり取りがかなり安定します。

書かない方がいいこと

長すぎるルールは、読まれないだけでなく、矛盾します。

• 気分や価値観だけの文章
• たまにしか使わない手順
• 古いコマンド
• 例外だらけの禁止リスト
• 特定の会話でしか必要ない背景

Claude Codeのドキュメントでも、具体的で簡潔な指示ほど従われやすいと説明されています。多段の手順や一部ディレクトリだけに関係するルールは、path-scoped rule や skill に分ける方が運用しやすいです。

更新タイミング

ルールファイルは、最初に完璧に書くものではありません。更新タイミングを決めておく方が効きます。

• エージェントが同じミスを2回した
• レビューで「知っているべきだった」指摘が出た
• 毎回同じ確認コマンドを教えている
• 新しいメンバーにも必要な文脈がある

AIエージェント用のルールは、READMEより運用に近く、CI設定より柔らかい位置にあります。短く、事実ベースで、検証可能に保つのがコツです。

出典

• Claude Code Docs: How Claude remembers your project
• OpenAI: The next evolution of the Agents SDK