XeroBis/website

計画とドキュメント化

なぜ

「ポート cards」や「ポートフォリオにタグを追加」のようなリクエストは、最終決定のように見えますが、通常は未解決の選択肢を隠しています。今どれだけ構築するか、古いリポジトリから何を削除/変更するか、どのスキーマがデータを所有するか、何を @shared に入れるかなどです。すぐに構築を始めると、間違ったことをしたり、やり直したり、既に documentation/decisions.md に記録されている選択から逸脱するリスクがあります。最初に質問することで、ドキュメント — そして後にはコード — がユーザーが実際に望むものを正確に記録することを保証します。

適用タイミング

documentation/ で追跡しているものを変更するリクエスト全てに適用されます。機能やユーザー向け動作、スキーマ/テーブル/カラム/ビジネスルール、技術やライブラリの選択、フォルダ/アーキテクチャ構造、migration-plan.md のステップなどです。小さく完全に特定された編集（このタイポを修正、このラベルを正確にXにリネーム）はインタビューを必要としません — 実際にどれだけ曖昧かを判断してください。

手順

1. 質問する前に読む。 リクエストに関連する documentation/*.md セクション（および関連コード）をざっと読んでください。移植の場合は、古いリポジトリのドキュメント（../<repo>/documentation/、../<repo>/CLAUDE.md）と移植対象のコードも読んでください。既に答えがあることを質問しないでください。それらを質問のベースラインとして使用します。

2. AskUserQuestion で明確化質問をする。 1つの広い質問よりも、いくつかの小さく具体的な質問を優先してください。このリポジトリでは以下のような質問が適切です：

   • 今すぐ構築する量と後回しにする量；
   • 移植時：古いアプリから何をそのまま維持し、何を変更し、何を削除するか（古い動作が自動的に望まれているわけではない）；
   • 新しいテーブルを所有するスキーマ（アプリ自身のスキーマか、全アプリが必要とする場合は core か）；
   • その部品が1つのアプリに属するのか、@shared や共有バックエンドモジュールに属するのか；
   • features.md が記録する必要がある UX 詳細、および新しいデータの形状。

   各質問には推奨デフォルト値を付けて、ユーザーが素早く進められるようにします。

3. ユーザーが返したスコープをそのまま尊重する。 ユーザーが「ドキュメントのみ」や「X だけで Y は不要」と限定した場合、静かに範囲を広げないでください — 後でスコープを拡張する前に再度確認してください。

4. 決定と同じステップでドキュメントを更新する。ルーティング先は CLAUDE.md のテーブルに従います：

   • フォルダ構造、環境、ポート、リクエストフロー → architecture.md
   • スキーマ、テーブル、カラム、リレーションシップ、ビジネスルール → data-model.md、該当スキーマのセクション配下
   • 技術/ライブラリ/アーキテクチャの選択 → decisions.md：日付付きで、何を、何に対して、なぜ選んだかを記載（ファイルのスタイルに合わせる）
   • ユーザー向け動作、バリデーションルール → features.md、該当アプリのセクション配下
   • 先送り、却下、またはまだ可能性があるもの → ideas.md
   • 移植の進捗 → migration-plan.md のステータスカラム
   • プロダクションランブックの変更 → deployment.md

5. 解決済みのアイデアを ideas.md から移動する。 変更によって ideas.md のエントリが実際の決定に変わった場合は、そのエントリを削除または書き換え、古い重複を残さないようにします。