peach-agent-team

Peach Agent Team

Overview

This is an integrated team skill that coordinates new feature development in the PeachSolution architecture.

Existing team-backend, team-ui, team-fullstackare unified into one, and the role-specific personas and checklists are included in this document.

Modes

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

Preconditions

For modes that require a DB schema (backend, fullstack), api/db/schema/[도메인]/[테이블].sqlmust exist.
ui In 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 overview → logic → specification → TDD in that order and inject the context.

Inputs

/peach-agent-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

Confirm 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

Proceed to the next step only when both mode and module name are specified. If missing, must ask the developer.

When mode is not specified:

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

When module name is not specified:

모듈명을 입력해주세요 (예: 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 방식

1.5. Domain analysis (Analyze)

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

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

Analysis items:

Schema comparison: number of fields, type complexity, relationships compared with test-data
Business logic determination: simple CRUD vs state transitions/calculated fields/conditional validation
Adaptation decision: Must Follow → as is / May Adapt → identify items customized to the domain

Pass the analysis results to the subagents:

When creating each agent, include "Characteristics of this domain: [analysis results]" in the prompt

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. Role-specific instructions

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

Role	Reference Files	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 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 passed
Deliverables: API file list, endpoint spec, test results
Details: references/backend-dev-agent.md reference

backend-qa

QA checklist (7 items):

type/, dao/, service/, controller/, test/ File structure exists
Compliance with Service static method rules
No FK constraints
bun test passed
bun run lint:fixed passed
bun run build succeeded
API endpoint spec match

Details: references/backend-qa-agent.md reference

store-dev

peach-gen-store Generate a 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.
UI pattern (ui=) is not present, confirm with the user.
In the target project, _common/components/If present, 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):

File structure (pages/, modals/, store/, type/) exists
Composition API (<script setup>) pattern compliance
Pinia Option API Store pattern compliance
listAction, resetAction, listMovePage function implementation
Apply the URL watch pattern (route → listParams, route → getList)
bunx vue-tsc --noEmit passed
bun run lint:fix passed
bun run build succeeded + no AI Slop design patterns

Details: references/frontend-qa-agent.md reference

Ralph Loop (iterative verification mechanism)

On QA failure, rather than a simple retry, Ralph Loopinject structured feedback using the (Vercel Labs) pattern.

Escalation stages

Iteration count	Stage	Action
1~3회	Autonomous fix	Fix code using only QA feedback
4~7회	Re-reference guide	Re-read the entire test-data baseline skeleton, then fix
8~10회	Minimal fix	Focus only on Must Follow items, defer the rest
11+	Stop	User escalation

Application method

Backend QA failure → 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 passes:

1. Evidence Collection

The orchestrator automatically runs /peach-qa-gate→ generates an evidence report

If the verdict is ❌, fix the relevant item and rerun
If the verdict is ✅, proceed to the next step

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-agent-team notice-board mode=backend

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

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

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