Design Feature

抽象的な要求から、実装可能な粒度の「実装マスタ（01）」と、非開発者の関係者向けの「システム要件書（02）」をペアで作る。AGENTS.md の Phase 0-2（準備・調査・計画）にあたり、実装は /plan-feature-prs に引き継ぐ。

AskUserQuestion が無い環境では、番号付き選択肢のテキスト質問で代える。

出力物

ファイル	内容	読み手
01_requirements_skeleton.md	実装マスタ。What + How。DBスキーマ / API / Usecase / ガード / 影響範囲 / 設計理由	実装担当
02_system_requirements.md	システム要件書。What のみ。Why は注記程度	企画・事業側 / 連携先 / サポート担当

01 を正本とし、02 は 01 から抽出する。保存先の既定は ${MEMORY_DIR}/memory/YYMMDD_<context_name>/（形式は context/memory-file-formats.md）。

ワークフロー

Step 1: 準備           → メモリディレクトリ・作業項目
Step 2: 要求深掘り     → AskUserQuestion で目的・スコープ・制約を確定
Step 3: 既存実装調査   → コードベースを正本として関連実装を把握
Step 4: 01 ドラフト     → 実装マスタを章別に書く
Step 5: 外部レビュー   → Action Required 0 まで反映
Step 6: 02 抽出         → 01 から What だけ抽出して書き、完了報告

各 Step の具体手順は references/workflow-detail.md。01・02 のテンプレートは references/doc-templates.md、禁止フレーズ・整合性チェック・完了基準は references/quality-checklist.md。

規則

1. 既存実装の正本はコードベース

• メモリディレクトリ内の資料は古い可能性がある。事実を書く前に実コードで確かめる
• Explore agent の報告は、結論を左右する箇所を Read で突き合わせてから採用する
• 公式仕様は context7 / WebSearch で確かめる

2. 禁止フレーズ

01・02 のどちらにも次を書かない。

要調査 / TBD / TODO / 要確認 / 要検討 / 追って確認 / 別途決定 / 要相談 / 場合によっては / 必要に応じて

書きたくなったら、Step 3 で情報を揃えるか、AskUserQuestion で確定する。

3. 設計判断は中長期の最適で決め、確認が要るものだけ AskUserQuestion で確定する

• 複数案がある設計判断は、AGENTS.md「進め方の既定」のとおり中長期の最適で自分で決める（今回の工数や差分の大きさを理由にしない）
• 日程・金額・対外コミュニケーションが絡む、既存パターンから外れる、スコープを縮める、要件の原文から一意に決まらない、のどれかに当たる判断は自分で決めず AskUserQuestion で確定する
• 採用案・不採用案・理由をセットで 30_decisions.md か 99_history.md に記録する

4. 文体

/ukwhatn-writing に従う（常体・宣言形・翻訳調を避ける・専門用語は原語と `code`）。

5. 既存パターンを踏襲する

プロジェクトの既存規約・命名・レイヤー構成から外れるなら AskUserQuestion で確かめる。

6. 識別子・用語は正式名称で書く

• システム上の識別子（非同期ジョブのキュー名・定期実行のジョブ名・enum 値・procedure 名）は実装から抽出した正式名称で書く。独自の通称・意訳を作らない
• 外部システムの操作は先方の正式 API 名で書く（例: 「<操作の通称>」ではなく「<操作名>（<外部APIの正式名>）」）
• データ項目は既存スキーマのフィールドと対応させる。スキーマに無い概念語を持ち込まない

7. 一覧は定義箇所の全件 grep で作る

• 非同期ジョブ・定期実行・Webhook・API 等の一覧表は、定義箇所のファイルを全件 grep してから作る
• 部分列挙なら「一部抜粋」と書く。grep のコマンドと件数を05_log.md に記録する

8. 既存実装に追従させる

• 新しいアクターの挙動は、類似する既存アクターの現状動作を実コードで調べ、追従させるのが原則。対応表を01に書く
• 既存実装のガード漏れ・不統一に見えるものを「バグ」「統一修正対象」と決めつけない。意図した設計の可能性を AskUserQuestion で確かめる
• 既存挙動の変更・広範囲のリファクタはスコープに入れない。必要だと思ったら「後続フェーズ」として分けて示す

9. 状態変更は内部表現まで特定する

• 「無効化」「失効」等の状態変更は、どのフィールド・enum 値で記録するかまで01で特定する（例: <enumフィールド> = "<値>"）
• 流用できる既存関数があれば01に関数名を書く（例: <既存関数名> を流用）。02では「既存処理を流用」程度に留める

10. 要件の語彙で設計を組み立てない

• 互換・移行・外部連携・規制対応など外部制約を満たす機能でも、成果物は自システムの第一級機能として設計・命名する
• 制約は仕様（fixtures・規範ルール・契約文書）として自立させ、制約元（旧システム・相手システム・規格書）の語彙・構造を設計書の骨格や実装の識別子にしない。制約元への言及は仕様書・ADR の背景節だけに置く
• 01の完成前に、章立て・用語が制約元との対応を骨格にしていないかを見る（対応表は根拠資料として分け、01本文は自システムの語彙で書く）

Step 別の要点

Step 1: 準備

1. MEMORY_DIR を確かめる（未定義なら .local/）
2. 既存のメモリディレクトリを探し、同じコンテキストなら再利用する。新規なら ${MEMORY_DIR}/memory/YYMMDD_<context_name>/ を作る
3. 05_log.md を初期化または追記し、ユーザーの指示を逐語で記録する。冒頭にメモリディレクトリの絶対パスを書く（worktree に移っても書き込み先を誤らないため）
4. 関連する過去タスク・issue を /findmem で探す
5. Step 2〜6 を作業項目として登録する（taskboard が繋がっていれば /taskboard、Codex は plan 機構）

Step 2: 要求深掘り

次の7項目のうち、依頼文から一意に読めないもの（特にスコープ境界・対外影響・スケジュール・金額）だけを AskUserQuestion で確定する。読めた項目は、推定した内容を05_log.md に書いて進む。

1. 目的・解決したい問題: なぜ作るのか
2. 対象ユーザー / アクター: 誰が使うか、誰が影響を受けるか（運用者 / 連携先 / エンドユーザー）
3. スコープの境界: やる / やらない。「全件」「全連携先」等は文字どおり全件
4. 既存機能との関係: 新規 / 拡張 / 置換 / 共存
5. 制約: スケジュール、依存サービス、法的制約、運用制約
6. 成果物の保存先: 既定は上記。指定があれば従う
7. 既知バグの取り込み: 機能追加と同時に既知バグを直すか

質問の粒度とテンプレートは references/workflow-detail.md「Step 2」。

Step 3: 既存実装調査

調査観点:

• 対象機能に関連する既存コードの場所・パターン
• データモデル（DB スキーマ、Domain 型）
• 既存 API / Usecase / Service / Repository / Adapter
• 既存ガード・エラーパターン
• 命名規約・テンプレート・規約同意・通知メールの既存実装
• 非同期ジョブ・定期実行・Webhook の関連エンドポイント
• 影響範囲（同類画面・同類 procedure）

調査手段:

• Agent tool で subagent_type: "Explore"・model: "sonnet" を3〜5並列で起動し、ファイル・関数を洗い出す（Explore は書き込まず結果を返すだけなので、pane でなく Agent tool を使う。context/delegation.md「経路の選択」）
• 公式仕様は context7 / WebSearch で確かめる

並列調査のパターンは references/workflow-detail.md「Step 3」。

Step 4: 01 ドラフト作成

実装可能な粒度で What + How を書く。章構成はプロジェクトに合わせて調整してよい（テンプレートは references/doc-templates.md「01実装マスタ」）。

章別の並列ドラフトは、ユーザーが ultracode の語を使ったか並列化を明示したときだけ Workflow で行う（references/workflow-detail.md「並列化」）。

Step 5: 外部レビュー

01 を外部レビューに出す（手順・Severity 別の判断・打ち切り条件は context/agent-cli-guide.md）。指摘を反映する前に、実コードで事実を確かめる。後続フェーズで足す内容を「現状に無いから差異」と誤判定する指摘が出やすい。

Step 6: 02 抽出と完了報告

01 から What だけを抽出して 02_system_requirements.md を書く。

書く	書かない
機能の存在・挙動・入出力	クラス名・関数名・ファイルパス・行番号
状態遷移・分岐条件	Usecase / Service / Repository / Adapter の構造
API レスポンス・scope / claim 名	DB のテーブル名・カラム名（最小限なら可。極力避ける）
画面遷移の概要	Procedure / queue key / DI 構造
エラーコード（仕様レベル）	エラーメッセージキー・ステータスマッピングの詳細
Why は注記程度（1〜2行、「※」「→」）	Why の詳細な設計理由

形式は既存フェーズのシステム要件書に揃える（章番号・箇条書き中心・サブセクション X.Y / X.Y.Z・表は最小限）。テンプレートは references/doc-templates.md「02システム要件書」。

完了報告には次を書く。

1. 作成したファイルのフルパス
2. 主要な設計判断のサマリ
3. 外部レビューの結果（ラウンド数・Action Required の件数）
4. 残課題（あれば。「要調査」と書かず、具体的な次の行動として書く）

完了の条件は references/quality-checklist.md「完了基準」。