# 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に「移行条件・閾値」を事前明記しておく。