design-doc

デザインドキュメント作成者

製品や技術に関するコンテキストを、能力のある実装エージェントが安全に実行できる、必要最小限のデザインにまとめます。

執筆前に、共有デザイン契約を最後まで読んでください。準備状況、根拠、権限、ストーリーの構文、後続の feature-delivery 契約が定義されています。

ワークフロー

1. 会話から情報を集めます。 課題、目標、制約、対象外事項、決定事項とその根拠、却下した方針、未解決の決定事項を抽出します。ユーザーが明示した選択を保持します。

2. デザインの根拠を確認します。 リポジトリの指示と、関連するビジョン、アーキテクチャ、コード、テスト、スキーマ、設定を読みます。推測する前に検索します。重要なパス、現在のシグネチャ、所有者、統合ポイントを検証します。

3. 重要な不足事項だけを明確にします。 回答によってスコープ、アーキテクチャ、互換性、安全性、ストーリーの境界が大きく変わり、その答えを発見したり安全に推測したりできない場合に限り、簡潔な質問をまとめて尋ねます。それ以外は前提を明記します。

4. デザインをまとめます。 調査の経過ではなく、選択した動作と契約を説明します。デザイン上の理由から逸脱する必要がない限り、既存のリポジトリパターンを優先します。

5. 正規のストーリーを作成します。 安定した ID を使い、コピーした課題本文だけで各ストーリーを個別に実装できるようにします。各ストーリーが依存関係の順序に沿った一貫性のある成果となる範囲で、ストーリーの数を最小限に抑えます。

6. 検証します。 インストール済みまたはリポジトリのスキルセットから design-to-issues/scripts/story_contract.py を特定し、次を実行します。

   python3 <story-contract-script> <design-doc> \
     --repo-root <repository-root> --mode author
   

   完了を報告する前に、検証で検出されたすべての問題を修正します。

7. Draft として保存します。 ユーザーまたはリポジトリで別のパスが指定されていない限り、docs/design/<short-kebab-case-name>.md に書き込みます。新規および改訂した内容は Draft のままにします。このスキルが Revised に昇格させることはありません。

ドキュメントの構成を適応させる

有用なデザイン情報を含むセクションだけを使います。一般的なドキュメントの構成は次のとおりです。

# Feature name

**Status:** Draft

## Problem and Goals
## Scope and Non-Goals
## Decisions and Rationale
## Architecture and Contracts
## Integration and Behavior
## Risks and Verification
## Open Questions
## User Stories
## Changelog

機能に合わせて見出しを調整したり、統合したりしてください。重要な場合は、セキュリティ、プライバシー、データ所有権、移行、互換性、パフォーマンス、可観測性、段階的なロールアウト、ロールバックを含めます。重要な決定の説明に役立つ場合は、代替案も記載します。関係のないセクションは定型文で埋めず、省略します。

実装上の曖昧さを解消できる場合に限り、正確な例、データ形式、シーケンス、図を記載します。提案中のインターフェースは提案であることを明記し、リポジトリの現状として提示しないでください。

ストーリーのガイドライン

共有契約に記載された正確なストーリー形式と依存関係の構文に従います。さらに、次の点に従ってください。

• 振る舞いの結果は受け入れ条件に、実装の指針は実装コンテキストに記載します。
• 条件は二値で観測可能なものにします。ファイルの配置、リンターの成功、「正しく動作する」のような曖昧な記述を、振る舞いに関する受け入れ条件にしないでください。
• 検証には、そのストーリーに適切なテスト、コマンド、ブラウザーやデバイスでの確認、移行、運用上の根拠を記載します。すべてのストーリーにすべての検証方法を必須にしないでください。
• ドキュメントや運用に関する作業は、そのストーリーで対象範囲が変わる場合に限って含めます。
• 共有アーキテクチャや契約に関する文章を改訂する場合は、影響を受けるすべてのストーリーも更新します。課題の同期でハッシュ化され、配信されるのはストーリーの内容です。
• 改訂後も既存の ID を保持します。ストーリーの追加、削除、先送り、または大幅なスコープ変更では、共有契約の権限に関するルールに従う必要があります。

改訂時の動作

レビュー成果物への対応を求められた場合は、各ブロッキング指摘を証拠と当初の意図に照らして評価してください。必要な不変条件を満たすために、整合性の取れた最小限の変更を行ってください。レビュアーの提案が自動的に解決策となるわけではありません。ブロッキングではない提案は、依頼された場合、または明らかに有益な場合にのみ適用してください。

指摘への対応の詳細は、レビュー成果物またはコーディネーターへの引き継ぎに記載してください。設計書には、次のような簡潔な変更履歴の行だけを追加してください。

- 2026-07-28: Addressed review pass 2; clarified token ownership and updated AUTH-002.

独立したフォローアップレビューに備えて、ドキュメントは Draft のままにしてください。

レポート

設計書のパス、決定事項とストーリーの順序の簡潔な要約、検証結果、および未決のユーザー判断があればその内容を返してください。課題の同期や実装は開始しないでください。