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 是实现标准的唯一事实来源。
• 不考虑 PRD。即使存在输入文档，它也只是源材料；实现标准仅以最终 Spec 中明确的内容为准。
• 标准产物是单个 .md 文件。
• Spec 应明确到 team-dev 和 team-e2e 无需追加规划问题即可开展工作。
• 不要在 Spec 中写入 team-* 可自行处理的测试代码、selector、fixture、suite 内部实现。
• 相反，应充分细化各 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 为 SoT；suite 集成规则以 peach-e2e-suite 为 SoT。
• 如果涉及外部集成、认证、支付、文件、通知或 mock 数据，应在 §5 权限·状态·错误·外部依赖中以散文明确各环境的行为（是否允许 local/dev mock、prod 禁止路径）。
• 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 表示新增/变更表
其他图表	可选。仅在存在状态机或特殊流程时使用

弃用：

• 系统架构图：这是 pitch harness 的标准结构，信息价值较低。
• 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 Schema 标准	必须	gen-db 创建迁移所需的列/索引/参照
4. API 契约	必须	Backend/Store/Contract 应遵循的请求·响应标准
5. 权限·状态·错误·外部依赖	必须	防止实现遗漏的标准（包含 5.5 系统安全性）
6. TEST_ID 要求	必须	要求、完成标准、验证等级
7. Backend TDD 标准	必须	需验证的行为，而非测试代码
8. Store/Contract 标准	必须	API 响应键和 Store 状态标准
9. UI 实现标准	必须	画面状态、按钮、Toast、验证消息
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/
四维状态矩阵（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 schema 基准中。

2단계: 基本信息确认

• 模块名：英文 kebab-case
• 表名：snake_case
• 韩文功能名：用于文件名
• 一句话说明
• 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 中提取以下内容，仅在有歧义时向用户确认。

• 画面列表：列表、详情、新增、修改、模态框、选项卡、批量处理等
• 主要操作：搜索、保存、删除、审批、驳回、上传、下载等
• 输入字段：必填/选填、类型、长度、可选值
• 列表列：列名、排序、显示条件
• 成功状态：toast、关闭模态框、刷新列表、跳转详情、更改状态
• 错误状态：必填项校验、权限失败、服务器错误、外部集成失败
• 空状态：列表为 0 条、无搜索结果、无文件

5단계: 确认 DB schema 基准

为确保 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，是否使用外部输入（邮箱、电话）作为标识符
• 数据所有权边界：谁可以查询/修改谁的数据
• 禁止交叉匹配：禁止用于两个系统间匹配的键
• 回归风险标记：此功能是否涉及认证/会话/通用模块（Y/N）

6단계: 确认 API contract

明确请求/响应，使 team-dev 和 team-e2e 遵循相同基准。

• endpoint
• method
• query/path/body
• response shape
• error response
• 是否使用 multipart 上传文件
• pagination key：优先采用现有模式，如 list、totalRow、page、rowSize

不要写代码实现示例，只写 contract。

7단계: 确认 TEST_ID + TDD/E2E 基准

每项需求原则上使用一个 TEST_ID。

推荐格式：

R-001, R-002 ...

若领域明确，则添加前缀。

NOTICE-001, NOTICE-002 ...

§6 TEST_ID 表需列出所有需求（需求 + 完成标准 + 验证等级）。

验证等级（4 个级别）

为每个 TEST_ID 指定以下其中一个等级。team-dev/team-e2e 根据等级划分自动处理范围与需用户确认的范围。

等级	含义	处理
自动（高）	类型、测试、contract	team-dev/e2e 自动处理
自动（中）	业务规则	映射 TEST_ID 后自动处理
人工（中）	权限、交叉匹配、系统安全性	必须由用户确认
人工（低）	美学、文案、真实交易准确性	禁止自动循环，并在 §12.5 中一并注明

§7 Backend TDD、§10 E2E 不涵盖全部 TEST_ID。只选取并编写核心验证项。

Backend TDD 筛选标准（仅编写符合以下条件的项目）

• 核心状态转换（例如：临时保存 → 申请审批 → 审批）
• 保存/更新结果（字段值、审计列、历史记录表）
• 权限或所有权范围限制
• 典型失败案例（外部集成失败、并发修改、重复）
• 测试数据的创建/清理责任

team-dev 会按标准模式处理简单 CRUD 的基本操作（必填项校验、正常 insert、正常 update），因此 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 영역을 자동으로 식별하지 못한다.