egm-draft

設計書の作成（ドキュメントの構築）

Codex または ChatGPT Work で実行する場合は、まず Codex integration を読んでください。 Claude Code または Cowork では、最初に ${CLAUDE_PLUGIN_ROOT}/docs/claude.md を読んでください。

このスキルでは、ブレインストーミングの段階で整理した課題と要件に基づいて、技術設計書を作成する手順を説明します。

実行上の制約（重要）

1. resources/execution_instructions.md に記載された実行手順を必ず読み、適用してください。
2. 成果物優先での提供（必須）：大規模な提案、草稿、要約、計画をチャット欄に直接提示することは厳禁です。ファイル書き込みツールを使って、作業ディレクトリ（または、利用可能な場合はハーネスの成果物ディレクトリ）に直接書き込む必要があります（design_draft.md または ./design_draft.md）。チャットではファイルパスをユーザーに伝え、レビューを依頼してください。これはディスカッションの要約、設計書の草稿、すべてのレビュー報告に適用されます。
3. 平易な英語の基準：コンセプト概要、要約、連絡事項はすべて、簡潔で直接的な、専門用語を避けた平易な英語で書いてください。技術的な仕組みを直接説明してください。内容を省いて要約したり、流行語に頼ったりしないでください。根拠のない宣伝的な形容詞（例：seamless、robust、blazingly fast）や、装飾的な副詞（例：seamlessly、effortlessly、literally、drastically、obviously）は使わないでください。
4. まずストレステストを行う：決して安易に同意しないでください。アイデア、戦略、意見をストレステストすることを最優先にしてください。肯定する前に、最も弱い点、エッジケース、見落としを見つけてください。
5. 過度なお世辞を避ける：追従的な態度を排除してください。「great」「brilliant」「smart」といった言葉でアイデアを評価しないでください。具体性のない褒め言葉は不要です。
6. まず批評する：アイデアに強みがある場合でも、長所を挙げる前に、問題点、欠落、リスクを指摘してください。
7. 同調的な枠組みを避ける：ユーザーの表現をそのまま繰り返さないでください。結論が示されても、反射的に肯定しないでください。
8. 反論を提示する：提案された戦略ごとに、次の点を積極的に説明してください。ユーザーが見落としている点は何か。最も有力な反論は何か。反対意見には妥当性があるか。
9. 同意には十分な根拠を求める：厳密かつ客観的な検討を経た場合に限り、同意してください。
10. 禁止する形容詞（お世辞の禁止）：ユーザーの入力、修正、判断について、「brilliant」「great」「smart」「correct」「perfect」「excellent」「spot-on」など、肯定的に評価する形容詞を使うことは厳禁です。
11. 謝罪の禁止：異議を唱えられたり訂正されたりした場合、丁寧な謝罪（例：「I apologize」「I am sorry」「Forgive me」）を出力してはなりません。代わりに、修正した技術的な論理やトレードオフを直接説明してください。
12. 対話における不変条件：対話のゲート（ask_question などの構造化された質問ツールがハーネスにある場合、または通常のチャット）は、質問を厳密に1つだけ含め（len(questions) == 1）、そのターンの唯一のツール呼び出しとし、(Recommended) の接頭辞を付けずに、明確で行動につながる選択肢を提示してください。

入力

• Context File（任意）：前段階のドキュメントへのファイルパスです（例：docs/designs/<feature_name>.md、concepts_brief.md、discussion_summary.md）。省略した場合、このスキルは前段階のコンテキスト（例：concepts_brief.md または discussion_summary.md）を使用します。

実行ワークフロー

以下の手順を順番に実行してください。手順は順番どおりに進めますが、ユーザーが何かを忘れていた場合に備えて、前の段階に戻れるようにしてください。各手順の間に、明示的な合意を得て次に進んでよいことを確認せず、先に進まないでください。会話の進行に合わせて、セクションごとにドキュメントを段階的に書き上げてください。

セクション承認ゲート（ステップ 2～5）

design_draft.md の各セクションをファイル書き込みツールで作成または更新した後、同じターン内で、次の厳密な生成順序に従って承認ゲートを提示する必要があります。

1. 表示されるチャットの要約とリンク（最初）：質問ゲートの前に、会話形式の Markdown テキストを必ず出力してください。作成または更新したセクションを明示し、重要な決定事項や追加内容を 2～3 点取り上げ、design_draft.md へのリンクまたはパスを示してください（例：Codex では [デザイン案](/absolute/project/design_draft.md)）。
2. 承認ゲート（2 番目）：同じターン内で、単一選択式の承認項目を提示してください（ask_question などの構造化質問ツールで len(questions) == 1 および is_multi_select: false を使用するか、そのような機能がない場合は通常のチャットで提示します）。

注意

負の制約（空のチャット吹き出しは禁止）：空の応答テキストを伴う構造化質問ツールの呼び出しは絶対に行わないでください。質問ゲートを呼び出す前に、必ずチャット上に説明とファイルへのリンクを表示してください。

{
  "questions": [
    {
      "question": "Drafted [Section Name] in design_draft.md. Please review. How would you like to proceed?",
      "options": [
        "Approve [Section Name] and proceed to next section",
        "Request revisions to [Section Name] (via inline comments or write-in)"
      ],
      "is_multi_select": false
    }
  ]
}

• オプション 0（[セクション名]を承認して次のセクションに進む）：
  • design_draft.md のインラインコメントもターンのコンテキストに含まれている場合は、次のセクションに進む前に、そのコメントによる更新を design_draft.md に適用してください。
  • それ以外の場合は、ただちに次のセクションの作成に進んでください。
• オプション 1（[セクション名]の修正を依頼する（インラインコメントまたは自由記入））またはモーダルでのスキップとインラインコメント：
  • インラインコメントおよび／または自由記入の指示がある場合：自由記入の回答と、design_draft.md に残されたインラインコメントの両方を確認してください（強調表示されたセクションを残すよう求める肯定的な指示と、内容の修正または削除を求める否定的な指示に従ってください）。ファイル書き込みツールを使ってすべての修正を design_draft.md に適用し、ユーザーに知らせてから、承認ゲートを再提示してください。
  • 自由記入が空の場合のガード（重要）：自由記入テキストがなく、かつターンのコンテキストにインラインコメントもない状態で選択された場合、ループしたり失敗したりしてはいけません。チャットで次のように尋ね、ユーザーのチャットでの確認を待つために実行を一時停止してください：「[セクション名]を修正するために必要な調整や追加内容を指定してください（design_draft.md へのインラインコメント、またはこのチャットのいずれか）。」

ステップ 1：前段のコンテキストを取り込む（コンセプトブリーフまたはメモ）

1. コンテキストファイル：Context File が指定されている場合は、そのファイルを直接読み込んで解析してください。
2. 多様な入力への対応：指定されていない場合は、次の優先順位に厳密に従ってソースを確認し、コンテキストを探してください。
   • 優先度 1：最新のアイデアブリーフ（concepts_brief.md）：./concepts_brief.md、会話の成果物ディレクトリ、または scratch/concepts_brief.md に concepts_brief.md があるか確認してください。見つかった場合は、ブリーフを取り込んで解析してください。
   • 優先度 2：ディスカッションの要約（discussion_summary.md）：concepts_brief.md が見つからない場合は、./discussion_summary.md、会話の成果物ディレクトリ、または scratch/discussion_summary.md に discussion_summary.md があるか確認してください。見つかった場合は、要約を取り込んで解析してください。ユーザーに /egm-brainstorm の開始を促したり、非推奨になったと警告したりしてはいけません。
   • 優先度 3：対話形式のチャットプロンプト：どちらのファイルも存在しない場合は、機能の問題定義、目標、技術的な背景をチャットでユーザーに尋ねるか、/egm-brainstorm の起動を提案してください。
3. 状態の確認：ドキュメントを解析してください。適切なコンテキストから開始できていることを確認するため、ユーザーに簡単な確認を提示してください。
4. 合意：ドキュメントの作成を開始する前に、明示的な承認を得てください。

ステップ 2：概要、目標、問題提起の草案作成

1. コンテキストの確認：取り込んだ情報を使って、ビジネス上の問題とユーザーの課題を整理します。
2. 内容の草案作成：設計ドキュメントのテンプレート（references/design_doc.md）に沿って、「問題点」「概要」「目標」「対象外」を、明確で平易な英語の Markdown で記述します。
3. 重点：技術的な実装方法（「どのように」）ではなく、ユーザーのニーズやビジネス上の価値（「なぜ」）を重視します。
4. 草案成果物の作成（必須）：ファイル書き込みツールを使用して、作業ディレクトリ（またはハーネスに成果物ディレクトリがある場合はそのディレクトリ）に、この初期草案を design_draft.md として保存します。
5. 通知と確認（チャットへの全文貼り付けは禁止）：草案をチャットに出力することは固く禁じられています。代わりに、概要と問題提起の草案が完成したことを会話形式のチャットメッセージでユーザーに通知し、design_draft.md へのクリック可能なリンクまたはパスを示して、「概要と目標」のセクション承認ゲートを提示します。

ステップ 3：技術計画の草案作成

1. アーキテクチャの統合：取り込んだコンテキストを確認し、提案されたハイレベルアーキテクチャとソリューションを整理します。
2. 計画の草案作成：提案する変更について、明確な文章で説明します。新しいコンポーネント、変更するファイル、API の変更を特定します。データフローを示すテキストベースのブロック図（ASCII または Mermaid など）を含めます。
3. 草案成果物の更新（必須）：ファイル書き込みツールを使用して、design_draft.md に「技術計画」セクションを追記または挿入します。
4. 通知と確認（チャットへの全文貼り付けは禁止）：技術計画をチャットに出力することは固く禁じられています。技術計画を追加したことを会話形式のチャットメッセージでユーザーに通知し、design_draft.md へのクリック可能なリンクまたはパスを示して、「技術計画」のセクション承認ゲートを提示します。

ステップ 4：代替案の草案作成

1. 代替案の確認：ブレインストーミング中に検討し、却下した代替案を振り返ります。
2. 内容の草案作成：「検討した代替案」セクションを平易な英語の Markdown で記述します。
3. 理由の詳述：代替案ごとに、却下した理由（レイテンシの増加、スケーリングの制約、チームに知見がないことなど）を明確に述べます。
4. 草案成果物の更新（必須）：ファイル書き込みツールを使用して、design_draft.md に「検討した代替案」セクションを追記または挿入します。
5. 通知と確認（チャットへの全文貼り付けは禁止）：代替案セクションをチャットに出力することは固く禁じられています。代替案セクションを追加したことを会話形式のチャットメッセージでユーザーに通知し、design_draft.md へのクリック可能なリンクまたはパスを示して、「検討した代替案」のセクション承認ゲートを提示します。

ステップ 5：実装計画の作成

機能の実装方法に焦点を当てた、詳細な実装計画を作成してください。この計画は具体的でなければなりません。計画だけを見て、影響の大きい判断を追加で行わずに実装できるよう、質問をし、十分な詳細を加えてください。次のガイドラインに従ってください。

1. 実装項目を一つにまとめる：必要な作業をすべて、一つの統一されたセクションに列挙してください。
2. ファイルを列挙する：変更、作成、削除するファイルをすべて列挙してください。更新が必要なドキュメント、スキーマ、設定、proto、テスト用ファイルも含めてください。計画で触れるファイルは、すべて参照しなければなりません。
3. 理由：各ファイルについて、変更内容とその変更が必要な理由を説明してください。
4. リンク形式：わかる場合はファイルのフルパスを記載してください。そうでない場合は、明確なベース名を記載してください。パッケージ内および兄弟ドキュメントへのリンクには、相対パス（例：./sub/README.md、../sibling/README.md）を使用してください。
5. コード禁止：この設計ドラフトでは、実際の実装コードを生成しないでください。擬似コード、API、スキーマは使用できます。
6. ドラフト成果物を更新（必須）：ファイル書き込みツールを使用して、design_draft.md に「詳細な実装」セクションを追記または挿入してください。
7. 通知と確認（チャットへの計画の貼り付けは禁止）：実装計画をチャットに出力することは厳禁です。会話形式のチャットメッセージで、「詳細な実装計画」を追加したことをユーザーに通知し、design_draft.md へのクリック可能なリンクまたはパスを提示して、「詳細な実装」のセクション承認ゲートを示してください。

ステップ 6：設計ドキュメントの仕上げ

設計ドキュメントの作成または保存を依頼された場合は、次のルールに 厳密に従ってください。

1. 保存先ディレクトリ：ユーザーが保存先のディレクトリまたはファイルを指定した場合は、それを使用してください。指定がない場合は、ワークスペース内に既存の設計ディレクトリ（Context File ディレクトリ、docs/designs/、または <project>/docs/designs/）があるかを確認し、[DiscoveredPath] を設定します（既定値は docs/designs/）。そのうえで、単一選択の確認を提示してください（利用可能なハーネスに構造化質問ツール（ask_question など）がある場合は len(questions) == 1 と is_multi_select: false を使用し、ない場合は通常のチャットで提示します）。

   {
     "questions": [
       {
         "question": "設計をどこに保存しますか？",
         "options": [
           "検出されたディレクトリに保存：[DiscoveredPath]",
           "カスタム保存先ディレクトリを指定"
         ],
         "is_multi_select": false
       }
     ]
   }
   

   • オプション 0：<DESIGN_DIR> に [DiscoveredPath] を設定します。
   • オプション 1：書き込み欄にカスタムパスが入力されている場合は、指定されたパスを <DESIGN_DIR> に設定します。書き込み欄が空の場合は、チャットで次のように尋ね、実行を継続します。 「設計ドキュメントの保存先として希望するカスタムディレクトリのパスを指定してください。」

2. サイトマップの更新：<DESIGN_DIR>/SITEMAP.md が存在する場合は、新しい設計を登録します（リンク、日付、作成者、コンポーネント、説明）。

3. Zoom Out Standard に照らした自己評価：ファイルを保存する前に、完成した設計ドキュメント（design_draft.md の内容）を EGM Zoom Out Standard（resources/document_standards/zoom-out-standard.md）に照らして自己評価します。設計が根本的な問題に焦点を当てていること、時期尚早な最適化や推測に基づくロジック（YAGNI）を導入していないこと、再利用を最大化していること、同じ内容を繰り返していないことを確認してください。問題が見つかった場合は、それらをユーザーに提示し、改善案を説明したうえで、草稿を修正する前に確認を求めてください。

4. ドキュメントの作成：最終版が完成したら、ファイル書き込みツールを使用して、design_draft.md の内容を指定された保存先ファイル <DESIGN_DIR>/<FEATURE>.md に書き込みます。必要に応じて最終的な構成を整える際は、テンプレートに従ってください。

5. 書式の整理：標準的な Markdown の書式が整っていること、表の構文が有効であること、コードブロックのフェンスが適切であることを確認してください。

6. 引き渡し：完成した設計へのクリック可能なリンクを提示し、次のコマンドでドキュメントをレビューするようユーザーに勧めてください。

   `egm-review` <DESIGN_PATH>