AIコーディングでAGENTS.mdを書いたら何が変わるか｜毎回の指示を減らす設計

AIコーディングを続けていると、毎回同じ前提を説明していることに気づきました。命名規則、レビュー観点、禁止事項、どこまで触ってよいか、最後に何を確認するか。作業のたびに言っているつもりでも、少しずつ抜けます。

最初は、その都度伝えれば十分だと思っていました。でも会話が長くなるほど、前に伝えた条件が薄くなったり、別の作業の文脈に引っ張られたりします。AIだけでなく、自分のほうも「今回は何を守るんだっけ」と迷うことがありました。

そこで効いたのが、AGENTS.mdのような運用前提を会話の外に置くことでした。毎回うまく頼むのではなく、毎回見返す土台を作る。今回は、AGENTS.mdを書いたことで何が変わったのかを、実務寄りの感覚で整理します。

毎回の指示が減るより、毎回のズレが減ったことが大きい

AGENTS.mdを書いて最初に感じたのは、省力化より整合性でした。同じことを何度も言わなくて済むのも助かりますが、それ以上に「言ったつもり」のズレが減ります。

AIに作業を頼むとき、毎回の依頼文だけで全ての前提を渡そうとすると、どうしても漏れます。たとえば「このファイルを直して」と頼んだだけでは、どこまで触ってよいか、既存の変更を戻してはいけないか、テストをどう扱うかまでは伝わりません。

AIエージェントの土台の話として見るなら、こちらの記事ともつながります。

少し任せる範囲を増やすほど、毎回の頼み方だけに頼るのは不安定になります。AGENTS.mdがあると、作業ごとの依頼文は短くても、背後にある判断基準をそろえやすくなります。

私にとってAGENTS.mdは、AIに細かい命令を押し込む場所ではなく、作業の前提を固定しておく場所でした。この見方に変えると、指示文を毎回がんばる負担が少し軽くなりました。

特に効いたのは、やってよいことと止めたいことを先に分けられる点

AIに任せる作業で怖いのは、作業できないことより、作業しすぎることです。良かれと思って関係ないファイルまで整える。文章の意味を変えてまで条件を満たそうとする。公開や削除に近い操作まで進めてしまう。こういうズレは、最初に境界線を出しておかないと起きやすくなります。

AGENTS.mdには、実装方針や文章トーンだけでなく、触ってよい範囲、やってほしくない操作、レビューの優先順位まで書けます。これはAIの自由度を奪うためではなく、安心して任せる範囲を決めるためのものです。

• 既存の変更を勝手に戻さない
• 公開、削除、収益導線の変更は確認なしに実行しない
• 本文では保存条件より文章の自然さを優先する
• テストや検証ができなかった場合は、できなかったことを明記する

こういう前提があるだけで、作業後の確認も変わります。全部をゼロから疑うのではなく、決めた境界線から外れていないかを見ればよくなります。

共通ルールを会話の外に出すと、長い作業でも前提が薄まりにくい

長い作業では、最初に伝えた条件がだんだん薄くなります。これはAIの問題だけではなく、人間側も同じです。最初は大事にしていた条件を、途中の修正や確認に追われるうちに忘れてしまうことがあります。

AGENTS.mdがあると、共通ルールを会話の流れに埋もれさせず、必要なときに戻れる場所として扱えます。今回のように文章のつながりや意味の分かりやすさを重視したい場合も、ルールとして外に出しておくことで、作業の途中で見失いにくくなります。

コンテキスト管理の観点でも、共通ルールを会話の外に出す意味は大きいです。

何でも会話に詰め込むと、長い作業ほど文脈が重くなります。逆に、繰り返し使う前提をファイルに分けておくと、依頼ごとには今回必要なことだけを渡しやすくなります。

これは記事制作でも同じでした。本文の自然さ、マーカーの扱い、公開前の確認順序を毎回その場で説明していると、どこかで抜けます。外に置いたルールへ戻れるだけで、作業の途中で優先順位を立て直しやすくなりました。

AGENTS.mdがあると、AIの問題と運用の問題を切り分けやすい

うまくいかないとき、以前の私はモデルの性能だけを疑いがちでした。でも、ルールが曖昧なままなら、どのAIを使っても似た崩れ方をします。AIが悪いのか、渡した前提が足りないのかを分けられないまま、同じ修正を繰り返してしまいます。

AGENTS.mdのような共通ルールがあると、失敗の原因を見直しやすくなります。ルールに書いてあるのに守られなかったのか。そもそもルールに書いていなかったのか。書き方が抽象的すぎたのか。この切り分けができるだけでも、次の改善につながります。

今回の記事改善でいえば、「品質条件を満たして保存する」ことが目的になりすぎると、本文の意味やつながりが壊れることがありました。これは単なる執筆ミスではなく、運用ルールの優先順位が弱かった問題でもあります。

AGENTS.mdは、失敗を責めるためのものではなく、次に同じ崩れ方をしないための記録場所です。ここに原因を戻せると、会話だけで反省して終わるよりも、次の作業に残りやすくなります。

共通ルールと案件固有ルールを分けると、運用しやすくなる

AGENTS.mdに何でも書き込むと、今度は読みづらくなります。私が整理したいと思っているのは、共通ルールと案件固有ルールの分け方です。毎回守ることと、今回だけの条件を混ぜすぎると、結局どこを見ればよいか分からなくなります。

共通ルールには、勝手に戻さない、公開しない、本文の意味を優先する、検証結果を明記する、といった毎回の土台を書きます。案件固有ルールには、この記事ではマーカーを戻す、この機能ではこのファイルだけ触る、このシリーズでは投資助言に見える表現を避ける、のような一時的な条件を書きます。

この分け方ができると、AIへの依頼も短くなります。「共通ルールはAGENTS.mdに従う。今回だけの条件はこれです」と言えるからです。毎回長い前提を書かなくても、必要な差分だけを渡せます。

ただし、ファイルに書いたから完璧というわけではありません。実際の作業でズレたら、ルールの書き方が弱いのか、運用の確認が足りないのかを見直す必要があります。

頼み方を毎回がんばるより、土台を育てるほうが続けやすい

私は以前、毎回うまくプロンプトを書くことに意識が寄りすぎていました。もちろん依頼文は大事です。でも、長く使うなら、頼み方そのものを仕組みに寄せたほうが安定します。

AGENTS.mdの価値は、一度きれいに書くことではなく、作業で見つかった失敗や違和感を次のルールに戻せることです。文章が分かりにくくなったなら、文章のつながりを確認するルールを足す。装飾で本文が変わったなら、マーカーは既存文の強調に限定すると書く。こうして少しずつ育てていくものだと思っています。

次に試したいのは、共通ルールを増やしすぎず、実際に使う頻度が高いものだけを残すことです。ルールが多すぎると、守る側も読む側も疲れます。大事なのは、作業の迷いを減らすことなので、書けば書くほど良いわけではありません。

AGENTS.mdは派手な改善ではありませんが、AIコーディングや記事制作を続けるほど効いてくる土台です。毎回の工夫を一回きりで流さず、次の作業に残す。そのための場所として、これからも更新していきたいです。ルールは増やすより、次の作業で本当に使える形に育てたいです。次回の自分が迷わないためにも。