| name | feature-request |
| description | 人間 / 他 Skill からの新機能要求を入力に要件 (REQ-NNN) と基本設計 / 詳細設計 (SPEC-NNN-basic / -detail)
を起草し、単一 PR スコープなら plan-author、複数 PR スコープなら epic-author を呼んで Plan / Epic
起票で完結する Spec Gen 専任 Skill。実装には踏み込まず、コード断片を docs/requirements /
docs/specifications 本文に書かない (§4.6 コード禁止原則)。Plan / Epic 起票後は
implementation-workflow にバトンタッチする。
|
| status | active |
| phase | A3 |
| last_updated | "2026-05-18T00:00:00.000Z" |
| related_plan | docs/harness/plan.md §4.6 / §5.3 / §5.4 / §6.2 A3 |
| related_rules | [".claude/rules/docs-structure.md",".claude/rules/plan.md",".claude/rules/epic.md",".claude/rules/adr.md",".claude/rules/template-language.md",".claude/rules/markdown.md",".claude/rules/mcp-usage.md",".claude/rules/pii.md",".claude/rules/secrets.md"] |
| related_adrs | ["ADR-0017","ADR-0018","ADR-0025","ADR-0027"] |
feature-request
5 行以内 summary: 人間 / 他 Skill からの新機能要求を入力に、要件定義 (REQ-NNN) → 基本設計
(SPEC-NNN-basic) → 詳細設計 (SPEC-NNN-detail) を順に起草し、単一 PR スコープなら
plan-author、複数 PR スコープなら epic-author を呼んで Plan / Epic 起票で完結する
Spec Gen 専任 Skill。実装には一切踏み込まず、Plan / Epic 起票後は implementation-workflow
にバトンタッチする。コード断片を設計書本文に書かない (§4.6 コード禁止原則) を強制する。
役割
- Spec Gen 専任: 要件定義 → 基本設計 → 詳細設計 → (必要時) ADR の起草と、Plan / Epic 起票までを担当
- 実装委譲: 起票後の実装 PR 起票 / コード変更は
implementation-workflow に委譲 (本 Skill は Plan / Epic を残して終了)
- コード混入禁止の強制:
docs/{requirements,specifications}/** には Kotlin / SQL / Gradle DSL 等のコード断片を一切書かない (§4.6、.claude/rules/docs-structure.md 機械検証で A6 から CI 失敗扱い)
- Plan vs Epic の判定: 想定変更行数 / ファイル数 / 仕様波及範囲 / レビュー aspect の走り方 から単一 PR か複数 PR かを判定し、該当 Skill を呼ぶ
- ADR 起票判定: 要件定義 / 基本設計の中でアーキテクチャ的に不変な決定が発生したら
adr-author を呼ぶ (.claude/rules/adr.md §起票基準)
- 責務分離: 要件定義 (WHY / WHAT) と基本設計 (システム外形) と詳細設計 (モジュール責務) の境界を
.claude/rules/docs-structure.md §4.6.2 と §4.6.3-4.6.5 のテンプレに従って厳守
implementation-workflow / code-reviewer / pr-retrospective 等の後続 Skill とは責務が重複しない (本 Skill は Plan / Epic 起票で終了)。
入力
- 起動 prompt (人間または別 Skill から渡される): 新機能要求の文字列 (背景 / ターゲットユーザー / 達成したいこと / 制約)
- 関連 docs:
docs/README.md / docs/glossary.md / docs/codebase-map.md / 既存 docs/requirements/REQ-NNN-*.md / docs/specifications/{basic,detail}/SPEC-*.md / docs/adr/ADR-*.md
- 既存 Epic / Plan:
docs/epics/INDEX.md / docs/plans/INDEX.md で関連取り組みの有無を確認 (新規 REQ が既存 SPEC を補強するパターンを検出)
- Context7 MCP 結果: 既存ライブラリ依存に影響する要求の場合、Context7 で API / 制約を確認 (
.claude/rules/mcp-usage.md 準拠、AI hallucination 抑止)
- JetBrains MCP 結果 (該当時): 既存実装の対象モジュールを index 経由で特定 (
.claude/rules/mcp-usage.md 「手動 git grep より JetBrains MCP 優先」)
出力
docs/requirements/REQ-NNN-<slug>.md (常に生成): 機能要件 (FR) / 非機能要件 (NFR) / ユースケース概要 / AC を含む。docs/requirements/template.md 準拠、.claude/rules/docs-structure.md §4.6.3 主要セクションdocs/specifications/basic/SPEC-NNN-<slug>.md (該当時): システム構成 / 業務フロー / 画面遷移 / データモデル (論理) / 外部 I/F 一覧 / エラーケース / AC ↔ テストマップ。docs/specifications/basic/template.md 準拠、.claude/rules/docs-structure.md §4.6.4docs/specifications/detail/SPEC-NNN-<slug>.md (該当時): モジュール配置 / 主要クラスの責務 / 状態遷移 / シーケンス / データ構造 / 例外 / 設定値 / テストパターン。docs/specifications/detail/template.md 準拠、§4.6.5- Plan or Epic (常にどちらか):
plan-author または epic-author Skill を呼んで起票
- (該当時) ADR:
.claude/rules/adr.md 起票基準充足時に docs/adr/template.md を copy して docs/adr/ADR-NNNN-<slug>.md を直接起草 (本 Skill 自身が担当、adr-author Skill は A3 配下では未配置 / 将来配置後は呼び出しに切替予定)
- 副作用:
docs/requirements/INDEX.md 追記 (本 Skill が直接書く)docs/plans/INDEX.md or docs/epics/INDEX.md 追記 (plan-author / epic-author が書く)
- 本 Skill が生成しない: 実装コード、テストコード、Draft PR 自体 (Plan / Epic 起票後の実装 PR は
implementation-workflow 担当)
フェーズ別動作
Phase 1: 要求把握 + 関連 docs / ADR / SPEC 調査
- 起動 prompt を読み、要求の WHY (背景・目的) と WHAT (達成したい状態) を分離して把握
docs/README.md / docs/glossary.md / docs/codebase-map.md を Read してドメイン用語 / 主要パスを把握docs/requirements/INDEX.md / docs/epics/INDEX.md / docs/plans/INDEX.md を走査して 重複・関連する既存 REQ / SPEC / Epic / Plan を抽出- 既存 SPEC を補強する要求なら
related_specs で双方向リンクを張る前提でメモ、新規ドメインなら新規 SPEC-NNN を採番
- ライブラリ / API に依存する制約は Context7 MCP で公式 docs を確認、既存実装の対象モジュールは JetBrains MCP で index 経由 search
Phase 2: 要件起草 (REQ-NNN)
docs/requirements/template.md を copy して docs/requirements/REQ-NNN-<slug>.md を作成 (採番は docs/requirements/INDEX.md の連番).claude/rules/docs-structure.md §4.6.3 の 11 セクションを順に埋める:
- 概要 / 目的 / 背景 — 自然言語 5 行以内 + 表 (HOW を書かない)
- ステークホルダー / アクター — 表
- スコープ — 含む / 含まない の箇条書き 2 段
- ユースケース概要 — Mermaid
graph + UC 表 (UC 詳細フローは基本設計に委譲)
- 機能要件 (FR) — 表 (FR ID / 機能名 / 説明 / 優先度 must/should/could/won't / 関連 UC)
- 非機能要件 (NFR) — IPA 6 大項目に沿った表
- 制約 / 前提 — 箇条書き
- 用語定義 — 表 +
docs/glossary.md への参照
- トレーサビリティ — 表 (FR ID / 関連 SPEC / 関連 EPIC / 関連 PLAN / 関連 ADR)
- 受け入れ基準 (AC) — チェックリスト (AC-NN / 検証可能な条件)
- Open Questions — 表 (空でも見出しは残す)
- frontmatter は
.claude/rules/docs-structure.md §frontmatter 必須キー表 の「要件 (REQ-NNN)」行に準拠 (block 形式)
- 冒頭 5 行 summary を必置 (
> **5 行以内 summary**: ... 形式)
docs/requirements/INDEX.md に新規行を追記
Phase 3: 基本設計起草 (SPEC-NNN-basic、該当時)
- 生成判定: 要件に対する「システム全体像 / 構成 / 流れ」を文書化する必要があるか判断 (単純な文言修正 / 既存 UI のラベル変更等は SKIP 可、新機能 / 新 API / 新画面なら必須)
- 生成する場合は
docs/specifications/basic/template.md を copy して docs/specifications/basic/SPEC-NNN-<slug>.md を作成
.claude/rules/docs-structure.md §4.6.4 の 11 セクションを順に埋める:
- 概要 (5 行以内サマリ)
- システム構成 — Mermaid
graph LR + 表
- 機能一覧と要件マッピング — 表 (SPEC-ID / 機能名 / 関連 FR ID / 関連 AC ID)
- 業務フロー — Mermaid
sequenceDiagram で actor ⇄ system (クラス間呼び出し詳細は詳細設計に委譲)
- 画面遷移 — Mermaid
stateDiagram-v2 + 表
- データモデル (論理) — Mermaid
erDiagram + 表 (物理 DDL / *.sq の中身は書かない)
- 外部 I/F 一覧 — 表 (詳細リクエスト / レスポンス JSON は
docs/api/colormaster-api.yaml を SoT として参照)
- エラーケース / 例外パターン — 表 (try/catch の構文は書かない)
- 受け入れ基準 (AC) ↔ テストマップ — 表
- 関連 ADR / リスク — 箇条書き
- Open Questions — 表
- frontmatter は
related_requirements: [REQ-NNN] と related_detail: [SPEC-NNN-detail] を必置 (block 形式、.claude/rules/docs-structure.md §frontmatter 必須キー表 の「基本設計」行準拠)
- Mermaid 種別の使い分けは
.claude/rules/docs-structure.md §4.6.6 早見表を参照 (基本設計では graph / sequenceDiagram / stateDiagram-v2 / erDiagram を使用、gantt は roadmap 専用のため使わない)
Phase 4: 詳細設計起草 (SPEC-NNN-detail、該当時)
- 生成判定: 詳細設計は AI (implementation-workflow / code-reviewer) が消費する主要文書のため、基本設計を生成したら 原則として詳細設計も生成する (例外: 文書のみの追加 / glossary 拡張等で実装を伴わない場合は SKIP 可)
- 生成する場合は
docs/specifications/detail/template.md を copy して docs/specifications/detail/SPEC-NNN-<slug>.md を作成
.claude/rules/docs-structure.md §4.6.5 の 11 セクションを順に埋める:
- 概要 (5 行以内サマリ)
- モジュール / ファイル配置 — 表 (パス / 責務 / 関連 SPEC-ID / 関連
.claude/rules/) + Mermaid graph TD
- 主要クラスの責務 — 表 (クラス名 / 種別 / 責務 / 保持する状態 / 主要メソッドの責務、シグネチャ / 引数型 / 擬似コードは書かない)
- 状態遷移 — Mermaid
stateDiagram-v2 + 表
- シーケンス — Mermaid
sequenceDiagram でモジュール間呼び出し (メソッド本文の処理ステップ列挙は書かない)
- データ構造 (論理スキーマ) — 表 (型は論理 String / Long / Instant 等、Kotlin
data class 宣言 / SQL DDL は書かない)
- 例外 / リトライ / タイムアウト — 表
- 設定値 / 環境変数 — 表 (
.env の中身は書かない)
- テストパターン — 表 (テスト ID / 観点 / パターン / 関連 AC ID /
@Spec 予定 ID、テストコードは書かない)
- 関連 Plan / Epic / ADR / Rules — 箇条書き
- Open Questions — 表
- frontmatter は
related_requirements: [REQ-NNN] と related_basic: [SPEC-NNN-basic] を必置 (block 形式)
- 基本設計 ⇄ 詳細設計のペア整合性 (basic 側の
related_detail と detail 側の related_basic が双方向に成立) は機械検証 (A6) で担保されるため、起草時に必ず双方を更新
Phase 5: Plan / Epic 起票判定 + 該当 Skill 呼出
- 判定基準 (
docs/harness/plan.md §4.1 と .claude/rules/plan.md §Epic 昇格条件 を SoT とする):
- Plan (単一 PR スコープ): 想定変更ファイル数 ≤ 10 / 想定期間 ≤ 1 週間 / open question 想定なし / 単独 PR で完結見込み
- Epic (複数 PR スコープ): 想定変更ファイル数 > 10 / 想定期間 > 1 週間 / open question 想定あり / 仕様波及が複数 SPEC / 単独 PR で完結見込みが立たない (4 兆候のいずれかで Epic 検討、
.claude/rules/plan.md §Epic 昇格条件 4 行表)
- 迷ったら Plan で起票 (Plan は後から
status: promoted + promoted_to: EPIC-NNN で Epic に昇格可能、.claude/rules/plan.md §Plan ⇄ Epic ⇄ ADR の責務分離)
- Plan 起票:
plan-author Skill を呼ぶ (起動コマンド例: Skill skill="plan-author")、frontmatter type は要求種別 (feature-request / bug-fix / refactor / dependency-upgrade 等) に合わせる
- Epic 起票:
epic-author Skill を呼ぶ、5 ファイル (README / roadmap / open-questions / decisions / progress) を template から生成、docs/epics/INDEX.md 更新、起票直後に roadmap-tracker Skill が自動起動
- ADR 起票判定 (該当時): 要件 / 基本設計で「アーキテクチャ的に不変な決定」が発生したら
.claude/rules/adr.md §起票基準 (SPEC を超えるアーキテクチャ層の意思決定 / 撤回コストが高い / 他複数の判断に影響等、2 項目以上充足) に基づき docs/adr/template.md を copy して 本 Skill 自身が ADR を起草 (adr-author Skill は A3 配下では未配置のため、本 Skill が直接担当)。将来 adr-author Skill 配置後は呼び出しに切替予定
Phase 6: orchestrator または人間に handoff
- 生成した REQ-NNN / SPEC-NNN-basic / SPEC-NNN-detail / Plan or Epic のパスとサマリを print
- 本 Skill は実装 PR を起票しない: Plan / Epic 起票で完結し、orchestrator (cmux 並列実装監督) または人間に implementation-workflow 起動 をハンドオフ
- ハンドオフメッセージのテンプレ:
✅ feature-request 完了
- REQ: docs/requirements/REQ-NNN-<slug>.md
- SPEC (basic): docs/specifications/basic/SPEC-NNN-<slug>.md (該当時)
- SPEC (detail): docs/specifications/detail/SPEC-NNN-<slug>.md (該当時)
- Plan or Epic: docs/plans/PLAN-NNN-<slug>.md or docs/epics/EPIC-NNN-<slug>/
- 次のステップ: implementation-workflow を起動して Phase 0-9 を実行してください (orchestrator pane 委譲推奨)
- 本 Skill 自体は Phase 6 完了後に終了、Plan / Epic ファイルが残るのが成果物
Gotchas
- 実装に踏み込まない: 設計書本文 (
docs/{requirements,specifications}/**) にコード断片 (Kotlin / SQL / Gradle DSL / シェル等のフェンス付きコードブロック) を一切書かない (§4.6 コード禁止原則、A6 で Gradle カスタムタスクが CI 失敗にする)。例外として file_path:line 形式の参照は許容
- frontmatter 配列は block 形式: flow 形式
[A, B] は禁止 (.claude/rules/docs-structure.md §frontmatter 規約、A6 で reject)
- 冒頭 5 行 summary 必置: 各 docs の H1 直後に
> **5 行以内 summary**: ... を置く (R-32、A6 で機械検証)
- 見出しは日本語: ADR 0027 /
.claude/rules/template-language.md 準拠、固定セクション名 (Open Questions / Gotchas 等) は例外
- 基本設計 ⇄ 詳細設計のペア整合性: basic 側の
related_detail と detail 側の related_basic が双方向に成立、未生成側は frontmatter の該当キーを [] で空配列明示 (null と区別)
- REQ ⇄ SPEC ⇄ EPIC ⇄ PLAN ⇄ ADR の ID 参照は実在チェック対象: 参照する ID が
docs/{requirements,specifications,epics,plans,adr}/ に実在しなければ A6 機械検証で reject される
- 既存 SPEC との衝突回避: 採番前に必ず
docs/specifications/{basic,detail}/INDEX.md (または ls で列挙) で既存 SPEC-NNN を確認、新規エンティティなら新規連番、既存エンティティ補強なら既存 SPEC を更新 (新規採番しない)
- Plan vs Epic 判定は保守的に: 迷ったら Plan で起票し、後から
status: promoted + promoted_to: EPIC-NNN で昇格 (.claude/rules/plan.md §Epic 昇格条件)、Epic は撤回コストが高いため軽率に起票しない
- ADR 起票判定の閾値: SPEC を超えるアーキテクチャ的決定 / 撤回コストが高い決定 / 他複数の判断に影響する決定のみ ADR、それ以外は Epic の
decisions.md 追記 (.claude/rules/adr.md §起票基準)
- PII / Secrets の混入禁止: 起動 prompt に PII (実メール / 実 uid / IP 等) や Secrets (API key / token / Bearer / JWT 等) が含まれる場合、設計書本文に転載する前に
.claude/rules/pii.md / .claude/rules/secrets.md の redaction パターンで置換する。テスト fixture のダミーメールは @example.com 限定
- Mermaid の使い分け: 基本設計 =
graph / sequenceDiagram / stateDiagram-v2 / erDiagram、詳細設計 = graph TD / sequenceDiagram / stateDiagram-v2、roadmap.md 専用の gantt は設計書では使わない (§4.6.6 早見表)
- plan-author / epic-author の呼び分けミス防止: 単一 PR スコープを epic-author で起票すると Epic ディレクトリが過剰生成され撤回困難。複数 PR スコープを plan-author で起票するとロードマップ追跡対象外 (R-34) になり進捗可視化が機能しない
- コード断片混入の典型パターン: 「擬似コード」「サンプル」「実装例」と称した Kotlin / SQL 等の断片は全て本 Skill の禁止対象、責務 / 制約 / I/O 表現を自然言語と Mermaid と表で記述する
- 詳細設計テストパターン表の
@Spec 予定 ID は placeholder: Phase 4 テストパターン表 (.claude/rules/docs-structure.md §4.6.5 #9) に書く @Spec 予定 ID は本 Skill 起草時点では暫定値 (SPEC-NNN-N の候補)、実際の Kotlin 側 @Spec annotation は implementation-workflow Phase 3 で確定する。SPEC ID 名称変更が発生したら spec-living-sync.md §同期パターン分類 (docs 軽微訂正) で同 PR 内で詳細設計側を更新する
adr-author Skill 未配置のため ADR 起草は本 Skill 直接: A3 配下では adr-author Skill 未実装 (実体ファイルなし)、.claude/rules/adr.md §起票基準 充足時は本 Skill が docs/adr/template.md を copy して直接起草する。adr-author を将来配置するときは関連 ADR (例: A3 後続 PR) で「呼び出しに切替」を明示docs/requirements/INDEX.md が未存在の場合は初回起動時に作成: 採番 (REQ-001 等) の起点として INDEX.md を新規作成し、ヘッダ行 (| REQ-NNN | タイトル | type | status | related_epic | 起票日 | 形式) + 自 REQ-NNN 行を追記する
関連
- ADR 0017 (ローカルポーリング駆動、Skill 起動契機)
- ADR 0018 (Skill 駆動 KPT ループ、6 段階フローの Spec Gen 担当)
- ADR 0025 (Skill 作成は
example-skills:skill-creator 経由、本 Skill 自体も rubric 評価対象)
- ADR 0027 (docs 構造 + 命名規約 + 5 行 summary + 日本語化 + コード禁止原則)
docs/harness/plan.md §4.6 (設計書 3 種類の責務分担 + テンプレ + コード禁止原則)docs/harness/plan.md §5.3 (Skill 責務一覧、本 Skill の行)docs/harness/plan.md §5.4 (6 段階ループ、Spec Gen フェーズの位置づけ)docs/harness/plan.md §6.2 A3 (本 Skill 本格化フェーズ).claude/skills/plan-author/SKILL.md (Plan 起票責務、本 Skill が呼ぶ).claude/skills/epic-author/SKILL.md (Epic 起票責務、本 Skill が呼ぶ).claude/skills/implementation-workflow/SKILL.md (Plan / Epic 起票後のバトンタッチ先).claude/rules/docs-structure.md (要件 / 基本設計 / 詳細設計 テンプレ + frontmatter 規約 + Mermaid 早見表).claude/rules/{plan,epic,adr,template-language,markdown,mcp-usage,pii,secrets}.md
