この半年のClaude Code / Codex の大幅な自律性強化によって、今までのCLAUDE.md AGENTS.md をはじめとしたドキュメントの、本当に良い書き方が全然変わってきています
以下の記事が非常に参考になりますが
すべてこのやり方でやると、物によっては問題が起きやすくなるドキュメントにもなりうるなと思いました
ドキュメントは以下のように分類してまとめるのが良いと思いました
先にCLAUDE.md / AGENTS.md に書くならこんな感じで
# ドキュメント方針
原則: 導出できるものはインターフェースを示して考えさせ、導出できないものは網羅する
- 書く前に種別を判断する
- 使い方系（README・使い方ガイド）: インターフェースが主。サンプルよりインターフェース
- ワークフロー系（ランブック・手順書）: 決まった手順を決まった順番で網羅する。決定論的に駆動できるようにする
- リファレンス系（仕様書・ユビキタス言語・一覧）: grepで引っかかるように省略せず網羅する
ドキュメントの3分類
使い方系（usage / how-to）
- 例: 社内ライブラリのREADME、SDKやCLIツールの使い方
サンプルよりインターフェースを書かせる
シグネチャ・引数・戻り値・制約が明確なら、使い方は読者が自分で導出できる
サンプルを書くと、前述の記事の通りAIエージェント探索を狭めてしまい、性能を落としてしまう
ワークフロー系（ランブック）
- 例: リリース手順、障害対応、開発環境の構築手順、DBマイグレーション手順
決まった手順を決まった順番で決定論的に守らせたい
創意工夫のいらない部分
徹底して同じ手順を守らせる
リファレンス系
例: 画面仕様書、ユビキタス言語、環境変数一覧、DB仕様
grepで引っかかるように網羅しておくことが大事
根っこにある原則
導出できるものはインターフェースを渡して考えさせ、導出できないものは網羅して渡す。
使い方はインターフェースから導出できるので、サンプルで埋めると思考停止を招く
手順や事実は導出できないので、省略した分だけエージェントが勝手に補完して事故る
「エージェントに考えさせたいか、考えさせたくないか」がドキュメントの書き分け基準になる