Skip to content

ChocoWork/speckit

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
.github
.github
 
 
docs/sdd
docs/sdd
 
 

Repository files navigation

AI Delivery Kit for Next.js + Supabase (MCP Required)

このディレクトリは、AI支援開発を SDD (Specification-Driven Development) と TDD (Test-Driven Development) で運用するためのテンプレート群です。
対象スタックは Next.js + React + TypeScript + Supabase で、Next.js/Supabase 関連作業は MCP 経由を前提にします。

1. 何が入っているか（役割の全体像）

  • agents/: 実行主体の役割定義（誰が何を担当するか）
  • instructions/: 全体ルール・禁止事項・品質基準（守るべき規約）
  • prompts/: タスク入力テンプレート（毎回の依頼フォーマット）
  • skills/: 再利用可能な手順パッケージ（標準作業手順）

役割分担の原則:

  • agents は「実行責務」を定義
  • instructions は「逸脱不可ルール」を定義
  • prompts は「入力/出力契約」を定義
  • skills は「手順の再利用」を定義

2. フォルダ構成

.github/
  agents/
    discovery-facilitator.agent.md
    requirements-analyst.agent.md
    specification-writer.agent.md
    research-analyst.agent.md
    feature-planner.agent.md
    test-designer.agent.md
    feature-implementer.agent.md
    quality-reviewer.agent.md
    release-orchestrator.agent.md
  instructions/
    discovery.requirements.instructions.md
    project.guardrails.instructions.md
    sdd.workflow.instructions.md
    tdd.quality-gates.instructions.md
  prompts/
    discovery-wall-batting.prompt.md
    requirements-definition.prompt.md
    specification-from-requirements.prompt.md
    research-from-codebase.prompt.md
    plan-from-research.prompt.md
    implement-from-approved-plan.prompt.md
    review-against-criteria.prompt.md
  skills/
    discovery-to-research-handoff/
      SKILL.md
    feature-delivery/
      SKILL.md
    mcp-preflight/
      SKILL.md
    test-evidence-mapping/
      SKILL.md

3. 各ファイルの概要

agents/

  • discovery-facilitator.agent.md
    壁打ちで課題・価値仮説・制約・未確定事項を構造化します。
  • requirements-analyst.agent.md
    discovery成果を要求仕様/要件定義（ACC付き）へ落とし込みます。
  • specification-writer.agent.md
    要件から実装可能な仕様を作成し、Researchへ引き継ぎます。
  • research-analyst.agent.md
    調査専任。research.md を作成し、仮説と検証タスクを定義します（実装は禁止）。
  • feature-planner.agent.md
    調査結果から plan.md / todo.md を生成します（実装は禁止）。
  • test-designer.agent.md
    plan.md / todo.md から TDD 用テスト設計（test-plan.md）を作ります。
  • feature-implementer.agent.md
    承認済み plan/todo を実装。TDD順序、MCP制約、型安全、hotfix例外ルールを適用します。
  • quality-reviewer.agent.md
    受け入れ観点で品質判定（ゲート合否、重大度別指摘、対応アクション）。
  • release-orchestrator.agent.md
    CI結果と証跡に基づき Go/No-Go 判定、監視/ロールバック観点を整理します。

instructions/

  • discovery.requirements.instructions.md
    壁打ち→要件定義→仕様化→Research引き継ぎまでの運用ルール。
  • project.guardrails.instructions.md
    全体ガードレール（SDD/TDD順序、MCP必須、セキュリティ、品質ゲート、hotfix例外）。
  • sdd.workflow.instructions.md
    仕様駆動フロー（research/plan/todo の品質要件と完了条件）。
  • tdd.quality-gates.instructions.md
    TDD契約、証跡契約、CI閾値、失敗時ポリシー。

prompts/

  • discovery-wall-batting.prompt.md
    壁打ちで論点を引き出し discovery.md を作るテンプレ。
  • requirements-definition.prompt.md
    discovery.md から requirements.md を作るテンプレ。
  • specification-from-requirements.prompt.md
    requirements.md から spec.md を作り Research へ接続するテンプレ。
  • research-from-codebase.prompt.md
    深い調査を指示して research.md を作るテンプレ。
  • plan-from-research.prompt.md
    承認済み調査から plan.md / todo.md を作るテンプレ。
  • implement-from-approved-plan.prompt.md
    承認済み計画を実装し、証跡まで返すテンプレ。
  • review-against-criteria.prompt.md
    受け入れ基準と品質ゲートに対するレビュー用テンプレ。

skills/

  • discovery-to-research-handoff/SKILL.md
    壁打ち〜仕様化を進め、Researchへ引き継ぐ標準手順。
  • feature-delivery/SKILL.md
    Research→Plan→Implement を TDD付きで進める標準手順。
  • mcp-preflight/SKILL.md
    MCP接続/権限/運用モードの事前診断手順。
  • test-evidence-mapping/SKILL.md
    受け入れ基準とテスト証跡のトレーサビリティ作成手順。

4. 使い方（アパレルブランドECサイト実例）

ここでは「アパレルブランドECサイトの新機能: 春コレクション特集ページ + お気に入り保存」を例に、どの順番で何を使うかを示します。

  1. 壁打ち（Discovery）
  • 使用: discovery-facilitator.agent.md + discovery-wall-batting.prompt.md
  • 目的: 誰の何を改善するかを明確化（例: 回遊率・お気に入り登録率の改善）
  • 出力: docs/sdd/discovery.md
  1. 要求仕様・要件定義
  • 使用: requirements-analyst.agent.md + requirements-definition.prompt.md
  • 目的: 機能要件/非機能要件/ACCを確定
  • 出力: docs/sdd/requirements.md
  1. 仕様化（Research前の契約化）
  • 使用: specification-writer.agent.md + specification-from-requirements.prompt.md
  • 目的: ユースケース、認可、エラーパス、MCP制約を仕様として固定
  • 出力: docs/sdd/spec.md
  1. Research連携
  • 使用: discovery-to-research-handoff skill + research-analyst.agent.md + research-from-codebase.prompt.md
  • 目的: 仕様で定義した調査対象をコードベース調査へ接続
  • 出力: docs/sdd/research.md
  1. Plan作成
  • 使用: feature-planner.agent.md + plan-from-research.prompt.md
  • 目的: 実装計画とタスク分解を確定
  • 出力: docs/sdd/plan.md, docs/sdd/todo.md
  1. Test設計（TDD前提）
  • 使用: test-designer.agent.md
  • 目的: ACCとTSを対応づけ、失敗系を先に定義
  • 出力: docs/sdd/test-plan.md（必要に応じて追加運用）
  1. Implement / Review / Release判定
  • 使用: feature-implementer.agent.md → quality-reviewer.agent.md → release-orchestrator.agent.md
  • 目的: Red→Green→Refactorで実装し、品質ゲートでGo/No-Goを判断

5. 動作シーケンス（Mermaid, アパレルEC実例）

sequenceDiagram
  autonumber
  participant U as Product/Dev
  participant DF as discovery-facilitator
  participant RAQ as requirements-analyst
  participant SW as specification-writer
  participant RH as discovery-to-research-handoff
  participant RS as research-analyst
  participant FP as feature-planner
  participant TD as test-designer
  participant FI as feature-implementer
  participant QR as quality-reviewer
  participant RO as release-orchestrator
  participant CI as CI/Quality Gates

  U->>DF: 春コレ特集 + お気に入り機能の課題を共有
  DF-->>U: discovery.md（課題/価値仮説/制約/未確定）

  U->>RAQ: discovery.mdを入力
  RAQ-->>U: requirements.md（FR/NFR/ACC）

  U->>SW: requirements.mdを入力
  SW-->>U: spec.md（ユースケース/認可/エラーパス）

  U->>RH: specからResearch引き継ぎ整理
  RH-->>RS: 調査対象と仮説を連携
  RS-->>U: research.md（コード実態/リスク/検証）

  U->>FP: research承認後に計画依頼
  FP-->>U: plan.md + todo.md

  U->>TD: ACCを入力してテスト設計
  TD-->>U: test-plan + TS対応

  U->>FI: 承認済みplan/todoで実装依頼
  FI->>CI: Red->Green->Refactor + 継続検証
  CI-->>FI: lint/type/unit/integration/security結果
  FI-->>U: 実装差分 + 証跡 + todo更新

  U->>QR: 受け入れレビュー依頼
  QR-->>U: 合否判定 + 是正事項

  U->>RO: リリース候補を判定依頼
  RO-->>U: Go/No-Go + 監視/ロールバック観点
Loading

6. 運用ルール（実例ベース）

6.1 前提条件

  • Next.js / Supabase 関連作業は MCP 経由で実行する
  • docs/sdd/ 配下の6ドキュメントを1機能ごとに更新する
  • ACC採番規則（例: ACC-001）を先に決める

6.2 品質ゲート最低ライン

  • lint
  • typecheck
  • unit tests
  • integration tests
  • security checks

6.3 例外運用（hotfix）

  • 事故レベル対応時のみ
  • Tech Lead on-call + Security on-call の二者承認
  • 緊急ミニプラン作成後に実装
  • 24時間以内に不足証跡を追補

6.4 トレーサビリティ

  • ACC-* → TS-* → CI結果 の対応表を維持
  • 証跡不足の場合は No-Go

6.5 ステータス管理

  • discovery / requirements / spec / research / plan / todo の各ファイルでチェックボックス管理
  • 完了条件は各ファイル内の Status Checklist を基準とする

7. よくある失敗と回避策（アパレルEC実例）

  • 失敗: 季節キャンペーン要件を固める前に実装開始
    回避: discovery と requirements のチェックボックス完了まで実装禁止
  • 失敗: 商品公開条件とRLSを後回しにして手戻り
    回避: spec段階で認可ルールを先に固定し、Researchで実装実態を検証
  • 失敗: ACCとテスト証跡が分離してレビュー差し戻し
    回避: test-evidence-mapping で ACC/TS/CI の紐づけを先に作成

8. クイックスタート（アパレルEC機能 1サイクル）

  1. discovery-wall-batting.prompt.md で docs/sdd/discovery.md を作成
  2. requirements-definition.prompt.md で docs/sdd/requirements.md を作成
  3. specification-from-requirements.prompt.md で docs/sdd/spec.md を作成
  4. research-from-codebase.prompt.md で docs/sdd/research.md を作成
  5. plan-from-research.prompt.md で docs/sdd/plan.md / docs/sdd/todo.md を作成
  6. feature-implementer と quality-reviewer で実装・判定

この順序を守ることで、壁打ちから実装までの判断が一貫し、手戻りを抑制できます。

9. 具体例: 春コレクション特集 + お気に入り保存

9.1 ゴール

  • 新作特集ページの閲覧導線を強化し、回遊率を上げる
  • ログインユーザーがお気に入り登録し、後で購入検討できる

9.2 受け入れ基準（例）

  • ACC-001: 特集ページに対象商品だけが表示される
  • ACC-002: ログインユーザーはお気に入り登録/解除できる
  • ACC-003: 未ログイン時はお気に入り操作が拒否される
  • ACC-004: 在庫切れ商品の表示ルールが仕様通り適用される

9.3 どのファイルをどう使うか（実務手順）

  1. docs/sdd/discovery.md にキャンペーン背景、KPI仮説、制約を記載
  2. docs/sdd/requirements.md に FR/NFR と ACC を確定
  3. docs/sdd/spec.md に商品表示条件、認可、エラーパスを記載
  4. docs/sdd/research.md で既存商品取得APIとRLSを調査
  5. docs/sdd/plan.md / docs/sdd/todo.md で実装順序を固定

10. SDDドキュメント配置

  • docs/sdd/discovery.md
  • docs/sdd/requirements.md
  • docs/sdd/spec.md
  • docs/sdd/research.md
  • docs/sdd/plan.md
  • docs/sdd/todo.md

1機能につき、上から順に更新します。

11. Discovery→Requirements→Spec→Research 連携フロー

  1. discovery-wall-batting.prompt.md + discovery-facilitator.agent.md で discovery を確定
  2. requirements-definition.prompt.md + requirements-analyst.agent.md で requirements を確定
  3. specification-from-requirements.prompt.md + specification-writer.agent.md で spec を確定
  4. discovery-to-research-handoff skill で調査引き継ぎを生成
  5. research-from-codebase.prompt.md + research-analyst.agent.md で research 開始

各段階は、各ドキュメントの Status Checklist（チェックボックス）完了を進行条件とします。

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors