AIエージェント向け指示（個人開発用・二層版）

目的: 個人開発で、要求定義〜テストまでを秩序立てて進めるための指針。
方針: 最小限守る「必須ルール」と、余裕があれば取り入れる「推奨ルール」に分割。

必須ルール（最低限これだけは守る）

開発プロセス

• フロー: 要求 → シナリオ → 要件 → ユースケース → 仕様 → 設計 → 実装 → テスト
• 成果物は Markdown で記録:
  • docs/requests/, docs/scenario/, docs/requirements/, docs/usecases/, docs/spec/, docs/design/, docs/adr/
• 要求が最上位。下位成果物に矛盾が出たら ADR で修正方針を残す。

要求・要件・仕様

• 各要求は 5W1H と 受入基準（検証可能な観測指標）を記す。
• シナリオは「誰が／どの機能で／何を達成するか」の代表フローに限定。
• 要件は「ユーザー種別・情報構造・提供機能・得られる価値」を揃える。
• 仕様は「公開操作／入力要件／出力契約／制限事項」を最低限揃える。
• 国際化・アクセシビリティ(i18n/a11y)の検討を要件段階で実施し、対象外なら理由を明記。

設計

• 低結合・高凝集、可読性・交換容易性・一覧性を重視。
• 設計を俯瞰する簡潔なクラス図/依存図を mermaid で記録。

セキュリティ

• 秘密情報（APIキー等）を直書きしない（秘密管理の利用前提）。
• 依存の脆弱性チェックを実施（CI/ローカルいずれでも可）。
• ログに個人情報を残さない。必要時はマスキング方針を仕様に記載。
• 構造化ログ必須化によるリスク対策:
  • 機微情報はログに出さない。
  • マスキング規則を明示し、テストで検証（ダミーデータを用いた検証を含む）。

可観測性・追跡性

• 構造化ログ（例: JSON）を必須。エラー/主要イベントに相関ID（トレーサビリティ）を持たせる。
• 失敗の事後メモ（簡易ポストモーテム）を ADR に残す。

テスト

• ユニットテストとe2eテストを最低限整備。クリティカル経路は必ずテストする。
• カバレッジ可視化を有効化し、主要モジュールのカバレッジを確認可能にする。

インフラ・データ

• インフラは 無料枠 / 安価枠優先 を原則とし、選定理由を ADR に記録。
• データベースは スキーマ管理とマイグレーションを明示的に実施（計画・適用・ロールバックの手順を仕様/設計に記載）。

バージョン管理・リリース

• main に直コミット禁止。必ず PR を経由（内容・関連ドキュメント更新の有無を記載）。
• 破壊的変更は CHANGELOG または ADR に明記。
• 自動リリースノート生成を導入（プラットフォームは問わない）。重要変更は必要に応じて追記。
• 自動リリースノートの精度確保:
  • PR タイトル・コミットメッセージに命名規約を導入（例: Conventional Commits）。
  • 内容が正しくリリースノートに反映されることを確認する。

推奨ルール（余裕があれば取り入れる）

ドキュメント運用

• ADR/要求/要件は 1件1ファイルで細分化（小規模変更は軽量ADRでも可）。
• ユースケース/仕様ごとにモデル図を整備し、俯瞰性を高める。

セキュリティ強化

• 簡易脅威モデリング（想定リスクと軽減策リスト化）。
• 依存ライセンスチェックや SBOM 生成を CI に組み込み。
• Secrets 管理の強化（保存/ローテーション/監査の最小ルールを決める）。

テスト拡張

• Property-based testing の段階的採用。
• 回帰テストセットの維持（LLM評価を含む場合は再評価手順を短文化）。

可観測性拡張

• 重要メトリクス（利用・性能）を軽量に収集。
• エラーレポートや通知の簡易連携（メール/チャット等）。

インフラ・運用拡張

• 簡易デプロイ戦略（Blue-Green/Canary）の導入。
• バックアップ/リストア手順のドキュメント化。

コスト配慮（推奨化した懸念への対応）

• カバレッジ計測のCIコスト抑制: PRのみ実行、主要パスに限定する。
• リリースノート生成の運用品質確保: タグ運用と自動生成の両立で冗長性を持たせる。
• 無料枠優先による将来移行コスト対策: ADRに「移行条件・閾値」を事前明記しておく。