このファイルは、このリポジトリで作業するコーディングエージェント向けの必須ルールを定義する。 曖昧な場合は勝手に楽観解釈せず、前提・制約・未確定事項を明示すること。 上位指示（system / developer / user）がある場合はそちらを優先すること。
- まず依頼の目的、影響範囲、変更対象、完了条件を整理してから作業する。
- 中規模以上の変更では、実装前に「何をどう変えるか」「どこが危ないか」を短く計画として示す。
- 変更は最小限に留める。依頼と無関係なリファクタリングや美化はしない。
- 既存コードの設計方針・命名・責務分割・フレームワーク流儀を優先し、独自流儀を持ち込まない。
- 既存の安全な仕組み・共通基盤・ユーティリティがあるなら、それを使う。
- わからない点を黙って埋めない。仮定で進めた箇所は最終報告で明示する。
- APIキー、秘密鍵、トークン、認証情報、個人情報をコード・設定・テスト・ログ・コメント・ドキュメントに直書きしない。
.env、秘密情報、認証情報、バックアップダンプをコミットしない。- 認可・権限・RLS・ACL・CORS・CSRF・レート制限・入力検証を「動作確認のため」に弱めたままにしない。
- スタックトレース、SQL、内部パス、内部テーブル名、ライブラリ詳細をユーザー向けエラーに露出しない。
- 本番データを直接更新しない。本番DBへの手作業クエリ、手動補正、直編集を前提にした修正を提案しない。
- 本番環境で試験しない。本番でのみ再現する場合でも、まず再現条件と安全策を整理する。
- IAM、ネットワーク、FW、公開設定、ストレージ公開範囲、外部公開URLなどの危険変更を、明示的な依頼なしに行わない。
- 新しい本番依存（外部API、SaaS、重いライブラリ、ジョブ、監視、永続化基盤）を、必要性と影響説明なしに追加しない。
- 「ログインできる」ことをもって安全と見なさない。
- クライアント側バリデーションだけで安全と見なさない。
- 認証と認可を分けて考える。
- データ取得・更新・削除のたびに、「現在のユーザーがその対象にアクセスしてよいか」をサーバー側で検証する。
- URLやリクエスト中のIDを信用しない。IDORを前提に疑う。
- 管理者権限、組織境界、テナント境界がある場合は毎回明示的に確認する。
- ユーザー入力、外部API応答、Webhook、アップロードファイル、クエリ文字列はすべて不正値を含みうる前提で扱う。
- バリデーションはサーバー側でも必ず行う。
- 文字数、型、範囲、必須、列挙値、形式を検証する。
- 出力時は文脈に応じてエスケープ・サニタイズする。
- ファイルアップロードを扱う場合は、拡張子だけでなく実体を確認し、サイズ上限、保存先、ファイル名正規化、実行不能化を検討する。
- シークレットは環境変数または秘密管理機構から取得する。
- 公開してよい鍵と秘匿すべき鍵を混同しない。
- 権限は最小化する。
- 開発用と本番用の鍵は分離する。
- 漏えい時の無効化・再発行手順を壊すような実装は避ける。
- 監査に必要なログは残すが、機密情報は残さない。
- エラー時は利用者向けメッセージと内部ログを分離する。
- セキュリティ上重要な失敗（認可失敗、異常入力、外部API失敗、ジョブ再試行など）は、必要に応じて観測可能にする。
- スキーマ変更は高リスク変更として扱う。
- DB変更を含む場合は、実装前に以下を整理すること。
- 何が変わるか
- 後方互換性が保てるか
- マイグレーション手順
- ロールバック可否
- バックアップ前提
- ステージング検証方法
- カラム削除、型変更、制約追加など破壊的変更は、既存コードとの両立期間が必要か検討する。
- データモデルは「今動く」だけでなく「後で変えられるか」で見る。
- 削除は物理削除か論理削除かを意識し、既存方針に合わせる。
- 本番データを直接読む・直す運用に依存した設計を作らない。
- 複数の状態変更をまたぐ処理では、途中失敗時に何が起きるかを必ず考える。
- 決済、在庫、予約、通知、外部API連携、ジョブ再実行では、特に以下を確認する。
- トランザクション境界
- 冪等性
- 二重送信時の挙動
- タイムアウト時の再試行
- 部分成功時の補償処理
- 「同じ要求が2回飛んでも壊れないか」をレビュー観点に含める。
- 新規ライブラリ追加時は、追加前に以下を確認して報告する。
- 何のために必要か
- 既存手段で代替できないか
- 保守状態
- ライセンス
- セキュリティ上の懸念
- バージョンは固定または再現可能な形で管理する。
- 使わない依存は増やさない。
- AIが提案したパッケージ名は実在確認なしに採用しない。
- 課金が発生しうるものを追加・変更する場合は、実装前にコスト要因を整理する。
- 特に以下は報告対象とする。
- API呼び出し回数
- トークン消費
- DB読み取り回数
- ストレージ増加
- バックグラウンドジョブ頻度
- ユーザー操作連打時の課金影響
- 無限ループ、過剰ポーリング、N+1、無制限再試行、重複ジョブ投入を避ける。
- 予算アラート、上限設定、レート制御が必要なら提案する。
以下に触れる場合は、実装を急がず懸念点を先に報告すること。
- スクレイピング、クロール、利用規約依存のデータ取得
- 個人情報、機微情報、決済情報
- 医療、金融、法律など規制領域
- 著作権・ライセンス上グレーな生成物やデータ
- GPL等のライセンス混入可能性
法的判断を断定しない。懸念点、前提、確認すべき論点を整理する。
- ループ内DBアクセス、全件走査、無制限ページング、同期的な多重外部API呼び出しを避ける。
- 一覧API・検索API・集計処理では、件数増加時のボトルネックを意識する。
- 少なくとも以下を点検する。
- N+1問題
- 必要なインデックス
- 不要なSELECT *
- 過剰な逐次処理
- キャッシュ要否
- 1リクエストあたりのクエリ数
- まだ最適化しない場合も、「どこが将来ボトルネックになるか」は最終報告に書く。
- 実装前に、対象変更の仕様を短く言語化する。
- その仕様から、正常系・異常系・境界値・権限違反・二重実行・部分失敗の観点でテストケースを洗い出す。
- テストはハッピーパスだけで終わらせない。
- モック過多で意味の薄いテストを量産しない。
- テスト名は仕様が読める名前にする。
- 実装詳細ではなく振る舞いを検証する。
- 可能なら以下を使い分ける。
- 単体テスト
- 結合テスト
- 回帰テスト
- テストを追加しない場合は、「なぜ追加しないのか」を説明する。
- 変更内容は追跡可能に保つ。
- コミットや push は、明示的に依頼された場合のみ行う。
- 差分は小さく保ち、レビューしやすい粒度を意識する。
- 生成物、秘密情報、ローカル設定、キャッシュを不用意に差分へ含めない。
- 振る舞い変更がある場合は、必要に応じて関連ドキュメントも更新する。
- 開発・ステージング・本番は別物として扱う。
- 本番専用設定を開発環境へ持ち込まない。
- 開発で本番データを使わない。必要なら匿名化・最小化・複製手順を前提とする。
- 本番のみで使う資格情報、エンドポイント、ジョブ、Webhookをローカル検証に流用しない。
判断に迷ったら、以下の順に優先する。
- 安全性
- 正しさ
- 変更の局所性
- 運用しやすさ
- 性能
- 開発速度
- 見た目の美しさ
最終報告では必ず以下を含めること。
- 何を変更したか
- なぜその変更にしたか
- どのファイルを触ったか
- どんなテスト・確認をしたか
- 未解決の懸念
- 追加で確認すべき点
- 仮定して進めた点
以下を満たして初めて「完了」とみなす。
- 依頼された目的に対して変更が十分である
- セキュリティを壊していない
- 既存規約と整合している
- テストまたは妥当な確認が済んでいる
- 危険な仮定や未確認事項が報告されている
- ドキュメント更新が必要な場合は反映されている
以下に該当する場合、実装を強行せず、リスクを説明して確認または方針提示に切り替えること。
- 本番影響が大きい
- 認可・権限・公開範囲に関わる
- DB破壊的変更を含む
- 法務判断が絡む
- 課金影響が読めない
- 既存設計の意図が読めない
- テストで安全確認できない