AIを迷走させない：すぐ使える協働のエンジニアリング手法（テンプレ付き）

• AI にバグ修正を頼んだら、関係ないコードまで“親切に”直されて、結局手で戻す羽目になる
• プロンプトを山ほど書いても、AI が正しいファイルに辿り着けず、最後は“当てずっぽう”
• 会話が長くなると制約を忘れはじめ、出力品質が急降下する

• AGENTS.md：プロジェクトのハード制約（レッドライン、デフォルト、Done の定義）
• docs/ai-playbook/index.md：高シグナルな入口（1 ページ索引）
• docs/ai-playbook/code-map.md：コード地図（どこを触るか）
• docs/ai-playbook/flows.md：重要フロー（どう動くか）
• docs/ai-playbook/collab-rules.md：協働ルール + 変更計画テンプレ（どう進めるか）

Step 0：境界と Done を先に決める（プロンプトから始めない）

1. Boundary（境界）：絶対にやってはいけないこと（プライバシー/アーキテクチャのレッドライン、プロトコル互換、重要パラメータの護栏）
2. Scope（範囲）：一度に一つの目的。「ついで修正」禁止
3. Done（完了条件）：ビルド/テスト/手動回帰チェックは必ず書く

目的は単一、まず計画。プライバシー/アーキテクチャのレッドラインを越えない。完了は build が通り、回帰チェックが書かれていること。

よくあるアンチパターン：ここは踏まない

1. 計画なしで AI に「コードを直して」と言う
   • 結果：10 ファイル変わってから方向違いに気づき、戻すコストが爆発する
   • 正解：先に変更計画を出させ、承認してから実装
2. ドキュメントを全部 AI に投げる
   • 結果：文脈が飽和して要点が消える（入口ファイルすら見つけられない）
   • 正解：高シグナルな index + code-map に絞る
3. AI に「ついでに最適化」させる
   • 結果：PR が複数目的で混ざり、レビューが重く、バグの切り戻しも難しい
   • 正解：単一テーマで最小・可逆に

Step 1：AGENTS.md を書く（ハード制約を強制的に再利用する）

• Plan first：AGENTS.en.md:7
• One change, one purpose：AGENTS.en.md:8
• Privacy & architecture red line：AGENTS.en.md:9
• Docs must stay in sync：AGENTS.en.md:12
• Verification required：AGENTS.en.md:13

# AGENTS — Repo Rules

First Principles

- Plan-first: Propose a change plan and get approval before writing code
- Single-scope: One PR solves one goal; avoid “while I’m here” fixes
- Redlines: Never cross privacy/architecture/protocol/key-parameter guardrails
- Docs-sync: Keep the playbook docs in sync when entry points/flows/interfaces change
- Validation: Must include build/tests and key manual regression checklist

多言語対応

• AGENTS.en.md をカノニカル（基準）として保つ
• 必要に応じてローカライズ版（例：AGENTS.<locale>.md）を追加する
• clone 後、各自がローカルで言語に合わせた symlink を作る：

# English users
ln -s AGENTS.en.md AGENTS.md

• symlink 衝突を避けるため .gitignore に AGENTS.md を入れる

核心の洞察
AI 協働の本質は「良いプロンプト」ではなく「制約をリポジトリの一部にすること」。AGENTS.md はルールを再利用可能にし、AI Playbook は文脈を持続可能にします。

Step 2：docs/ai-playbook/index.md（高シグナルな入口索引）を書く

• 30 秒で読める：プロジェクト概要 + リンク索引だけ
• 1 クリックで飛べる：読者/AI を code-map / flows / collab-rules に誘導する

# AI Playbook — Index

## Project Snapshot

- Stack: Next.js / Node / ...
- Red lines: ...

## Document Index

- Code map: docs/ai-playbook/code-map.md
- Key flows: docs/ai-playbook/flows.md
- Collaboration rules: docs/ai-playbook/collab-rules.md

Step 3：code-map.md（どこを触るか）を書く：入口ファイル + 役割 1 行

• 重要ディレクトリと入口ファイルだけ列挙
• 入口ファイルは 1 行で責務を書く
• 依頼が来たら、まず code-map で 3–8 個の候補を当ててから深掘り

Common request routing

- New page / SEO: frontend/app/\*\*/page.tsx + metadata.ts
- i18n copy: frontend/constants/messages/\*
- Blog: frontend/content/blog/\* + frontend/lib/blog.ts

• 初版：AI に「ディレクトリ + 入口ファイル」を要約させ、完璧さより“当てやすさ”を優先
• 更新：PR ごとに差分でメンテ。丸ごと書き直しは避ける

Step 4：flows.md（どう動くか）を書く：時系列 + デバッグ要点 + マイクロ計画

• 時系列と不変条件が書かれていれば、AI は“雰囲気修正”をしなくなる
• 過去の落とし穴をチェックリストに圧縮して再利用できる

1. 重要フロー / 時系列（必要なら Mermaid）
2. デバッグ要点（見るべきログ/状態）
3. マイクロ計画テンプレ（計画 → 承認 → 実装を強制）

• 初版：AI に E2E フロー + 重要時系列 + 不変条件を復唱させ、あなたが修正して文書化
• 更新：インターフェース/時系列が変わったら差分で追従

Step 5：「Plan first」を工程化する（計画 = ミニ設計書）

Title: <short, clear title>

Goals
- <what you want to achieve>

Scope / Files
- <list of files you’ll change/add + why>

Approach
- <implementation plan and key design points>

Risks & Mitigations
- <risk> → <mitigation>

Acceptance Criteria
- <verifiable acceptance items>

Rollback
- <how to revert quickly>

Docs to Update
- docs/ai-playbook/index.md / code-map.md / flows.md / collab-rules.md / others?

Validation
- Build: next build
- Manual: <key cases & regression points>

1. index + code-map + flows を読む（読み取り専用、コードは触らない）
2. 現状と制約を自分の言葉で復唱する（あなたが 1 回だけ矯正）
3. 変更計画を書く（承認後に実装）

避坑
計画段階で方向を直す。書いてから壊すのを避ける。単一テーマは rollback とマージを軽くします。

Step 5.1：文脈の持久力（チェックポイント → 新しい会話）

# Handoff

## Problem statement (3–5 sentences)

## Confirmed plan (bullets)

## Done / Not done

## Key files and entry points

## Red lines and invariants

## Acceptance & regression checklist

## Next-step checklist

Step 6：協働を閉ループにする（新入社員を迎えるように agent を扱う）

1. 依頼 → 制約（AGENTS.md を引用）
2. 位置特定 → 入口（index + code-map を引用）
3. すり合わせ → 時系列（flows を引用）
4. 計画 → ミニ設計書（collab-rules テンプレ）
5. 実装 → 小さく単一テーマ（切り戻しやすい）
6. 検証 → next build + 手動回帰点
7. 同期 → playbook を最新に保つ

• 計画で方向を直し、作って壊すを減らす
• 単一テーマで rollback を軽く、マージを簡単に
• flows で過去の罠を checklist 化して再利用

• 変更計画のリンク/要約はあるか？
• 入口/フロー/IF が変わったなら docs/ai-playbook/* を更新したか？

すぐ使えるプロンプト例

• Role: sets quality bar and responsibility boundaries
• Kickoff: forces reading the playbook instead of guessing
• Working style: makes “plan first” part of the workflow

業界参照：OpenAI は Codex でスプリントをどう回すか

• agent は“新しいシニアエンジニア”として扱う：強いが、制約とアーキテクチャの明確化が必要
• ルールの外部化：強い AGENTS.md を保守するのは効く
• 実装前に計画：計画はミニ設計書。コードより先に計画をデバッグ
• 文脈の持久力：限界が来たら計画をファイルへ書き、次のセッションへ
• マルチセッション並列：単一ツールより“チームを運用する”に近い

そのままコピーできる最小ディレクトリ構成

AGENTS.en.md             # Canonical rules (English)
AGENTS.<locale>.md       # Optional localized rules
AGENTS.md                # Symlink (created locally after git clone)
docs/
  ai-playbook/
    index.md             # High-signal entry point
    code-map.md
    flows.md
    collab-rules.md

次にやること

1. 今すぐ始める：最小構成をあなたのリポジトリにコピーし、まず AGENTS.md から
2. 参考実装： PrivyDrop GitHub で AI Playbook 全体を見る
3. フィードバック：役立った/詰まったら issue やコメントで共有
4. Star：価値があれば PrivyDrop に star を 🌟

結び