generar-tech-design

テクニカル設計ドキュメント生成ツール（対話型）

目標

本番環境で使える品質のテクニカル設計ドキュメント（TDD）と、それを補足するアーキテクチャ決定記録（ADR、MADR 形式）を作成します。実際の実装を導けるほど十分に詳細で、将来の保守担当者にその根拠を示せるほど追跡可能なものにします。簡易なドラフトを生成するツールではありません。

このスキルは一問一答ではなく、対話形式です。 TDD 全体を一度に生成してはいけません。アーキテクチャ上の決定を一つずつユーザーと検討し、現実的な代替案とそれぞれのトレードオフを提示したうえで、どれを選ぶか（または別の案があるか）を尋ねます。その後で初めて、実際の決定を反映した ADR を作成します。ユーザーの意見を聞かず、エージェントが単独で決めた ADR は、このスキルの失敗です。

入力

• PRD.md — 必須です。課題、ユーザー、スコープ、プロダクトレベルの受け入れ基準が記載されています。ファイルがない場合は処理を中断して提示を求めてください。PRD の内容を捏造してはいけません。このスキルの対象はアーキテクチャ上の決定だけです。
• Design.md — 任意ですが、あると望ましいです。存在する場合は、データモデルの決定における主要な入力として使用してください。インターフェースが示唆する具体的なデータ（割引フィールド、ステータスバッジ、フィルターなど）から、PRD だけではわからないモデル要件が明らかになることがよくあります。存在しない場合は、処理を続行し、TECH-DESIGN.md に Design.md が利用できなかったことを記載してください。これを理由に処理を中断してはいけません。

ステップ 0 — プロジェクトの種類

何よりも先に、ユーザーにこのプロジェクトがグリーンフィールド（ゼロからの構築）か、ブラウンフィールド（既存のコードベース）かを尋ねます。

• グリーンフィールド： 以下のワークフローに直接進みます。すり合わせが必要な既存の制約はありません。
• ブラウンフィールド： 既存のリポジトリやコンポーネントのパスと、既存ドキュメント（README、CLAUDE.md、以前の ADR やテクニカル設計ドキュメント）の有無を尋ねます。決定を行う前に、それらを読みます。既存の選択は白紙ではありません。
  • 既存のコードですでに決まっている領域（例：スタックがすでに Node.js と Postgres である場合）は、その領域についてのヒアリングを省略し、既存の選択を決定として記録したうえで、Estado: Aceptado (heredado) を設定した ADR を作成します。ただし、ユーザーが明示的に見直しを希望した場合は、通常の新しい決定として扱い、「結果」に既存の選択を変更することを記載します。
  • 既存のリポジトリがすでに採用している方針に、暗黙のうちに矛盾するアーキテクチャ上の決定を提案してはいけません。PRD の新しい要件が既存のアーキテクチャと衝突する場合は、独断で解決せず、ユーザーにその衝突を明確に伝えてください。

ワークフロー

1. PRD.md（必須）、Design.md（存在する場合）、そしてブラウンフィールドの場合は、既存のリポジトリとステップ 0 で特定したドキュメントを読みます。
2. assets/decision-areas.md を参照して、このプロジェクトに該当する意思決定領域（コンポーネント／リポジトリ、データモデル、API コントラクト、コンポーネントごとの技術スタック、状態管理、レジリエンス／エラー処理、および PRD で求められているもののリストにない項目）を特定します。ブラウンフィールドプロジェクトでは、ステップ 0 に従って、すでに確定している領域に印を付けます。
3. 新しい意思決定領域（継承した選択によってすでに確定しているものを除く）ごとに、1 つずつ次の手順を実施します。 a. 背景を示します。この決定が必要な理由と、PRD／Design.md が示唆している内容を引用します。 b. 具体的なトレードオフを伴う、現実的な選択肢を 2～3 個提示します（見せかけの二者択一は避け、各選択肢がこのプロジェクトで実際に実現可能であること）。 c. ユーザーに選択肢を選んでもらうか、別の案があるかを尋ねます。回答を待ってから次に進みます。 d. assets/adr-template.md を使用して、直ちに ADR を作成します。選択した案を Decision に、選ばなかった案とその理由を Alternatives considered に記載し、選択による実際のトレードオフを少なくとも 1 つ含む Consequences を記載します。メリットだけを記載してはいけません。
4. すべての決定を記録した後、PRD の主要なフローごとに、PRD 自身の基準よりも細かい受け入れ基準を導き出します。判断が必要だった基準については、最終確定前にユーザーに確認します。
5. assets/tech-design-template.md を基に TECH-DESIGN.md を作成し、継承したものも含め、すべての ADR を番号で参照します。
6. ディスクに書き込みます。
   • プロジェクトのルートに TECH-DESIGN.md を作成します。
   • 決定ごとに 1 ファイルずつ、記録した順に連番で adrs/0001-{slug}.md、adrs/0002-{slug}.md、... を作成します（新規または継承）。

品質ゲート

完了前に、次の点を内部で確認します。

• すべての ADR に Context、Decision、少なくとも 1 つの実際のコストまたはトレードオフを含む Consequences が記載されています。また、新しい決定には、却下した Alternative が少なくとも 1 つ記載されています。既存の内容を記録する継承 ADR（Aceptado (heredado)）は、すでに確定している内容を記録するため、Alternatives の要件は免除されます。
• アーキテクチャ上の決定が、ユーザーに先に問題を提示することなく、PRD の「No alcance」セクションまたは既存のブラウンフィールドコードベースと矛盾していません。
• データを示唆する Design.md（利用可能な場合）のすべての UI 要素に、対応するデータモデルの決定があります。
• 受け入れ基準は曖昧な形容詞ではなく、検証可能です。
• TECH-DESIGN.md に記載された新しい決定は、すべて実際にユーザーから回答を得ています。質問を飛ばしたためにエージェントだけで決めたものはありません。

参考資料

• assets/decision-areas.md — 検討する決定事項と、リストにない項目を追加するタイミング。
• assets/adr-template.md — 継承された決定の状態を含む、各 ADR の MADR-lite 形式。
• assets/tech-design-template.md — ADR をまとめて参照する TDD ドキュメント。