SuperAPI AI Directory
Partner中文AI newsFavorites
Skillspeach-team

peach-team

Coding & development

View repository

Updated 10-15 21:35

About this skill

Peach Agent Team

Overview

An integrated team skill that coordinates new feature development in the PeachSolution architecture.

Existing team-backend, team-ui, team-fullstackinto one, and includes role-specific personas and checklists within this document.

Modes

mode Purpose Included roles
backend Connect API + Store to existing UI backend-dev, backend-qa, store-dev, frontend-qa
ui Implement UI only based on Store ui-dev, frontend-qa
fullstack Generate everything based on the DB schema backend-dev, backend-qa, store-dev, ui-dev, frontend-qa

Preconditions

  • In modes that require a DB schema (backend, fullstack), api/db/schema/[도메인]/[테이블].sqlmust exist.
  • ui In the mode, front/src/modules/[모듈명]/store/[모듈명].store.tsmust exist.
  • If there is no Store, first peach-gen-store, and if there is no UI, generate based on peach-gen-ui.
  • When running in the context of modifying an existing feature, if docs/기능별설명/{카테고리명}/{기능명}/exists, first read in the order of overview → logic → specification → TDD and inject the context.

Inputs

/peach-team [모듈명] mode=backend|ui|fullstack [옵션]

# 공통 옵션
# model=sonnet|opus|haiku  (서브에이전트 모델 override, 기본값: sonnet)
# figma=[URL]
# ui=crud|page|two-depth|infinite-scroll|select-list
# file=Y
# excel=Y
# storeTdd=Y

Orchestration

0. Input validation

Check that the agent team feature is enabled

Use the command below to check whether ~/.claude/settings.jsonhas the agent team flag set:

cat ~/.claude/settings.json | grep -i "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"

If there is no setting or it is not "1", stop immediatelyand output the following guidance:

⚠️  에이전트 팀 기능이 비활성화되어 있습니다.

~/.claude/settings.json에 아래 내용을 추가한 후 Claude Code를 재시작하세요:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

설정 가이드: https://github.com/peachSolution/peach-harness/blob/main/docs/06-에이전트팀-설정.md
공식 문서: https://code.claude.com/docs/ko/agent-teams

Both mode and module name must be specified to proceed to the next step. If missing, must ask the developer.

When mode is unspecified:

mode를 선택해주세요:
1. backend — 기존 UI에 API + Store 연결
2. ui — Store 기반 UI만 구현
3. fullstack — DB 스키마 기반 전체 생성

When module name is unspecified:

모듈명을 입력해주세요 (예: notice-board, product-manage):

model option:

  • Unspecified: run all subagents with the default value sonnet
  • If specified: override all subagents to that model
  • Allowed values: sonnet, opus, haiku

1. Environment check

# 스키마 / 타입 / 가이드 코드 확인
ls api/db/schema/
head -5 api/src/modules/test-data/dao/test-data.dao.ts
head -3 api/src/modules/test-data/controller/test-data.controller.ts
ls front/src/modules/test-data/

# DAO 라이브러리 감지
# from 'bunqldb' → 재할당 방식
# from 'sql-template-strings' → append 방식

# modules 분리 구조 감지
ls -d api/src/modules*/
ls -d front/src/modules*/

# _common 구성 감지
ls api/src/modules/_common/
ls api/src/modules/_common/constants/ 2>/dev/null

# 스킬 references 경로 감지
SKILL_BASE=$(dirname "$(find ~/.claude ~/.agents -path "*/peach-gen-backend/references" -type d 2>/dev/null | head -1)" 2>/dev/null)

1.5. Domain analysis (Analyze)

The orchestrator reads the schema of the target domain, identifies differences compared to test-data, and injects them as context into the subagent prompts.

# 대상 스키마 읽기
cat api/db/schema/[도메인]/[테이블].sql

Analysis items:

  1. Schema comparison: number of fields, type complexity, relationships compared to test-data
  2. Business logic assessment: simple CRUD vs state transitions/computed fields/conditional validation
  3. Adaptation decision: Must Follow → as is / May Adapt → identify domain-tailored items

Pass the analysis results to the subagents:

  • When creating each agent, include "Characteristics of this domain: [analysis results]" in the prompt
  • Module creation path: api/src/[감지된 modules 경로]/[모듈명]/
  • front corresponding path: front/src/[감지된 modules 경로]/[모듈명]/
  • _common constant list: [감지된 상수 파일 목록] (if present, instruct not to hardcode)
  • file option inference: if the schema shows file-related requirements, file=Y suggest
  • references path (injected separately by role):
    • backend-dev: ${SKILL_BASE}/peach-gen-backend/references/
    • store-dev: ${SKILL_BASE}/peach-gen-store/references/
    • ui-dev: ${SKILL_BASE}/peach-gen-ui/references/

  1. Structure suggestion (May Suggest): If the domain analysis determines that a structure different from the guide code (test-data) is more appropriate:

    • Present the proposal and rationale to the user first
    • After user confirmation, reflect it in the sub-agent prompt

    Proposable scope:

    • Service file separation (e.g., a service dedicated to state transitions)
    • DAO composition changes (e.g., separating a DAO for composite queries)
    • Whether a transaction service is needed
    • Subdirectories within a module (e.g., step1/step2 separation by stage)

    Not proposable (Must Follow):

    • Module boundaries, naming, type principles, etc.

2. Team composition diagram

mode=backend

backend-dev ──→ backend-qa
       │
       └──→ store-dev ──→ frontend-qa

mode=ui

ui-dev ──→ frontend-qa

mode=fullstack

backend-dev ──→ backend-qa
       │
       └──→ store-dev ──→ ui-dev ──→ frontend-qa

3. Team creation and task registration

TeamCreate: team_name="[모듈명]-[mode]-team"

# mode=backend 작업 등록
TaskCreate:
1. "Backend API 개발" (owner: backend-dev)
2. "Backend QA 검증" (blockedBy: Task1, owner: backend-qa)
3. "Frontend Store 개발" (blockedBy: Task1, owner: store-dev)
4. "Frontend QA 검증" (blockedBy: Task3, owner: frontend-qa)

# mode=ui 작업 등록
TaskCreate:
1. "UI 컴포넌트 생성" (owner: ui-dev)
2. "Frontend QA 검증" (blockedBy: Task1, owner: frontend-qa)

# mode=fullstack 작업 등록
TaskCreate:
1. "Backend API 개발" (owner: backend-dev)
2. "Backend QA 검증" (blockedBy: Task1, owner: backend-qa)
3. "Frontend Store 개발" (blockedBy: Task1, owner: store-dev)
4. "Frontend UI 개발" (blockedBy: Task3, owner: ui-dev)
5. "Frontend QA 검증" (blockedBy: Task4, owner: frontend-qa)

4. Instructions by role

The full definition of each role (persona, Bounded Autonomy, workflow) is in references/. When creating a sub-agent, include the entire contents of that file in the prompt. model= If the option is specified, pass it as the model parameter on each agent call to override the frontmatter default.

Role Reference file Core skills
backend-dev references/backend-dev-agent.md peach-gen-backend
backend-qa references/backend-qa-agent.md Verification only (read-only, worktree)
store-dev references/store-dev-agent.md peach-gen-store
ui-dev references/ui-dev-agent.md peach-gen-ui + peach-gen-design
frontend-qa references/frontend-qa-agent.md Verification only (read-only, worktree)

backend-dev

  • peach-gen-backend Generate the API code based on the criteria.
  • Detect Koa/Elysia mode.
  • Detect the DAO library (bunqldb/sql-template-strings).
  • Completion criteria: bun test, bun run lint:fixed, bun run build pass
  • Deliverables: API file list, endpoint spec, test results
  • Details: references/backend-dev-agent.md reference

backend-qa

QA checklist (7 items):

  1. type/, dao/, service/, controller/, test/ File structure exists
  2. Comply with Service static method rules
  3. No FK constraints
  4. bun test pass
  5. bun run lint:fixed pass
  6. bun run build success
  7. API endpoint spec matches
  • Details: references/backend-qa-agent.md reference

store-dev

  • peach-gen-store Generate the Pinia Store based on the criteria.
  • Match the Backend types and interfaces.
  • Completion criteria: bunx vue-tsc --noEmit
  • Details: references/store-dev-agent.md reference

ui-dev

  • peach-gen-ui, and if needed, peach-gen-designis used.
  • figma=[URL]If present, load FigmaRemote MCP to analyze the design.
  • If there is no UI pattern (ui=), check with the user.
  • If the target project has _common/components/, use the wrapper component first.
  • Completion criteria: bunx vue-tsc --noEmit, bun run lint:fix, bun run build
  • Details: references/ui-dev-agent.md reference

frontend-qa

QA checklist (8 items):

  1. File structure (pages/, modals/, store/, type/) exists
  2. Composition API (<script setup>) pattern compliance
  3. Comply with the Pinia Option API Store pattern
  4. listAction, resetAction, listMovePage function implementation
  5. Apply the URL watch pattern (route → listParams, route → getList)
  6. bunx vue-tsc --noEmit pass
  7. bun run lint:fix pass
  8. bun run build success + no AI Slop design patterns
  • Details: references/frontend-qa-agent.md reference

QA Verdict Processing (3 Stages)

QA agents (backend-qa, frontend-qa) APPROVED / CONDITIONAL / REJECTED make verdicts in 3 stages. The orchestrator performs the Architect role and processes the verdicts.

✅ APPROVED

QA → SendMessage → 오케스트레이터: "APPROVED" + 검증 결과
오케스트레이터 → /peach-qa-gate 자동 실행
→ 완료

⚠️ CONDITIONAL

QA → SendMessage → 오케스트레이터: "CONDITIONAL" + 조건 내용 + 왜 REJECTED가 아닌지 근거
오케스트레이터 판단:
    "조건 수용" → dev 에이전트에 수정 지시 → QA 재검증
    "조건 무시" → 판단 근거 기록 후 APPROVED로 처리

Rules:

  • CONDITIONAL is not a Ralph Loop. Do not mark as complete until the orchestrator decides.
  • QA는 At least 1 condition item + the rationale for why it is not REJECTEDmust be reported together.
  • If the orchestrator chooses "ignore", include the rationale in the final completion report.

❌ REJECTED → Ralph Loop activates

On REJECTED, not a simple retry but Ralph Loop(Vercel Labs) pattern is used to inject structured feedback.

Escalation Stages

Iteration Count Stage Action
1~3회 Autonomous Fix Fix code using QA feedback only
4회 Re-reference Guide Re-read the entire test-data baseline skeleton, then fix
5~7회 Codex Diagnosis codex:codex-rescueto independently diagnose the failure cause + re-reference the guide
8~10회 Minimal Fix Focus only on Must Follow items, defer the rest
11+ Stop User Escalation

Codex Deployment Conditions (5–7 times)

  • CODEX_AVAILABLE=true only (detected in settings.json via "codex@openai-codex": true detection)
  • CODEX_AVAILABLE=false: Continue the existing Ralph Loop without Codex (re-reference guide)
  • Codex no response/timeout: wait 60 seconds → if no response, skip and proceed with existing feedback
  • Codex diagnosis result poor: orchestrator ignores it and proceeds with existing feedback

Application Method

  • Backend QA REJECTED → backend-dev fix → backend-qa re-verification (SendMessage)
  • Store issue → store-dev fix → frontend-qa re-verification
  • UI issue → ui-dev fix → frontend-qa re-verification

Escalation Report

## Ralph Loop 에스컬레이션
- 모듈: [모듈명]
- 반복: N/10회
- 단계: [현재 단계]
- 미해결: [위반 항목]
- 권장: [수동 개입 사항]

Completion

After all QA APPROVED:

1. Evidence Collection

The orchestrator /peach-qa-gateruns automatically → generates evidence report

  • If the verdict is ❌, fix the relevant item and re-run
  • If the verdict is ✅, proceed to the next stage

2. Team Cleanup

SendMessage(shutdown_request) → 모든 팀원에게
TeamDelete → 팀 정리

Completion Report Format

mode=backend

✅ Backend + Store 연결 팀 개발 완료

모듈: [모듈명]
mode: backend

결과:
✅ backend-dev: API 생성 완료
✅ backend-qa: TDD X개 통과
✅ store-dev: Store 생성 완료
✅ frontend-qa: vue-tsc + lint + build 통과
✅ qa-gate: 증거 보고서 생성 + 완료 가능 판정

생성된 파일:
Backend:
├── api/src/[modules 경로]/[모듈명]/type/
├── api/src/[modules 경로]/[모듈명]/dao/
├── api/src/[modules 경로]/[모듈명]/service/
├── api/src/[modules 경로]/[모듈명]/controller/
└── api/src/[modules 경로]/[모듈명]/test/

Frontend:
├── front/src/[modules 경로]/[모듈명]/type/[모듈명].type.ts
└── front/src/[modules 경로]/[모듈명]/store/[모듈명].store.ts

다음 단계:
→ bun start (Backend 실행)
→ bun run dev (Frontend 실행)
→ 브라우저에서 /[모듈명]/list 접속

mode=ui

✅ UI Only 팀 개발 완료

모듈: [모듈명]
mode: ui
패턴: [ui=패턴]
피그마: [URL 또는 없음]

결과:
✅ ui-dev: UI 컴포넌트 생성 완료
✅ frontend-qa: vue-tsc + lint + build 통과

생성된 파일:
├── front/src/[modules 경로]/[모듈명]/pages/list.vue
├── front/src/[modules 경로]/[모듈명]/pages/list-search.vue
├── front/src/[modules 경로]/[모듈명]/pages/list-table.vue
├── front/src/[modules 경로]/[모듈명]/modals/insert.modal.vue
├── front/src/[modules 경로]/[모듈명]/modals/update.modal.vue
├── front/src/[modules 경로]/[모듈명]/modals/detail.modal.vue
├── front/src/[modules 경로]/[모듈명]/_[모듈명].routes.ts
└── front/src/[modules 경로]/[모듈명]/_[모듈명].validator.ts

다음 단계:
→ bun run dev (Frontend 실행)
→ 브라우저에서 /[모듈명]/list 접속

mode=fullstack

🎉 풀스택 개발 완료!

모듈: [모듈명]
mode: fullstack

결과:
✅ backend-dev: API 생성 완료
✅ backend-qa: TDD X개 통과
✅ store-dev: Store 생성 완료
✅ ui-dev: UI 컴포넌트 생성 완료
✅ frontend-qa: vue-tsc + lint + build 통과

생성된 파일:
Backend:
├── api/src/[modules 경로]/[모듈명]/type/
├── api/src/[modules 경로]/[모듈명]/dao/
├── api/src/[modules 경로]/[모듈명]/service/
├── api/src/[modules 경로]/[모듈명]/controller/
└── api/src/[modules 경로]/[모듈명]/test/

Frontend:
├── front/src/[modules 경로]/[모듈명]/type/
├── front/src/[modules 경로]/[모듈명]/store/
├── front/src/[modules 경로]/[모듈명]/pages/
├── front/src/[modules 경로]/[모듈명]/modals/
├── front/src/[modules 경로]/[모듈명]/_[모듈명].routes.ts
└── front/src/[modules 경로]/[모듈명]/_[모듈명].validator.ts

다음 단계:
→ bun start (Backend 실행)
→ bun run dev (Frontend 실행)
→ 브라우저에서 /[모듈명]/list 접속

Examples

# 기존 UI에 API + Store 연결
/peach-team notice-board mode=backend

# UI만 구현
/peach-team member-list mode=ui ui=two-depth figma=https://figma.com/file/xxx

# 전체 풀스택 생성
/peach-team product-manage mode=fullstack ui=page file=Y

# opus 모델로 서브에이전트 실행
/peach-team product-manage mode=fullstack model=opus ui=page