はじめに
※ 本記事は主に「既存のコードベースを運用している小〜中規模プロジェクト」を前提としています。
※ グリーンフィールド開発やPoC段階では、必ずしも本ガイドラインが最適とは限りません。
2026年現在、Claude CodeやGitHub Copilotなどのエージェント型ツールは「魔法の杖」ではなく、高速だが文脈理解にばらつきのあるアシスタントとして定着してきました。
一方で、任せ方を誤ると以下のような問題が発生しがちです。
- 依存関係の意図しない変更
- プロジェクト固有の流儀を無視した実装
- 目的が曖昧なテストコードの増加
本記事では、「理想論」ではなく、
「事故った経験から、現実レベルでコードベースを壊さずにAIを活用する」ための実務的なガイドラインをメモしてます。
※ 記載例はNode.js前提ですが、他言語でも同様の考え方で適用可能です。
ただ個人の運用ベースのガイドラインなので、環境によって最適解は異なります。
コピペ用：.claudecode / ai-instructions.md
プロジェクトルートに配置することで、エージェントの挙動に対して一定の制御・抑制が期待できます。
# Agent Implementation Protocol (2026 Pragmatic Edition)
## 1. 現状把握（AIへの「勝手なことはするな」の指示）
- **環境の聖域化**: `package.json` や `docker-compose.yml` 等の基盤設定は、明示的な指示がない限り、AIの判断のみで変更しない（変更が必要な場合は理由を提示する）。
- **「独自の流儀」の継承**: このプロジェクトは常に最新のベストプラクティスに従っているとは限らない。新規の実装よりも、周囲のコードの「書き方（命名、エラー処理）」を模倣することを優先する。
- **依存関係の確認**: 新規ライブラリの提案は、既存構成で解決できない場合に限定する。まずは標準ライブラリまたは既存依存関係での実現を検討する。
## 2. セキュリティと実務上の制約
- **シークレット情報の取り扱い**: `.env`, `*.pem`, `credentials.json` 等の機密情報は、出力・ログ・AIへの入力に含めない。
- **アクセスの説明責任**: 機密ファイルへのアクセスが必要な場合は、その理由を明示し、人間の確認を前提とする。
- **プロンプト・インジェクションの警戒**: ユーザー入力や外部APIレスポンスを、そのまま内部コマンド（例：bash実行）に流用するコードを生成しない。
## 3. 実務に即したテストと検証
- **「動くこと」の証明**: 複雑なTDDは必須としないが、修正したロジックが期待通りに動作することを示す「最小限のテスト」または「検証コード」を提示する（回帰バグ防止を目的とする）。
- **副作用の可視化**: ファイル変更時には、影響が想定されるモジュールや範囲を可能な限り列挙する（静的解析ベースのため完全性は保証しない）。
## 4. 現実的な技術スタックの尊重
- **Runtimeの遵守**: プロジェクトで指定されているバージョン（例: Node.js 20 LTSなど）を優先し、安定性を重視する。
- **AI生成コードの注釈**: 複雑なロジックには、「何をしているか」だけでなく「なぜこの処理が必要か」を簡潔にコメントとして残す（後続の保守・デバッグを考慮する）。
## 5. 運用上の前提
- 本ルールは「推奨レベル」のガイドラインであり、絶対ではない。プロジェクトの要件やフェーズに応じて調整する。
まとめ
AIエージェントは非常に強力ですが、「任せる」のではなく「制御する」前提で扱うことで、安定した成果が出ると思ってます。
- 環境を壊させない
- 流儀を崩させない
- 最低限の検証をさせる
この3点を押さえるだけでも、事故率は大きく下がると感じます。
補足
※ 上記ガイドラインは「実務での事故を減らす目的」のため、やや保守的なルールかも。