なぜ開発者はAGENTS.mdを書くのか。Claude CodeでAIに規律を守らせるガイド

SNS運用を自動化しませんか？

ThreadPostなら、投稿作成・画像生成・スケジュール管理までAIがサポート。

無料で始める

AIがコードを書く時代から、AIに「規律」を守らせる時代へ

AIがコードを書く作業は日常化した。

Claude Codeを実行すれば、数秒でコンポーネントが生成される。

勝手に新しいライブラリがインストールされる。

既存の命名規則が無視され、独自の変数名が付けられる。

共通化されていた関数がコピペで書き直される。

AI駆動開発を行う開発者が直面する事象だ。

AGENTS.mdというファイルがある。

このファイルはAIの振る舞いを制御する。

AIに明確な制約を与える。

しんたろー：
AIのコード生成能力には慣れた。
100行のコードを書くことより、1つの規律をAIに守らせる方が難易度が高い。
1人SaaS開発において、この制御は避けて通れない。

※この記事は、Claude Codeで1人SaaS開発を行うしんたろーが、AI活用Tipsを解説する記事だ。

AIエージェントの自律性を制御する「メタデータ層」

AI駆動開発のトレンドは変化している。

リポジトリ内にAGENTS.mdやPLAN.mdを配置する手法が主流だ。

これはAIが作業前に読み込む「メタデータ層」だ。

AIは個別のファイル修正は行うが、プロジェクト全体の暗黙のルールを読み取ることは困難だ。

リポジトリのルートにAI専用の指示書を配置する。

構造化して記述する項目は以下の通りだ。

* プロジェクトの目的: 誰が使う何を作っているか

* 自律判断のルール: AIが判断していい範囲

* 人間確認の条件: コスト、セキュリティ、外部通信のトリガー

* 技術スタックの制約: 使用を許可するライブラリと禁止事項

* Doneの定義: タスク完了の基準

検証プロジェクトでは、あえてAIに「実装するな」と指示を出した。

AGENTS.mdを読み、文脈を理解しているかを確認するためだ。

AIは「これはアプリ開発ではなく、自律性を高めるための実験（ハーネス設計）だ」と認識した。

導入コストは0ドルだ。

AGENTS.mdの作成には10分を要する。

開発の安全性は向上する。

しんたろー：
開発者の仕事はコードを書くことから、AIが動く環境を設計することに変化した。
抽象度が高い作業だ。
最初は手間だが、一度「檻」を作ればAIは規律に従う。

Claude Codeで実感する「事前制約」の効果

Claude Codeはリポジトリ全体のファイルをスキャンする能力を持つ。

AGENTS.mdとの相性は高い。

ログイン画面のUI改善をAIに依頼した際、共通バリデーションが消去され、独自のロジックが埋め込まれる事象が発生した。

AGENTS.mdに「共通ディレクトリにある関数は必ず再利用せよ」と記述した。

以降、Claude Codeはファイルを書き換える前に「共通関数を探す」ステップを自律的に踏むようになった。

Linterや静的解析ツールは「事後」に間違いを検知する。

AI駆動開発では、AIがコードを生成する「前」に思考の枠組みを固定する。

AGENTS.mdによる事前制約と、Linterによる事後検証を組み合わせる。

ThreadPostの開発では、このフローの導入によりデバッグ時間が70%減少した。

しんたろー：
Claude Codeへの修正依頼回数が減った。
AIに文句を言う前に、自分がルールを明文化できていたかを確認するようになった。
AIのミスは設計のミスだと感じる。

ここまで読んだあなたに

今なら無料で全機能をお試しいただけます。設定後はAIが投稿案を毎日生成。確認して選ぶだけ。

無料で始める

具体的なアクションプラン

リポジトリのルートにAGENTS.mdを作成する。

以下の5つのセクションで構成する。

Context: プロジェクトの課題
Tech Stack: 言語、フレームワーク、DB、デプロイ先
Governance: 触れてはいけないファイルやディレクトリ
Intervention Policy: 人間に確認を求める条件
Coding Standards: 命名規則、テスト、コメントの書き方

PLAN.mdを活用する。

AIに実装を依頼する前に、PLAN.mdを更新させ、手順を宣言させる。

人間がプランをレビューし、承認後に実装を開始する。

非エンジニアがチームにいる場合、エンジニアがAGENTS.mdをメンテナンスし、非エンジニアはそのルールの上でAIに指示を出す。

設定済みのコンテナや設定ファイルを配布する。

開発者の価値は、AIがミスをしない環境を設計することにシフトしている。

コードを書く手を止め、ドキュメントを書くことが、結果としてコードを完成させる道だ。

しんたろー：
ドキュメントが重要という結論に至る。
読み手が人間からAIに変わった。
AI向けに書くドキュメントは、曖昧さが許されない。

AI活用に関するよくある質問（FAQ）

Q1: AIにコードを書かせると規律が乱れます。どう防げばいいですか？

リポジトリ内にAGENTS.mdやPLAN.mdを作成し、ルールや制約を明文化してAIに読み込ませる「事前制約」を行ってください。加えて、Linterや静的解析ツールをCI/CDと連携させ、AIが生成したコードを機械的に検証し、エラーがあればAI自身に修正させる「事後検証」のサイクルを構築してください。