Skills

peach-gen-spec

Installation
SKILL.md

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 시나리오를 충분히 구체화한다.
  • 상태 코드는 운영 보고용으로 만들지 않는다. 사용자 보고는 평문(확정, 구현완료, 검증완료, 차단)을 우선한다.
  • 의무 매트릭스는 만들지 않는다. 권한/상태/오류/외부의존성은 산문 1차, 분기와 규칙이 많아 표가 더 명확할 때만 표로 확장한다.
  • FK(Foreign Key)는 생성하지 않는다. 참조 무결성은 애플리케이션에서 처리한다.
  • test-data는 복사 정답지가 아니라 기준 골격이다. 후속 gen-*/team-* 스킬은 Bounded Autonomy 안에서 도메인에 맞게 적응할 수 있다.
  • Spec 분량 목표는 250~450줄이다. 작으면 200줄 내외도 허용하되, TDD/E2E 기준은 생략하지 않는다.

파일 구조

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

예:

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

개발자 아이디는 whoami를 우선 사용하고, 실패하면 git config user.name을 사용한다.

산출물 구조

Part A: 한눈에 보기

사람이 기능의 본질을 빠르게 확인하는 섹션이다.

섹션 정책
요약 카드 의무. 무엇/누가/핵심 액션/신규·변경 테이블/검증 포인트
핵심 흐름 권장. 사용자 액션 1~3개의 sequence diagram
데이터 모델 권장. 신규/변경 테이블만 erDiagram으로 표현
추가 다이어그램 선택. 상태 머신이나 특수 흐름이 있을 때만

폐기:

  • 시스템 아키텍처 다이어그램: 피치 하네스 표준 구조라 정보 가치가 낮다.
  • UI 흐름도 다이어그램: ui-proto가 1차 자료다. ui-proto가 없으면 Part B의 화면 기준 표로 대체한다.

Part B: 확정 Spec

team-dev, team-e2e, gen-db가 우선 읽는 실행 기준이다.

섹션 정책 목적
메타 의무 모듈명, 기능명, UI 패턴, 참조 자료
1. 기능 범위 의무 CRUD, 특수 액션, 파일/엑셀/외부 연동
2. 화면/액션 기준 의무 ui-proto 기반 화면, 액션, 성공/오류 상태
3. DB 스키마 기준 의무 gen-db가 마이그레이션을 만들 수 있는 컬럼/인덱스/참조
4. API 계약 의무 Backend/Store/Contract가 맞출 요청·응답 기준
5. 권한·상태·오류·외부의존성 의무 구현 누락 방지 기준
6. TEST_ID 요구사항 의무 요구사항과 완료 기준
7. Backend TDD 기준 의무 테스트 코드가 아니라 검증해야 할 동작
8. Store/Contract 기준 의무 API 응답 키와 Store 상태 기준
9. UI 구현 기준 의무 화면 상태, 버튼, 토스트, 검증 메시지
10. E2E 시나리오 의무 사용자 흐름, 입력, 기대 결과
11. 파일/모듈 경계 의무 생성·수정 대상 디렉터리
12. 제외/금지 사항 선택 범위 밖 기능과 금지 구현
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단계: 자료 수집

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
  • 한글 기능명: 파일명용
  • 한줄 설명
  • UI 패턴: crud / two-depth / select-list / page / excel
  • 파일 업로드: 없음 / 일반 파일 / 이미지 / 일반 파일 + 이미지
  • 저장 방식: 없음 / Local / S3
  • DB 종류: PostgreSQL / MySQL

3단계: 기능 범위 확정

기본 CRUD:

  • 페이징 목록(findPaging)
  • 키워드/선택 목록(findList)
  • 상세 조회(detailOne)
  • 등록(insert)
  • 수정(update)
  • 사용여부 변경(updateUse)
  • 논리 삭제(softDelete)

특수 액션이 있으면 CRUD와 분리해서 명시한다.

예:

  • 승인 / 반려
  • 엑셀 업로드 / 다운로드 / 템플릿 다운로드
  • 일괄 변경
  • 파일 미리보기 / 다운로드
  • 알림 발송
  • 외부 API 동기화

4단계: 화면/액션 기준 확정

ui-proto에서 다음을 추출하고, 모호한 부분만 사용자에게 확인한다.

  • 화면 목록: 목록, 상세, 등록, 수정, 모달, 탭, 일괄처리 등
  • 주요 액션: 검색, 저장, 삭제, 승인, 반려, 업로드, 다운로드 등
  • 입력 필드: 필수/선택, 타입, 길이, 선택값
  • 목록 컬럼: 컬럼명, 정렬, 표시 조건
  • 성공 상태: 토스트, 모달 닫힘, 목록 새로고침, 상세 이동, 상태 변경
  • 오류 상태: 필수값 검증, 권한 실패, 서버 오류, 외부 연동 실패
  • 빈 상태: 목록 0건, 검색 결과 없음, 파일 없음

5단계: DB 스키마 기준 확정

gen-db가 바로 마이그레이션을 만들 수 있도록 아래를 확정한다.

  • 신규/변경 테이블
  • 컬럼명, 타입, 필수 여부, 설명, 선택값, 기본값
  • 인덱스 후보
  • 논리적 참조 관계(FK 생성 없음)
  • 공통 컬럼 적용 여부: is_use, is_delete, insert_seq, insert_date, update_seq, update_date
  • DB 변경 후보와 확정 조건

모호하면 DB_DECISION_REQUIRED로 남기되, 가능하면 Spec 생성 단계에서 사용자 확인 후 확정한다.

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는 요구사항당 하나를 기본으로 한다.

권장 형식:

R-001, R-002 ...

도메인이 명확하면 접두어를 붙인다.

NOTICE-001, NOTICE-002 ...

각 TEST_ID마다 반드시 다음을 채운다.

  • 요구사항
  • 완료 기준
  • Backend TDD 기준
  • Store/Contract 기준
  • UI 구현 기준
  • E2E 시나리오

예:

TEST_ID: NOTICE-001
요구사항: 관리자는 공지사항을 등록할 수 있다.
완료 기준: 제목/내용/공지여부/사용여부가 저장되고 목록 첫 페이지에 반영된다.
Backend TDD: 필수값 검증, insert 저장, 등록자/등록일 저장을 검증한다.
Store/Contract: insert 성공 응답 후 목록 재조회 액션이 호출된다.
UI 기준: 저장 성공 후 모달이 닫히고 성공 토스트가 표시된다.
E2E: 목록 → 등록 클릭 → 필수값 입력 → 저장 → 목록에서 제목 확인.

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 권한/상태/오류/외부의존성
REQUIREMENT_MATRIX TEST_ID 요구사항 매트릭스
TDD_CRITERIA Backend TDD 기준
STORE_CONTRACT_CRITERIA Store/Contract 기준
UI_IMPLEMENTATION_CRITERIA UI 구현 기준
E2E_SCENARIOS E2E 시나리오
MODULE_BOUNDARIES 파일/모듈 경계
FORBIDDEN_ITEMS 제외/금지 사항
REFERENCE_INDEX 참조 인덱스

완료 조건

□ DB 종류 판별 완료
□ ui-proto/기능 문서/schema 입력 자료 확인 완료
□ 기능 범위 확정
□ 화면/액션/성공/오류 기준 확정
□ DB 스키마 기준 확정 또는 DB_DECISION_REQUIRED 명시
□ API 계약 확정
□ TEST_ID 요구사항 매트릭스 확정
□ Backend TDD 기준 확정
□ Store/Contract 기준 확정
□ UI 구현 기준 확정
□ E2E 시나리오 확정
□ 제외/금지 사항 확인
□ 단일 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 태스크 경로>]

예제

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가 임의 구현하지 않는다.
Related skills

More from peachsolution/peach-harness

Installs
59
Repository
peachsolution/p…-harness
First Seen
Mar 15, 2026
Security Audits
Gen Agent Trust HubFail
SocketPass
SnykPass