AIの誤りと運用注意
誤り早見と本番注意。
AIのよくある誤り
プロジェクト固有のルールとは別に、AI がよく間違える論点の早見表。該当行があればテスト・docs・rules で先回りする。
下表は論点ごとの典型ミスと対策。プロジェクト docs に境界表・丸めポリシー等を書いておくと効く。
| 論点 | 典型ミス | 対策 |
|---|---|---|
| 金額/数量 | float 使用 | Decimal 必須。丸めポリシーを docs に明示 |
| 時刻/TZ | ローカル保存 | UTC 保存。境界値テスト |
| 境界条件 | 0/null/上限未テスト | 境界表をテストケース化 |
| 並行更新 | ロック未考慮 | 楽観/悲観ロック方針を docs 化 |
| 冪等性 | リトライで二重実行 | idempotency key / 一意制約 |
| エラーパス | ハッピーパスのみ | 異常系チェックリスト |
| 既存整合 | 「最善実装」提案 | 既存パスをコンテキストに必須 |
| 国際化 | 単一言語前提 | 通貨・単位・エンコーディング |
| 権限 | 認証=認可 | 行レベル権限を設計 docs に |
| 性能 | N+1 | クエリ数をテスト/ログで確認 |
| データ移行 | 後方互換なし | 移行手順 + rollback |
NOTE: 言語・FW・ライブラリの最新仕様は AI の学習データより古いことが多い。公式ドキュメント・チェンジログと突き合わせる習慣をつける。
ルールは古くなります。四半期見直し・チーム導入・コスト管理をセットで運用してください。
運用の注意
運用の注意（6項目・クリックで展開）
ルールの陳腐化対策
- スプリント終了時や四半期ごとに利用中ラインのルール (
.cursor/rules//AGENTS.md/CLAUDE.md/.claude/skills//.agents/skills/) を見直す - ルール改訂時は docs/adr/ に意思決定を残す（例: ADR-NNNN: Update testing rule）
- 新規メンバーのオンボーディング時のフィードバックを取り込む
グローバルルールとの境界
- 個人のグローバルルール (
/Users/<user>/.cursor/rules/、~/.claude/CLAUDE.md、~/.codex/AGENTS.md) と重複させない - プロジェクト固有のものだけリポジトリに置く
AIツールのバージョン管理
- モデル変更で挙動が変わることがある
- 重要な意思決定では「どのモデルでいつ生成したか」を履歴に残す
- モデル変更時はチーム内で動作確認を共有
ルール運用の注意点
チームへの導入手順
- まず 1〜2 人で試し、ルールの初版を固める
- 設計レビューで Cursor / Claude Code / Codex のルール群の存在を共有
- ペアプロでフロー実演
- 既存リポジトリへは PR 単位で rules を追加
- 1〜2 スプリント後にレトロでフィードバック収集
既存プロジェクトへの段階適用
- 既存コードを一括書き換えしない
- 新規 PR から本フローを適用
- 既存実装と異なる選択は
docs/<feature>/04_tech_decisions.mdまたはdocs/adr/に理由を残す
コスト管理
- 長セッションはコンテキストコスト高 → 1 チャット 1 タスクで分ける
- 単純な補完は Tab 補完 / cmd+K で済ませる
- Plan/設計の議論は Web の Free Tier でも可
1 機能 = 1 チャットに分ける — 1 機能 = 1 チャットに分ける。変数名修正は Tab 補完、Plan 議論だけ別チャットで行い、実装チャットのコンテキストを薄く保つ。