AGENTS.mdを作り、AIへ毎回同じ説明をしなくてよくなった

依頼文が記事より長くなり始めた

第21回では、ChatGPT、Codex、人の役割を分けた流れをまとめました。運用を続けると、別の問題が出てきました。

Codexへ記事を追加してもらうたびに、「既存記事を読む」「本文は体験を優先する」「タイトルやslugを勝手に変えない」「note用Markdownも生成する」「最後にnpm.cmd run checkを実行する」と説明していました。

どれも必要な条件ですが、毎回の依頼へ並べると、今回実際に行ったAWS作業や記事固有の注意点が見つけにくくなります。同じ文章を貼り直しながら、これをリポジトリ側へ置けないかと考えました。

AGENTS.mdは、Codexがリポジトリで作業する時に読む指示ファイルです。SAMEKORO LABでは、ルートとcontent/articlesの二か所に分けました。

ルートのAGENTS.mdには、プロジェクト全体へ関わる内容を置きます。

content/articles/AGENTS.mdには、記事制作へ固有の内容を置きます。

一つのファイルへ全部書かず、適用される場所に合わせて役割を分けました。

AGENTS.mdを作ったあとも、依頼文が不要になったわけではありません。今回のAWS作業で確認できたこと、正式タイトル、記事で扱わない範囲、公開状態などは、記事ごとに変わります。

そこで、毎回変わらないルールはAGENTS.md、今回だけの事実と判断は依頼文へ残しました。

この区別がないと、記事固有の内容までルールとして固定したり、逆に重要な共通ルールを毎回書き忘れたりします。ファイルを作ることより、どちらへ置く情報かを決めるほうが大切でした。

シリーズが増えるほど、同じAWSサービスの説明をもう一度書きやすくなります。CloudFront、S3、Route 53、IAM Identity Centerなどは、一度説明した内容を毎回繰り返すと、構築記ではなくサービス解説へ戻ってしまいます。

そのため新しい記事の前に、content/articles配下の公開済み記事を読み直すルールを置きました。

確認するのは文章の雰囲気だけではありません。今回の内容が既出でないか、前回から自然につながるか、過去記事へのリンクで省略できる説明はないかを見ます。

AIへ「同じ文体で」とだけ伝えるより、実際の原本を読み直してもらうほうが、シリーズの流れを保ちやすくなりました。

困るたびにAGENTS.mdへ一文を足すと、今度は長すぎて判断しにくいファイルになります。今回の記事だけの例外や、すでにビルドで検証できる細かな条件まで文章で重ねる必要はありません。

人が読むルール、Codexが作業前に判断するルール、自動検証で守るルールを分けました。たとえばリンク切れやH1の数はnpm.cmd run checkで確認し、なぜ体験を優先するかはAGENTS.mdへ残します。

ルールとテストを同じ内容で増やし続けるのではなく、それぞれが得意な役割を持たせました。

企業では、コーディング規約、執筆ガイド、レビュー基準を文書化し、担当者が変わっても同じ品質を保ちます。個人リポジトリなら自分が覚えていればよいと思っていました。

しかしAIと一緒に作業する場合、別の会話でも同じ前提を共有する必要があります。AGENTS.mdは、将来の自分とAIのための小さな引き継ぎ書になりました。

毎回の説明が短くなったことで、今回は何を確認し、どこまで実施したかという本題へ時間を使えます。

ルートのAGENTS.mdへプロジェクト全体のルール、content/articles/AGENTS.mdへ記事制作のルールを置き、毎回変わる事実は依頼文へ残しました。

AIへ説明しなくてよくなったのではなく、同じ説明を信頼できる場所へ一度書き、毎回は差分だけを伝えられるようになったということです。

第23回では、この個人環境で続けてきたガバナンスの取り組みを、企業のCCoEと同じだと決めつけず、違いを実際の経験から整理する予定です。