※本記事は個人の自己研鑽として取り組んだ内容であり、所属組織の公式見解や業務事例ではありません。
こんにちは。Lamb です。
CodexやAIで同じ説明を何度も書いているなら、そろそろプロンプトの外に置く頃かもしれません。
AIやCodexを使い続けていると、同じ前提を何度も説明する場面が増えてきます。
ファイル名、変更範囲、参照するルール。書き忘れると、成果物にも小さなずれが出ます。
そこで役立ったのが、リポジトリ全体の作業ルールをまとめる AGENTS.md でした。
この記事では、Skillsとの役割分担や、運用して分かった注意点を実務目線で整理します。
Codexを使っていると、だんだん同じ説明を何度も書いていることに気づきます。
「このファイルは変更しないでほしい」
「記事本文はこの形式で作ってほしい」
「レビューするときは、この観点を確認してほしい」
最初のうちは、その都度プロンプトに書けば済みます。
ただ、作業が増えるほど説明も長くなり、書き忘れや認識のずれが起きやすくなりました。
そこで作ったのが、リポジトリ全体の作業ルールをまとめる AGENTS.md です。
実際に運用してみると、毎回の説明を減らせただけではありませんでした。Codexに何を任せ、どこを人が確認するのかを整理するきっかけにもなりました。
ここからは、ある記事制作・ドキュメント管理プロジェクトを例に、AGENTS.md を作ってよかったことと、運用して分かった注意点をまとめます。
☑️ AGENTS.mdを作る前に困っていたこと
AGENTS.md を作る前は、依頼するたびに前提が少しずつ変わっていました。
たとえば、こんな場面です。
- ファイル名の付け方が作業ごとに変わる
- 下書きと公開用成果物の役割が曖昧になる
- 記事本文が、読者向けではなく設計メモのようになる
- 更新対象が複数あると、一部だけ反映が漏れる
- 毎回、参照してほしいルールを説明する必要がある
ひとつずつは小さな問題です。
ただ、確認と手直しが積み重なると、AIに任せたことで本当に作業が楽になったのか分からなくなります。
このとき感じたのは、プロンプトの書き方だけでは解決しにくいということでした。
依頼文を毎回工夫するより、変わりにくい前提をリポジトリ側に置いたほうが管理しやすい。そう考えて、共通ルールを AGENTS.md にまとめました。
☑️ AGENTS.mdに書いて役立ったこと
最初から細かい手順をすべて書いたわけではありません。
まず整理したのは、次のような内容です。
| 項目 | 書いたこと |
|---|---|
| プロジェクトの目的 | 何を作るリポジトリなのか |
| 共通ルール | 文体、用語、事実確認などの基本方針 |
| 作業の流れ | 入力から成果物までの大まかな順序 |
| 参照先 | 作業ごとに確認するSkills |
| 命名規則 | ファイルやディレクトリの付け方 |
| 禁止事項 | 勝手に補完しない情報や変更してはいけない範囲 |
特に役立ったのは、「作業ごとに何を参照するか」を決めたことです。
記事本文を作るとき、公開前にレビューするとき、投稿用の補助情報を用意するときでは、確認すべき内容が違います。
その入口を AGENTS.md に置いたことで、依頼のたびに詳しい前提を並べなくても、Codexが参照すべきルールをたどりやすくなりました。
人が見ても、プロジェクトの全体像を把握しやすくなります。AI向けに書いたつもりでも、結果的には運用ルールの棚卸しにもなりました。
☑️ AGENTS.mdとSkillsの役割分担
運用してみて迷ったのが、AGENTS.md にどこまで書くかでした。
全部を1ファイルに詰め込むと、長くなりすぎます。ルールを探しにくくなり、更新する場所も分かりづらくなります。
そこで、次のように分けました。
-
AGENTS.md: プロジェクト全体の目的、基本ルール、作業別の参照先 - Skills: 記事作成、レビュー、投稿準備など、個別作業の詳しい進め方
感覚としては、AGENTS.md が案内板で、Skillsが作業別の手順書です。
たとえば、AGENTS.md には「記事本文を作るときは編集用Skillを参照する」と書きます。本文の構成、避けたい表現、確認項目まではSkill側に置きます。
この分け方にすると、全体ルールを確認したいときと、具体的な作業手順を確認したいときで見る場所がはっきりします。
同じ説明を複数のファイルへ重ねて書かないことも大切です。重複が増えると、片方だけ更新して内容が食い違いやすくなります。
☑️ 運用して分かった注意点
AGENTS.md を作れば、Codexの出力がすべて安定するわけではありません。
実際に使って分かったのは、ルールを置くことと、ルールどおりにできているか確認することは別だという点です。
最低限、次のような確認は残ります。
- 指定したSkillを参照しているか
- 変更してよい範囲を守っているか
- ファイル名や出力先が合っているか
- 本文が内部資料のような書き方になっていないか
- 事実と推測が混ざっていないか
- 機密情報や社外秘情報につながる内容が含まれていないか
また、プロジェクトの運用が変わったら、AGENTS.md も更新する必要があります。
命名規則や作業フローを変えたのに古い説明が残っていると、Codexはその古いルールを参照する可能性があります。ルールがあることで安心してしまい、更新漏れに気づきにくくなる点には注意が必要です。
個人的には、AGENTS.md を完成品として扱わないほうが運用しやすいと感じています。
作業中に同じ修正が続いたら、共通ルールへ追加できないか考える。細かくなりすぎたらSkillへ分ける。使わなくなったルールは整理する。
このくらいの温度感で、実際の作業に合わせて育てていくのがよさそうです。
☑️ AGENTS.mdを作るなら、最初に何を書くか
これから作るなら、最初から大きなルール集にする必要はありません。
まずは、次の項目から始めると整理しやすいです。
- リポジトリの目的
- 主な入力と成果物
- 変更してよい範囲、変更しない範囲
- ファイルやディレクトリの命名規則
- 作業ごとに参照するルール
- 完了時に確認すること
- やってはいけないこと
なかでも、Codexに推測で補ってほしくない内容は先に書いておきたいところです。
存在しない事例や数値、確認できていないURL、機密情報に関わる推測などは、生成後の文章に自然に混ざると見落としやすくなります。
「何をしてほしいか」だけでなく、「何をしてほしくないか」も明記する。これは、AIエージェントへ作業を任せるうえで大事な運用設計だと思います。
☑️ まとめ
Codex運用で AGENTS.md を作ってよかったのは、毎回のプロンプトを短くできたことだけではありません。
プロジェクトの目的や作業ルールを整理し、AIと人が同じ前提を確認できる場所を作れたことが大きかったです。
今回のポイントをまとめます。
- 変わりにくい前提は、毎回のプロンプトではなくリポジトリ側に置く
-
AGENTS.mdは全体ルールと参照先を示す入口にする - 詳しい手順は作業別のSkillsへ分ける
- ルールを書いて終わりにせず、人によるレビューを残す
- 運用の変化に合わせて内容も更新する
AIエージェントを使うときは、よいプロンプトを考えることに目が向きがちです。
ただ、繰り返し使うなら、AIが迷いにくい作業環境をどう作るかも同じくらい大切です。AGENTS.md は、その最初の一歩として扱いやすい仕組みでした。
💕 CTA
この記事が参考になったら、いいね してもらえると嬉しいです。
今後も、現役インフラエンジニア目線で、AWS・設計・運用改善・PM・AI活用について整理していきます。
こちら のnoteでも情報発信しています。興味があればぜひ覗いていただけますと幸いです。