クイックサマリー: この記事は、Zennで公開されている実践記事「VibeCoderが陥る罠：可読性・環境変数・分割設計とAGENTS.md活用」をベースに、AI生成コードが劣化していく典型パターンと、リポジトリルートに置く AGENTS.md で対策を仕組み化する方法を解説します。AGENTS.md は Codex CLI・Gemini CLI・Cursor など複数のAIエージェントが読み取るオープンな規約ファイルで、Claude Code では同様の役割を CLAUDE.md が担います。
AIに「動くコード」を書かせるのは簡単になりました。しかし、生成されたコードを次のセッションのAIに修正させたとき、「意図が伝わらず別の場所を書き換えられた」「APIキーをそのままcommitしそうになった」という経験はありませんか。バイブコーディングの速度を保ったままコードの寿命を延ばすには、AIが迷わないコードと、ルールを毎回プロンプトで言わずに済む仕組みが必要です。
元記事はZennの VibeCoder向けソフトウェア工学ベストプラクティス第2弾（無料公開記事）で、題材となるAGENTS.md自体は特定ベンダーに依存しないオープンな慣習です。この記事でわかることは次のとおりです。
- バイブコーディングで頻発する5つの罠（マジックナンバー・環境変数・スパゲッティコード・ファイル肥大化・docstring欠如）
- 各罠に対するコード例つきの具体的な対策
- AGENTS.md と SOP（作業手順書）に対策を落とし込む手順
- Claude Code / Codex CLI の実開発フローへの組み込み方
VibeCoderが陥りがちな5つの罠とは
元記事が指摘する核心は「AIが生成したコードをAIが読み直すとき、人間と同じ困りごとを抱える」という点です。可読性の低いコードは人間だけでなくAIの修正精度も下げます。具体的には次の5つが典型的な罠として挙げられています。
- マジックナンバー:
if retry_count > 3: time.sleep(60)のような裸の数値。AIは「60を変えるべきか、他の60もか」を確信できず、変更漏れの原因になります - 環境変数のハードコード: AIがテスト用に埋め込んだダミーキーを実キーに書き換えたままcommitする事故が典型例です
- スパゲッティコード: 100行超の関数や7段ネストの条件分岐は、AIの変更影響範囲の把握を困難にします
- 1ファイルの肥大化: 記事では「1ファイル1000行」を分割の目安としています。3000行のmain.pyはAIが全文を読みきれず、途中だけ見て変更するリスクがあります
- docstringの欠如:
def calc(x, y, mode)のような関数は、AIにmodeの意味を推測させることになります
記事では関数の長さの目安として20〜40行、ファイル分割の検討ラインとして800〜1000行という具体的な数値が示されており、レビュー時の客観的な判断基準として使いやすい構成です。
罠を防ぐ具体的な対策（コード例つき）
定数化と.env分離
マジックナンバーは名前をつけた定数に置き換えます。元記事のコード例をそのまま引用します。
MAX_RETRY_COUNT = 3
RETRY_INTERVAL_SECONDS = 60
if retry_count > MAX_RETRY_COUNT:
time.sleep(RETRY_INTERVAL_SECONDS)環境変数は python-dotenv で .env に分離し、必ず .gitignore に追加します。
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
raise ValueError("OPENAI_API_KEY が設定されていません")# .gitignore
.env
.env.*
!.env.example値を空にした .env.example をテンプレートとして公開し、commit前に git diff --staged で差分を確認する習慣が推奨されています。一度公開リポジトリにpushしたキーはfork・clone・キャッシュに残るため、履歴削除ではなく即時無効化が必要という指摘も重要です。
分割設計とdocstring
「取得・加工・保存・通知」をすべて行う1つの関数は、fetch_user_data / normalize_user_data / save_user / notify_slack のように1責任ずつに分けます。こうすると「fetch_user_dataだけ変えて」という指示がAIに正確に届きます。ファイルの肥大化チェックは次の1コマンドで確認できます。
wc -l main.pydocstringはGoogleスタイル + 型ヒントのセットが推奨されています。型ヒントは「何の型か」、docstringは「なぜそうするか」を伝える役割分担です。元記事では「AIに『Googleスタイルでdocstringを書いて』と頼むのが早道」という実践的なアドバイスも添えられています。
AGENTS.mdとSOPで対策を仕組みにする手順
個人の注意だけではルールは徐々に崩れ、毎回プロンプトで説明するのも非効率です。そこで対策をファイルとして固定します。
AGENTS.mdの配置と記述例
AGENTS.md はリポジトリのルートに置きます。agents.md 公式サイトによると、この形式は Codex をはじめ複数のAIコーディングエージェントが読み取るオープンな規約として整備されています。元記事の記述例は次のとおりです。
## コーディング規約
- マジックナンバー禁止：数値リテラルは定数として定義し、意味のある名前をつける
- 環境変数はコードに直接書かない：`os.getenv()` と `.env` を使う
- 関数は1つの責任のみを持つ（単一責任の原則）
- 1ファイルは原則1000行以内。超えた場合はモジュール分割を提案する
- 型ヒントとGoogle スタイルのdocstringを必ず書く
- `print`禁止。`logging`モジュールを使う
## 禁止事項
- APIキー、パスワード、トークンをコードに直接記述すること
- `except: pass` による例外の握りつぶしClaude Code を使う場合はプロジェクトルートの CLAUDE.md に同じ内容を書けば、セッション開始時に自動で読み込まれます。両方のCLIを併用するチームでは、AGENTS.md を正とし CLAUDE.md から参照する構成も選択肢になります（対応状況は各CLIの公式ドキュメントで確認してください）。
SOPで繰り返し作業を標準化する
SOP（Standard Operating Procedure）は繰り返す作業の手順書です。元記事では「新規Pythonスクリプト作成手順」として、ブランチ作成 → 定数をファイル上部にまとめる → 環境変数のNoneチェック → git diff --staged での差分確認 → PR作成、という流れを _docs/sop/ 以下にまとめる構成が紹介されています。SOPがあれば「SOPに従って新しいスクリプトを作って」という一言で、ベストプラクティスに沿った雛形をAIに生成させられます。
実際の開発フローに組み込む方法
AGENTS.md / CLAUDE.md は「書いて終わり」ではなく、日々の開発タスクと組み合わせて効果を発揮します。Claude Code を使った具体的な流れの一例です。
- 新機能実装: CLAUDE.md に規約を書いておけば、「ユーザー通知機能を追加して」と依頼するだけで、定数化・型ヒント・docstringつきのコードが最初から生成されます
- リファクタリング: 「一番長い関数を3つに分割して」と依頼すると、規約の「関数は1責任・20〜40行」を基準に分割案を提示させられます
- commit前チェック: hooks で
git diff --stagedのシークレットスキャン（git-secrets や gitleaks）を自動実行すれば、APIキー混入をAIの注意力に頼らず機械的に防げます
業種別のユースケースも想定しやすい内容です。個人開発のSaaS運営者なら、複数のAIセッションをまたいでもコード品質が揃うため保守コストが下がります。データ分析職なら、使い捨てスクリプトが肥大化して秘伝のタレ化する前に分割ラインを機械的に判定できます。受託開発チームなら、AGENTS.md自体が納品物のコーディング規約書を兼ねる運用が考えられます。
AGENTS.md・CLAUDE.md・Cursor Rulesの比較
「AIへの指示をファイルで固定する」仕組みは複数あります。主要な選択肢を整理します。
| ツール名 | 対応CLI/エディタ | ライセンス | 最終更新 | 特徴 |
|---|---|---|---|---|
| AGENTS.md | Codex CLI・Gemini CLI ほか複数 | オープンな規約 | 継続更新中（2026年時点） | ベンダー非依存。1ファイルで複数エージェントに共通指示 |
| CLAUDE.md | Claude Code | —（Claude Codeの標準機能） | 継続更新中（2026年時点） | セッション開始時に自動読込。ルール分割・参照ゲート等の運用が発達 |
| Project Rules（.cursor/rules） | Cursor | —（Cursorの標準機能） | 継続更新中（2026年時点） | glob指定でファイル種別ごとにルールを出し分け可能 |
| SOP（手順書） | CLI非依存（Markdown） | 自作ドキュメント | — | 「規約」ではなく「手順」を固定。AGENTS.mdと併用が前提 |
使い分けの目安として、単一のCLIしか使わないなら各CLI標準の形式、複数エージェントを併用するならAGENTS.mdを正とする構成が管理しやすいと考えられます。
注意点・制約
- AGENTS.mdは強制力を持ちません: エージェントへの「指示」であり、リンターのような機械的ブロックではありません。シークレット混入の防止は git-secrets / gitleaks などのpre-commitフックと組み合わせるのが安全です
- 肥大化に注意: 規約ファイル自体が長大になると、毎セッションのコンテキストを圧迫します。常時必要なルールだけを書き、詳細は別ファイルに分ける構成が実用的です
- 数値基準は目安: 「1000行」「20〜40行」は元記事の経験則であり、公式仕様ではありません。プロジェクトの性質に合わせて調整してください
- モノレポ回避は小規模前提: 元記事は「最初は1リポジトリ1サービス」を推奨していますが、これは小規模プロジェクト向けの指針です。成長後のモノレポ移行は否定されていません
- 外部通信なし: AGENTS.md・SOPはただのMarkdownファイルで、それ自体がデータを外部送信することはありません。データの扱いは読み取る側の各CLIのポリシーに依存します
まとめ
- AI生成コードの劣化は「AIが読み直すときに迷う」ことが原因。可読性はAIへの指示精度に直結します
- マジックナンバーの定数化・.env分離・1責任関数・1000行での分割・docstringの5点が優先対策です
- 対策はプロンプトで毎回伝えるのではなく、AGENTS.md（規約）とSOP（手順）に書いて仕組みにします
元記事は失敗パターンごとに「今日やる1アクション」が明示されており、上から順に試すだけで改善が始められる構成です。まずは wc -l で一番大きいファイルの行数を確認するところから始めてみてください。さらに詳しくは Zennの元記事 と agents.md 公式サイト、および各CLI（Claude Code / Codex CLI）の公式ドキュメントを参照してください。
コメント