peach-gen-spec

Spec生成スキル

新機能を Spec主導開発 で進めるため、単一のSpecファイルを生成します。

目標の流れ：

peach-team-ui-proto
→ peach-gen-spec proto=<ui-proto 태스크 경로>
→ peach-gen-db spec=<생성된 Spec 경로>
→ peach-team-dev spec=<생성된 Spec 경로>
→ peach-team-e2e spec=<생성된 Spec 경로> [proto=<ui-proto 태스크 경로>]

基本原則

• Specは実装基準のSource of Truthです。
• PRDは考慮しません。入力文書がある場合も、それは元資料にすぎず、実装基準として従うのは最終Specに明記された内容だけです。
• 標準成果物は 単一の .md ファイル です。
• Specは、team-dev と team-e2e が追加の企画上の質問なしで進められるほど確定させます。
• team-* が独自に処理するテストコード、selector、fixture、suite内部の実装はSpecに記載しません。
• その代わり、TEST_IDごとの要件、完了基準、Backend TDD基準、Store/Contract基準、UI基準、E2Eシナリオを十分具体的に記載します。
• 状態コードは運用報告用に作成しません。ユーザーへの報告では平文（確定、実装完了、検証完了、ブロック）を優先します。
• 義務マトリクスは作成しません。権限／状態／エラー／外部依存関係はまず散文で記載し、分岐や規則が多く、表の方が明確な場合に限り表に拡張します。
• FK（Foreign Key）は作成しません。参照整合性はアプリケーションで処理します。
• test-data はコピー用の正解集ではなく、基準となる骨格です。後続の gen-*／team-* スキルは、Bounded Autonomyの範囲内でドメインに合わせて適応できます。
• Specの分量目標は250～450行です。短い場合は200行前後でも許容しますが、TDD／E2E基準は省略しません。
• ユーザーが 修正前の議論 を求めた場合、文書をすぐに修正せず、分析 → 推奨案 → ユーザー確認 → 文書反映 の順に進めます。AIは質問を乱発せず、合理的なデフォルト案を先に提示しますが、DB構造・状態遷移・外部連携・権限フローなど、後戻りしにくい判断についてはユーザーの確認を得ます。
• TDD／E2E基準をすべての要件について漏れなく埋める必要はありません。team-dev／team-e2eが自律的に補完できるよう、主要なビジネス遷移、保存結果、権限・所有権による拒否、代表的な失敗ケース のみを明記します。
• E2Eには 主要なユーザーフローのみ を記載します。開始データはシナリオ／suiteが直接準備し、同じフローが繰り返される場合は suiteの組み合わせ を優先します。単一シナリオの作成ルール（単一責任／再利用／独立実行）は peach-e2e-scenario、suite統合ルールは peach-e2e-suite がSoTです。
• 外部連携・認証・決済・ファイル・通知・mockデータがある場合は、環境ごとの動作（local/devでのmock許可の有無、prodで禁止する経路）を§5「権限・状態・エラー・外部依存関係」に散文で確定します。
• Specでは 検証可能性 を明記します。何を自動検証し、何が検証不能で、どこにシステム安全性のリスクがあるかを§5.5／§6／§12.5に分けて記載します。この定義が明確であれば、team-dev／team-e2eは自動化の対象領域とユーザー確認の対象領域を振り分けられます。

ファイル構造

docs/spec/{년}/{월}/[개발자아이디]-[YYMMDD]-[한글기능명].md

例：

docs/spec/2026/05/{개발자아이디}-260506-공지사항-게시판.md

開発者IDはまず whoami を使用し、失敗した場合は git config user.name を使用します。

成果物の構成

Part A: 一目でわかる概要

機能の本質をすばやく確認するためのセクションです。

セクション	方針
概要カード	必須。何を／誰が／主要なアクション／新規・変更テーブル／検証ポイント
主要フロー	推奨。ユーザーアクション1～3件のsequence diagram
データモデル	推奨。新規／変更テーブルのみをerDiagramで表現
追加ダイアグラム	任意。状態マシンや特殊なフローがある場合のみ

廃止：

• システムアーキテクチャ図：ピッチハーネスの標準構造であり、情報価値が低いです。
• UIフロー図：ui-protoが一次資料です。ui-protoがない場合はPart Bの画面基準表で代替します。

Part B: 確定Spec

team-dev、team-e2e、gen-db が優先して読む実行基準です。

セクション	方針	目的
メタ	必須	モジュール名、機能名、UIパターン、参照資料
1. 機能範囲	必須	CRUD、特殊アクション、ファイル／Excel／外部連携
2. 画面／アクション基準	必須	ui-protoに基づく画面、アクション、成功／エラー状態
3. DBスキーマ基準	必須	gen-dbがマイグレーションを作成できるカラム／インデックス／参照
4. API契約	必須	Backend／Store／Contractが合わせるリクエスト・レスポンス基準
5. 権限・状態・エラー・外部依存関係	必須	実装漏れの防止基準（5.5 システム安全性を含む）
6. TEST_ID要件	必須	要件、完了基準、検証レベル
7. Backend TDD基準	必須	テストコードではなく、検証すべき動作
8. Store/Contract基準	必須	APIレスポンスキーとStore状態の基準
9. UI実装基準	必須	画面状態、ボタン、トースト、検証メッセージ
10. E2Eシナリオ	必須	ユーザーフロー、入力、期待結果
11. ファイル／モジュール境界	必須	作成・変更対象のディレクトリ
12. 除外／禁止事項	任意	範囲外の機能と禁止する実装（12.5 検証不能領域を含む）
13. 参照	必須	ui-proto、schema、機能文書、ガイドコード

Specから除外するもの

項目	担当
テストコード、describe/itの詳細	peach-team-dev
selector、wait、fixture、suiteコード	peach-team-e2e
実行履歴、Ralph Loopの履歴	docs/qa/、docs/e2e-suite/
4軸ステータスマトリクス（S/U/I/V）	使用しない
PRDトレース表	使用しない

必須：DB種類の判定

スキルの実行時に、まず対象プロジェクトのenvファイルを読み、DBの種類を判定します。

api/src/environments/env.local.yml

DATABASE_URL に基づく判定：

URL	モード
postgresql://...	PostgreSQL
mysql://...	MySQL

型の基準：

用途	PostgreSQL	MySQL
PK	serial4	INT AUTO_INCREMENT
整数	int4	INT
大きな整数	int8	BIGINT
日時	TIMESTAMP	DATETIME
参照値	int4	INT

型マッピングのSoTは peach-gen-db/references/type-mapping.md です。変更時は両方を合わせて更新します。

入力シナリオ

シナリオ	入力引数	説明
ui-protoベース	proto=<ui-proto 태스크 경로>	推奨。確定した画面企画案からSpecを抽出
既存機能の改善	feature-docs=<경로> またはコンテキストの注入	peach-doc-featureの成果物を基準に変更Specを作成
自然言語／会話	なし	小規模な新機能について会話から情報を収集
DBドラフトの補強	schema=<경로>	既存のschema／DDL／ERDのドラフトも読み込み、DB基準を補強
議論／確定	ユーザーが「修正前に」「要点のみ」「方向性を確定してから修正」と依頼	文書をすぐに修正せず、分析・推奨案・確認質問のみを返す

実行形式：

/peach-gen-spec proto=<ui-proto 태스크 경로>
/peach-gen-spec proto=<ui-proto 태스크 경로> schema=<schema 또는 DDL 경로>
/peach-gen-spec feature-docs=<기능별설명 폴더>
/peach-gen-spec

ワークフロー

0단계：入力モードの分岐

proto=<경로> 있음        → ui-proto 기반 모드
feature-docs=<경로> 있음 → 기존 개선 모드
schema=<경로> 있음       → DB 초안 보강
인자 없음                → 자연어/대화 모드
사용자가 "수정 전/핵심만/방향 확정 후 수정" 요청
                         → 토론/확정 모드 (문서 수정 보류)

議論／確定モードでは、次の順序でのみ応答し、ファイルは変更しません。

1. 현재 이해
2. 미확정 판단
3. 권장안
4. 사용자 확인 질문
5. 사용자 확정 후에만 문서 반영

1단계：資料の収集

ui-proto／機能ドキュメントに加えて、現行の実装確認を簡潔に行います。結果はSpecに詳しく書かず、「現行構造を基に拡張／新規作成／対象外」程度にまとめます。

• DB：既存のテーブル／カラム／状態値／インデックス
• Backend：API、service、dao、transaction、approval/processing flow
• Frontend：画面、store、contract、modal、route
• TDD：既存のhelper、fixture、cleanupのパターン
• E2E：既存のscenario、suite、seed/dataの準備方法

続いて、ui-protoを基にする場合は次の資料を読みます。

# 메타
<PROTO_PATH>/_task-meta.ts

# 현업 검토용 설명/기획 개요
<PROTO_PATH>/overview/pages/overview.vue

# 화면 파일
<PROTO_PATH>/**/pages/*.vue

# Mock 데이터
<PROTO_PATH>/**/mock/*.mock.ts

# Mock Store
<PROTO_PATH>/**/store/*.store.ts

# 타입
<PROTO_PATH>/**/type/*.ts

既存機能の改善モードの場合は、まずfeature-docsの概要ドキュメントを読み、必要な詳細ドキュメントのみ追加で読みます。

schemaの入力がある場合は、テーブル／カラム／インデックス／参照関係を読み、SpecのDBスキーマ基準に反映します。

2단계：基本情報の確定

• モジュール名：英語のkebab-case
• テーブル名：snake_case
• 韓国語の機能名：ファイル名用
• 1行の説明
• UIパターン：crud / two-depth / select-list / page / excel
• ファイルアップロード：なし／一般ファイル／画像／一般ファイル＋画像
• 保存方式：なし／Local／S3
• DBの種類：PostgreSQL / MySQL

3단계：機能範囲の確定

基本CRUD：

• ページング一覧（findPaging）
• キーワード／選択肢一覧（findList）
• 詳細取得（detailOne）
• 登録（insert）
• 更新（update）
• 使用可否の変更（updateUse）
• 論理削除（softDelete）

特別なアクションがある場合は、CRUDと分けて明記します。

例：

• 承認／却下
• Excelアップロード／ダウンロード／テンプレートのダウンロード
• 一括変更
• ファイルのプレビュー／ダウンロード
• 通知の送信
• 外部APIとの同期

4단계：画面／アクション基準の確定

ui-protoから次の項目を抽出し、不明瞭な箇所のみユーザーに確認します。

• 画面一覧：一覧、詳細、登録、編集、モーダル、タブ、一括処理など
• 主なアクション：検索、保存、削除、承認、却下、アップロード、ダウンロードなど
• 入力フィールド：必須／任意、型、長さ、選択値
• 一覧のカラム：カラム名、並び替え、表示条件
• 成功時の状態：トースト、モーダルを閉じる、一覧を再読み込み、詳細画面へ移動、状態変更
• エラー時の状態：必須値の検証、権限エラー、サーバーエラー、外部連携エラー
• 空の状態：一覧が0件、検索結果なし、ファイルなし

5단계：DBスキーマ基準の確定

gen-dbがすぐにマイグレーションを作成できるよう、以下を確定します。

• 新規／変更するテーブル
• カラム名、型、必須かどうか、説明、選択値、デフォルト値
• インデックスの候補
• 論理的な参照関係（FKは作成しない）
• 共通カラムの適用有無：is_use、is_delete、insert_seq、insert_date、update_seq、update_date
• DB変更の候補と確定条件

DB設計はカラム一覧だけにしません。次の判断を簡潔に記載します。

• 採用した構造とその理由
• 除外した構造とその理由
• uniqueの基準
• 履歴テーブルの必要性
• soft delete／共通監査カラムを適用するか、除外するか（単一レコードの状態テーブル・ログ用・外部台帳テーブルのように、性質上適さない場合は除外可能です。除外する場合は§12の除外／禁止事項に明記します）
• FKは禁止（参照整合性はアプリケーションで処理します）

不明瞭な場合はDB_DECISION_REQUIREDとして残しますが、可能な限りSpecの作成段階でユーザーに確認して確定します。

5.5단계：システム安全性の確定

§5「権限・状態・エラー・外部依存性」の中に、システム安全性の小節を明記します。カパシインタビューで指摘された「動作はするものの、システム上危険な判断」（例：外部メールアドレスを識別子として使用し、決済とログインを照合する）の類を、Specの段階で事前に防ぎます。

次の項目を文章で確定します。該当しない場合は「該当なし」と記載しますが、「該当なし」が多すぎる場合は§7.5のセルフチェックで疑ってください。

• 識別子のポリシー：何をPKとするか、外部入力（メールアドレス・電話番号）を識別子として使用するか
• データ所有の境界：誰のデータを誰が参照／変更できるか
• 相互照合の禁止：2つのシステム間の照合に使用してはならないキー
• 回帰リスクのマーク：この機能が認証／セッション／共通モジュールに影響するか（Y/N）

6단계：API契約の確定

team-devとteam-e2eが同じ基準を参照できるよう、リクエスト／レスポンスを明記します。

• endpoint
• method
• query/path/body
• response shape
• error response
• ファイルアップロードがmultipartかどうか
• pagination key：list、totalRow、page、rowSizeなど、既存のパターンを優先

コード実装例は記載しません。契約のみを記載します。

7단계：TEST_ID＋TDD/E2E基準の確定

TEST_IDは、要件ごとに1つを基本とします。

推奨形式：

R-001, R-002 ...

ドメインが明確な場合は、接頭辞を付けます。

NOTICE-001, NOTICE-002 ...

§6のTEST_ID表には、すべての要件を記載します（要件＋完了基準＋検証レベル）。

検証レベル（4段階）

各TEST_IDに、次のいずれかを割り当てます。team-dev/team-e2eはレベルに応じて、自動化する範囲とユーザー確認が必要な範囲を分けます。

レベル	意味	対応
自動（高）	型・テスト・契約	team-dev/e2eで自動化
自動（中）	ビジネスルール	TEST_IDをマッピングして自動化
人間（中）	権限・相互照合・システム安全性	ユーザー確認が必須
人間（低）	美観・コピー・実取引の正確性	自動ループは禁止、§12.5にも明記

§7のBackend TDDと§10のE2Eでは、すべてのTEST_IDを扱う必要はありません。重要な検証のみを選んで記載します。

Backend TDDの選定基準（該当するもののみ記載）

• 重要な状態遷移（例：一時保存 → 承認申請 → 承認）
• 保存／更新の結果（フィールド値、監査カラム、履歴テーブル）
• 権限または所有範囲による拒否
• 代表的な失敗ケース（外部連携の失敗、同時更新、重複）
• テストデータの作成／クリーンアップの責任

単純なCRUDの基本動作（必須値の検証、正常なinsert、正常なupdate）はteam-devが標準パターンで処理するため、Specには記載しません。

E2Eシナリオの選定基準

• 重要なユーザーフローのみを単体シナリオとして定義します。
• 「既存データがある」と仮定しません。開始データはシナリオ／suiteが直接準備します。
• 同じフローが複数のTEST_IDで繰り返される場合は、suiteの組み合わせを優先します。
• selector、wait、fixture、suite内のコードは記載しません。
• 単体シナリオの作成ルール（単一責任／再利用／独立実行）とsuiteの統合ルールは、peach-e2e-scenario／peach-e2e-suiteがSoTです。Specにはフローの意図のみを記載します。

例：

TEST_ID: NOTICE-001 (등록 흐름 — 핵심)
Backend TDD: 등록자/등록일 저장 + 필수값 검증
E2E 단위: 빈 목록 → 등록 → 필수값 입력 → 저장 → 목록에 노출

TEST_ID: NOTICE-005 (승인 흐름 — 상태 전이)
Backend TDD: 승인요청 → 승인 상태 전이, 권한 차단
E2E 단위: 등록된 공지 → 승인요청 → 관리자 로그인 → 승인 → 상태 변경 확인

E2E suite: 공지 라이프사이클
  단위(등록) → 단위(승인) → 사용여부 변경 → 삭제

7.5단계: 검증성 자가 점검

8단계 파일 생성 전에 다음 5개 질문을 자체 점검한다. 하나라도 문제가 있으면 사용자에게 보고하고 보강 후 8단계로 넘어간다.

1. 모든 TEST_ID에 검증 등급이 매겨졌는가?
2. §5.5 시스템 안전성에서 "해당 없음"이 5개 이상인가? (있으면 의심하고 재검토)
3. 외부 입력(이메일·전화·외부 시스템 ID)을 식별자로 쓰는 곳이 있는가?
4. 인증/세션/_common 변경이 예상되는가? 있으면 §5.5 회귀 위험 표식에 Y로 명시한다.
5. §12.5 검증 불가 영역이 비어 있는가? 정말 없는지 미학·카피·실거래·외부 연동 안전성 관점에서 재확인한다.

이 점검은 카파시가 짚은 jagged intelligence 영역을 Spec 단계에서 분리하기 위한 것이다. 점검 결과는 완료 보고에 한 줄로 남긴다.

8단계: 사용자 확인 후 파일 생성

• 단일 .md 파일 한 개를 생성한다.
• assets/spec-template.md를 읽어 치환한다.
• 사용자 확인이 끝난 항목만 확정으로 쓴다.
• 미확정 항목은 DECISION_REQUIRED 또는 DB_DECISION_REQUIRED로 남기고 완료 보고에서 차단 항목으로 알린다.

템플릿

spec-template.md를 읽어 치환한다.

주요 플레이스홀더:

플레이스홀더	의미
FEATURE_NAME_KR	한글 기능명
DESCRIPTION	한줄 설명
MODULE_NAME	모듈명
TABLE_NAME	테이블명
DB_TYPE	PostgreSQL/MySQL
STATUS	초안/확정/차단
SOURCE_REFERENCES	ui-proto/schema/기능 문서 경로
SUMMARY_*	Part A 요약 카드
SEQUENCE_DIAGRAM_BODY	핵심 흐름 sequence body
ER_DIAGRAM_BODY	데이터 모델 erDiagram body
FUNCTION_SCOPE	CRUD/특수 액션/파일 기능
SCREEN_ACTION_CRITERIA	화면/액션/성공/오류 기준
SCHEMA_COLUMNS	DB 컬럼 표 본문
SCHEMA_INDEXES	인덱스 SQL
REFERENCE_RELATIONS	논리 참조 관계
DB_CHANGE_CANDIDATES	DB 변경 후보
API_CONTRACTS	API 계약
RULES_PROSE	권한/상태/오류/외부의존성
SYSTEM_SAFETY	시스템 안전성 (식별자/소유 경계/교차 매칭 금지/회귀 위험)
REQUIREMENT_MATRIX	TEST_ID 요구사항 매트릭스 (검증 등급 포함)
TDD_CRITERIA	Backend TDD 기준
STORE_CONTRACT_CRITERIA	Store/Contract 기준
UI_IMPLEMENTATION_CRITERIA	UI 구현 기준
E2E_SCENARIOS	E2E 단위 시나리오
E2E_SUITES	E2E 통합 suite (선택)
MODULE_BOUNDARIES	파일/모듈 경계
FORBIDDEN_ITEMS	제외/금지 사항
UNVERIFIABLE_AREAS	검증 불가 영역 (자동 검증 금지, 사용자 확인 영역)
REFERENCE_INDEX	참조 인덱스

완료 조건

□ DB 종류 판별 완료
□ ui-proto/기능 문서/schema 입력 자료 확인 완료
□ 기능 범위 확정
□ 화면/액션/성공/오류 기준 확정
□ DB 스키마 기준 확정 또는 DB_DECISION_REQUIRED 명시
□ API 계약 확정
□ §5.5 시스템 안전성 확정 (식별자/소유 경계/교차 매칭/회귀 위험)
□ TEST_ID 요구사항 매트릭스 확정 (검증 등급 포함)
□ Backend TDD 기준 확정
□ Store/Contract 기준 확정
□ UI 구현 기준 확정
□ E2E 시나리오 확정
□ §12.5 검증 불가 영역 명시 (없으면 "해당 없음")
□ §7.5 검증성 자가 점검 5개 질문 통과
□ 제외/금지 사항 확인
□ 단일 Spec 파일(.md) 생성 완료
□ team-dev/team-e2e가 추가 기획 질문 없이 실행 가능한지 자체 점검 완료

완료 후 안내

Spec 생성이 완료되었습니다.

산출물: docs/spec/{년}/{월}/[개발자]-[YYMMDD]-[기능명].md

다음 단계:
1) DB 마이그레이션 생성
   /peach-gen-db spec=docs/spec/.../[기능명].md

2) 본 개발
   /peach-team-dev [모듈명] mode=fullstack spec=docs/spec/.../[기능명].md

3) E2E 검증
   /peach-team-e2e spec=docs/spec/.../[기능명].md [proto=<ui-proto 태스크 경로>]

사용자가 후속 구현을 별도 세션/worktree에서 이어가려면 다음 인계 정보를 함께 안내한다.

- 대상 저장소
- 기준 브랜치 / feature branch 추천명
- Spec 문서 경로
- Spec 확정 커밋
- worktree 추천 경로 (peach-worktree 스킬 활용 가능)
- team-dev 실행 명령
- team-e2e 실행 명령
- commit/push 전 사용자 확인 원칙

예제

Spec 주도 개발 예제는 examples.md를 필요한 경우에만 읽는다.

주의사항

1. PRD 추적 섹션을 만들지 않는다. 구현 기준은 Spec이다.
2. 질문은 단계별로 진행하되, 컨텍스트가 충분하면 단계 통합 가능하다.
3. 작은 단일 수정은 정식 Spec을 강제하지 않고 짧은 메모로 처리 가능하다.
4. 시스템 아키텍처 다이어그램을 반복 생성하지 않는다.
5. 4축 상태 매트릭스(S/U/I/V)를 만들지 않는다.
6. 권한/상태/오류/외부의존성은 산문 1차, 복잡할 때만 표로 확장한다.
7. TDD/E2E는 코드가 아니라 검증 기준과 시나리오로 확정한다.
8. Spec에 없는 요구는 team-dev와 team-e2e가 임의 구현하지 않는다.
9. 검증 가능성은 Spec이 책임진다. §5.5 시스템 안전성, §6 검증 등급, §12.5 검증 불가 영역을 비워 두지 않는다. 비워 두면 downstream이 jagged 영역을 자동으로 식별하지 못한다.