peach-team-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Peach Team Dev

PeachSolution 개발을 조율하는 통합 오케스트레이터다. 신규 기능, 기존 기능 수정, prompt 기반 즉흥 작업을 처리하되 구현 기준은 항상 외부 산출물과 기존 코드 증거에서 가져온다.

这是协调PeachSolution开发的集成编排器。处理新功能、现有功能修改、基于prompt的即兴作业，但实现标准始终取自外部产出物和现有代码证据。

핵심 책임

核心职责

구현과 코드 수준 검증을 수행한다: TDD, lint, build, API-Store Contract Gate.
사용자 흐름과 기획 부합 검증은
```
peach-team-e2e
```
로 넘긴다.
DB 마이그레이션 생성과 적용은 직접 하지 않는다.
```
mode=backend|fullstack
```
은
```
peach-gen-db
```
로 생성된
```
api/db/schema/...
```
가 준비된 뒤 실행한다.
Spec, schema, ui-proto가 충돌하거나 기준이 없으면 추측 구현하지 않고
```
DECISION_REQUIRED
```
,
```
DB_DECISION_REQUIRED
```
,
```
DB_CHANGE_REQUIRED
```
로 차단한다.
요청 범위와 런타임 도구 가용성에 따라
```
single-agent
```
,
```
role-queue
```
,
```
agent-team
```
중 하나를 선택한다.

执行实现和代码级验证：TDD、lint、build、API-Store Contract Gate。
用户流程与规划匹配验证移交至
```
peach-team-e2e
```
。
不直接进行DB迁移的创建与应用。
```
mode=backend|fullstack
```
需在
```
peach-gen-db
```
生成的
```
api/db/schema/...
```
准备完成后执行。
若Spec、schema、ui-proto存在冲突或无标准，不进行推测实现，而是通过
```
DECISION_REQUIRED
```
、
```
DB_DECISION_REQUIRED
```
、
```
DB_CHANGE_REQUIRED
```
进行拦截。
根据请求范围和运行时工具可用性，选择
```
single-agent
```
、
```
role-queue
```
、
```
agent-team
```
中的一种方式。

입력 모드

输入模式

모드	입력	검증 기준	적합 케이스
표준	`mode` + `spec` + `proto`	Spec + ui-proto 화면	신규 기능 표준 경로
Spec만	`mode` + `spec`	`docs/spec/...` Spec	백엔드 중심, 기존 화면 수정, 단순 CRUD
prompt	자연어 입력	prompt 텍스트 + 기존 코드	버그 수정, 즉흥적 변경, 핫픽스
queue	`queue=<기능큐.md>`	기능별 Spec/schema/proto	큰 작업의 기능별 상태 관리

prompt 모드는 검증 기준이 약하므로 작은 변경은 경량 처리하고, 중규모는 자동 팀 모드로 전환한다. 기준이 부족한 큰 변경은

peach-gen-spec

으로 Spec 작성을 권고하고 중단한다.

模式	输入	验证标准	适用场景
标准	`mode` + `spec` + `proto`	Spec + ui-proto页面	新功能标准路径
仅Spec	`mode` + `spec`	`docs/spec/...` Spec	后端为主、现有页面修改、简单CRUD
prompt	自然语言输入	prompt文本 + 现有代码	bug修复、即兴变更、热修复
queue	`queue=<功能队列.md>`	功能别Spec/schema/proto	大型作业的功能别状态管理

prompt模式的验证标准较弱，因此小型变更进行轻量处理，中型变更自动切换至团队模式。标准不足的大型变更会建议使用

peach-gen-spec

编写Spec并终止操作。

Modes

mode	용도	포함 역할
`backend`	준비된 DB 스키마 기준 API + Store 연결	backend-dev, backend-qa, store-dev, frontend-qa
`ui`	Store 기반 UI만 구현	ui-dev, frontend-qa
`fullstack`	준비된 DB 스키마 기준 API + Store + UI 생성	backend-dev, backend-qa, store-dev, ui-dev, frontend-qa

mode	用途	包含角色
`backend`	基于已准备好的DB Schema实现API + Store连接	backend-dev, backend-qa, store-dev, frontend-qa
`ui`	基于Store仅实现UI	ui-dev, frontend-qa
`fullstack`	基于已准备好的DB Schema生成API + Store + UI	backend-dev, backend-qa, store-dev, ui-dev, frontend-qa

Preconditions

표준 모드

标准模式

```
docs/spec/{년}/{월}/
```
의 Spec 파일이 존재해야 한다.
ui-proto 저장소의 태스크 폴더가 존재해야 한다.
DB 스키마가 필요한 모드에서는
```
api/db/schema/[도메인]/[테이블].sql
```
이 존재해야 한다.

必须存在
```
docs/spec/{年}/{月}/
```
下的Spec文件。
必须存在ui-proto仓库的任务文件夹。
需要DB Schema的模式下，必须存在
```
api/db/schema/[领域]/[表].sql
```
。

Spec만 모드

仅Spec模式

DB 스키마가 필요한 모드에서는
```
api/db/schema/[도메인]/[테이블].sql
```
이 존재해야 한다.

ui

모드에서는

front/src/modules/[모듈명]/store/[모듈명].store.ts

가 존재해야 한다.

Store가 없으면 먼저
```
peach-gen-store
```
, UI가 없으면
```
peach-gen-ui
```
기준으로 생성한다.
기존 기능 수정이면
```
docs/기능별설명/{카테고리명}/{기능명}/
```
가 있을 때 개요, 로직, 명세, TDD 순으로 먼저 읽는다.
Spec의 화면 흐름 요약이 있으면 UI 흐름의 최소 기준으로 사용한다.
신규 복잡 화면인데 Spec에 화면 흐름 요약이 없으면
```
peach-team-ui-proto
```
또는 Spec 보강을 권고하고, 강행 시 완료 보고에 검증 한계를 남긴다.

需要DB Schema的模式下，必须存在
```
api/db/schema/[领域]/[表].sql
```
。

ui

模式下，必须存在

front/src/modules/[模块名]/store/[模块名].store.ts

。

若无Store则先基于
```
peach-gen-store
```
生成，若无UI则基于
```
peach-gen-ui
```
生成。
若为现有功能修改，当存在
```
docs/功能别说明/{分类名}/{功能名}/
```
时，按概述、逻辑、规格、TDD的顺序优先读取。
若Spec中有页面流程摘要，则作为UI流程的最低标准使用。
若为新复杂页面但Spec中无页面流程摘要，会建议使用
```
peach-team-ui-proto
```
或补充Spec，强行执行时会在完成报告中注明验证局限性。

prompt 모드

prompt模式

사전 조건은 자연어 입력이다.
변경 규모 추정 후 DB/권한/상태/API 계약 기준이 부족하면 Spec 작성으로 돌린다.

前置条件为自然语言输入。
估算变更规模后，若DB/权限/状态/API契约标准不足，则转回Spec编写环节。

Inputs

bash

undefined

bash

undefined

표준 모드

标准模式

/peach-team-dev [모듈명] mode=backend|ui|fullstack spec=<경로> proto=<경로> [옵션]

/peach-team-dev [模块名] mode=backend|ui|fullstack spec=<路径> proto=<路径> [选项]

대규모 기능 큐 모드

大规模功能队列模式

/peach-team-dev [작업명] queue=<기능큐.md> [proto=<경로>] [옵션]

/peach-team-dev [作业名] queue=<功能队列.md> [proto=<路径>] [选项]

Spec만 모드

仅Spec模式

/peach-team-dev [모듈명] mode=backend|ui|fullstack spec=<경로> [옵션]

/peach-team-dev [模块名] mode=backend|ui|fullstack spec=<路径> [选项]

prompt 모드

prompt模式

/peach-team-dev "버그/개선 사항 자연어 설명" [옵션]


| 인자 | 역할 |
|------|------|
| `[모듈명]` | 표준/Spec만 모드에서 권장. prompt 모드에서는 후보 제안 후 확정 |
| `mode` | 표준/Spec만 모드에서 필수 |
| `spec` | 본 프로젝트 `docs/spec/...`의 Spec 파일 경로 |
| `queue` | 큰 작업용 기능 큐 문서. 지정 시 기능별 mode/input/status를 기준으로 반복 실행 |
| `proto` | ui-proto 저장소의 태스크 폴더 절대 경로 |
| `model` | 선택. 서브에이전트 모델 override. 미지정 기본값은 `sonnet`, 허용 값은 `sonnet|opus|haiku` |
| `team` | 선택. `force`는 agent-team 강제 시도, `off`는 실제 agent-team 금지 |
| `e2e` | 선택. `auto`는 개발 전 E2E preflight 후 완료 시 `peach-team-e2e` 자동 실행, `off`는 자동 체인 비활성 |
| `figma`, `ui`, `file`, `excel`, `storeTdd` | 선택. 역할별 reference의 옵션 처리 기준을 따른다 |

E2E chain 해석:

```text
team-dev만 요청 → E2E 미실행
team-dev + team-e2e 함께 요청 → e2e=auto
사용자가 E2E 제외 명시 또는 e2e=off → e2e=off

/peach-team-dev "bug/改进事项自然语言说明" [选项]


| 参数 | 作用 |
|------|------|
| `[模块名]` | 标准/仅Spec模式下推荐。prompt模式下先候选提议再确认 |
| `mode` | 标准/仅Spec模式下必填 |
| `spec` | 本项目`docs/spec/...`的Spec文件路径 |
| `queue` | 大型作业用功能队列文档。指定时会基于功能别mode/input/status重复执行 |
| `proto` | ui-proto仓库的任务文件夹绝对路径 |
| `model` | 可选。覆盖子Agent模型。未指定默认值为`sonnet`，允许值为`sonnet|opus|haiku` |
| `team` | 可选。`force`强制尝试agent-team，`off`禁用实际agent-team |
| `e2e` | 可选。`auto`在开发前执行E2E预检查，完成后自动执行`peach-team-e2e`，`off`禁用自动链式流程 |
| `figma`, `ui`, `file`, `excel`, `storeTdd` | 可选。遵循各角色参考的选项处理标准 |

E2E链式流程说明：

```text
仅请求team-dev → 不执行E2E
同时请求team-dev + team-e2e → e2e=auto
用户明确排除E2E或指定e2e=off → e2e=off

구현 기준 우선순위

实现标准优先级

Spec / schema / proto 충돌 처리

Spec / schema / proto冲突处理

상황	처리
Spec과 schema가 일치	Spec/schema 기준으로 구현
Spec에 없는 요구 발견	임의 구현하지 않고 `DECISION_REQUIRED` 로 기록
Spec과 schema가 충돌 (의사결정 필요)	`DB_DECISION_REQUIRED` 로 분리하고 사용자 결정 요청
Spec과 schema가 충돌 (변경 필요 확정)	`DB_CHANGE_REQUIRED` 로 분리하고 `peach-gen-db` 후속
ui-proto와 Spec이 충돌	비즈니스/데이터는 Spec 우선, 화면/흐름은 ui-proto 우선. 자동 병합하지 않는다

ui-proto는 Mock 산출물이므로 team-dev는 코드 구조와 이벤트 구현 참고로 사용한다. 실제 사용자 흐름 부합은

peach-team-e2e

가 판정한다.

情况	处理方式
Spec与schema一致	基于Spec/schema实现
发现Spec中未提及的需求	不随意实现，以 `DECISION_REQUIRED` 记录
Spec与schema冲突（需决策）	标记为 `DB_DECISION_REQUIRED` 并请求用户决策
Spec与schema冲突（确认需变更）	标记为 `DB_CHANGE_REQUIRED` 并后续执行 `peach-gen-db`
ui-proto与Spec冲突	业务/数据优先遵循Spec，页面/流程优先遵循ui-proto。不自动合并

ui-proto是Mock产出物，因此team-dev仅作为代码结构和事件实现的参考使用。实际用户流程匹配由

peach-team-e2e

判定。

항목별 team-dev 기준 vs 최종 검증

各项目team-dev标准 vs 最终验证

ui-proto는 본질적으로 Mock이라 100% 구현되지 않을 수 있다. team-dev는 다음 기준으로 구현/TDD 범위를 잡고, 실제 브라우저 흐름 부합 검증은

peach-team-e2e

로 넘긴다.

항목	team-dev 기준	최종 검증
화면 레이아웃, 컴포넌트 배치	ui-proto 화면을 구현 참고 자료로 사용	`peach-team-e2e`
사용자 인터랙션 흐름	ui-proto/Spec을 기준으로 코드 구조와 이벤트를 구현	`peach-team-e2e`
비즈니스 규칙 (검증, 권한, 분기)	Spec 기준으로 API/Store/UI 코드와 TDD 작성	TDD + `peach-team-e2e`
데이터 정확성 (API 응답값)	Spec 기준으로 타입/API/TDD 검증	TDD
에러/예외 처리	Spec 기준으로 코드와 테스트 작성	TDD + 필요 시 E2E

핵심 원칙: team-dev는 구현과 코드 수준 검증까지 책임진다. 화면 흐름이 실제 사용자 관점에서 기획 의도와 맞는지는

peach-team-e2e

가 판정한다. 두 팀 사이의 책임 경계와 자세한 운영 규칙은

references/dev-e2e-chain.md

를 따른다.

ui-proto本质上是Mock，可能无法100%实现。team-dev按以下标准确定实现/TDD范围，实际浏览器流程匹配验证移交至

peach-team-e2e

。

项目	team-dev标准	最终验证
页面布局、组件配置	将ui-proto页面作为实现参考资料	`peach-team-e2e`
用户交互流程	基于ui-proto/Spec实现代码结构和事件	`peach-team-e2e`
业务规则（验证、权限、分支）	基于Spec编写API/Store/UI代码和TDD	TDD + `peach-team-e2e`
数据准确性（API响应值）	基于Spec验证类型/API/TDD	TDD
错误/异常处理	基于Spec编写代码和测试	TDD + 必要时E2E

核心原则：team-dev负责实现和代码级验证。页面流程是否符合用户视角的规划意图由

peach-team-e2e

判定。两个团队之间的职责边界和详细运营规则遵循

references/dev-e2e-chain.md

。

Reference 선택

Reference选择

필요한 상세 문서만 읽는다.

SKILL.md

는 실행 라우터이고, 세부 절차와 역할 정의는 아래 reference가 Source of Truth다.

상황	읽을 reference
팀 구성 자동 분석	`references/runtime-team-selection.md`
Claude/Codex 실행 모드 선택	`references/runtime-adapter.md`
전체 입력 판정, 환경 확인, 도메인 분석, 작업 등록	`references/orchestration-workflow.md`
proto 인자 처리	`references/proto-sync.md`
prompt 모드	`references/prompt-mode.md`
대규모 기능 큐	`references/queue-workflow.md`
team-dev + team-e2e 자동 chain	`references/dev-e2e-chain.md`
fullstack 병렬 개발	`references/fullstack-workflow.md`
Mock Store → 실제 Store 연결	`references/connect-workflow.md`
Figma 입력	`references/figma-workflow.md`
API-Store-UI 연결 검증	`references/contract-gate.md`
결정 차단, DB 변경 차단 템플릿	`references/blockers.md`
QA 판정과 완료 보고	`references/qa-policy.md`
역할별 dev/qa 지시	`references/*-agent.md`

仅阅读必要的详细文档。

SKILL.md

是执行路由器，详细步骤和角色定义以以下reference为Source of Truth。

情况	需阅读的reference
团队构成自动分析	`references/runtime-team-selection.md`
Claude/Codex执行模式选择	`references/runtime-adapter.md`
整体输入判定、环境检查、领域分析、作业登记	`references/orchestration-workflow.md`
proto参数处理	`references/proto-sync.md`
prompt模式	`references/prompt-mode.md`
大规模功能队列	`references/queue-workflow.md`
team-dev + team-e2e自动链式流程	`references/dev-e2e-chain.md`
fullstack并行开发	`references/fullstack-workflow.md`
Mock Store → 实际Store连接	`references/connect-workflow.md`
Figma输入	`references/figma-workflow.md`
API-Store-UI连接验证	`references/contract-gate.md`
决策拦截、DB变更拦截模板	`references/blockers.md`
QA判定与完成报告	`references/qa-policy.md`
各角色dev/qa指示	`references/*-agent.md`

真正的Source of Truth是目标项目的

test-data/

指南代码和gen-*技能reference。team-dev以团队执行方式协调相同模式。

실행 순서

QA与完成

references/runtime-team-selection.md

와

references/runtime-adapter.md

를 읽고

single-agent

role-queue

agent-team

중 실행 방식을 정한다.

입력 형태를 판정한다:
```
queue
```
→ 기능 큐, 자연어 단독 → prompt,
```
mode+proto
```
→ 표준,
```
mode
```
만 → Spec만.
```
e2e=auto
```
또는 team-dev/team-e2e 동시 요청이면 개발 시작 전에
```
references/dev-e2e-chain.md
```
의 preflight를 수행한다.
환경, schema, 기존 모듈 구조, gen-* reference 경로를 확인한다. 상세 명령은
```
references/orchestration-workflow.md
```
를 따른다.
Spec, schema, proto 또는 prompt를 읽고 도메인 특성을 분석해 역할별 프롬프트에 주입한다.
mode와 분석 결과에 맞춰 역할을 실행한다. 실제 agent-team을 쓸 수 없으면 같은 순서를 role-queue로 실행한다.
각 dev 역할은 요청 범위 구현과 자체 검증을 수행하고, QA 역할은 독립적으로 검증한다.
```
mode=backend|fullstack
```
또는 연결 변경이 있으면
```
references/contract-gate.md
```
를 기준으로 API-Store Contract Gate를 수행한다.
QA가
```
REJECTED
```
면
```
references/qa-policy.md
```
의 반복 상한 안에서 dev 역할로 되돌린다.
완료 보고에 TDD/lint/build/Contract Gate, TEST_ID 구현 상태, 차단 항목, E2E 인계 정보를 남긴다.

QA Agent以

APPROVED / CONDITIONAL / REJECTED

判定。

APPROVED

后执行

/peach-qa-gate

，

REJECTED

则通过Ralph Loop转回dev Agent修改后重新验证。

完成报告至少包含以下内容：

变更摘要和文件路径
执行的TDD/lint/build命令及结果
Contract Gate结果：通过/失败/跳过
TEST_ID别实现状态：未实现/实现中/部分实现/已实现/拦截

DECISION_REQUIRED

、

DB_DECISION_REQUIRED

、

DB_CHANGE_REQUIRED

项目

```
e2e_chain
```
状态与
```
peach-team-e2e
```
移交契约或后续建议

详细判定规则和报告字段遵循

references/qa-policy.md

，功能队列状态遵循

references/queue-workflow.md

，E2E移交遵循

references/dev-e2e-chain.md

。

역할 구성

Examples

역할	참조 파일	핵심 책임
backend-dev	`references/backend-dev-agent.md`	API 코드 생성, TDD/lint/build
backend-qa	`references/backend-qa-agent.md`	Backend 구조, TDD, lint, build, Spec 기반 검증
store-dev	`references/store-dev-agent.md`	Backend 타입 기반 Pinia Store 생성과 타입 검증
ui-dev	`references/ui-dev-agent.md`	Store 기반 UI 생성, 디자인 시스템/Figma/proto 반영
frontend-qa	`references/frontend-qa-agent.md`	Store/UI 구조, 타입, lint, build, AI Slop, Spec/proto 반영 검증

진짜 SoT는 대상 프로젝트의

test-data/

가이드 코드와 gen-* 스킬 reference다. team-dev는 같은 패턴을 팀 실행 방식으로 조율한다.

bash

undefined

QA와 완료

标准fullstack

QA 에이전트는

APPROVED / CONDITIONAL / REJECTED

로 판정한다.

APPROVED

후에는

/peach-qa-gate

를 실행하고,

REJECTED

는 Ralph Loop로 dev 에이전트 수정 후 재검증한다.

완료 보고에는 최소한 다음을 포함한다.

변경 요약과 파일 경로
실행한 TDD/lint/build 명령과 결과
Contract Gate 결과: 통과/실패/스킵
TEST_ID별 구현 상태: 구현전/구현중/일부구현/구현완료/차단

DECISION_REQUIRED

DB_DECISION_REQUIRED

DB_CHANGE_REQUIRED

항목

```
e2e_chain
```
상태와
```
peach-team-e2e
```
handoff contract 또는 후속 권장

상세 판정 규칙과 보고 필드는

references/qa-policy.md

, 기능 큐 상태는

references/queue-workflow.md

, E2E 인계는

references/dev-e2e-chain.md

를 따른다.

/peach-team-dev product-manage mode=fullstack spec=docs/spec/2026/05/example.md proto=<PROTO_REPO>/src/modules-task/2604/260427-<initial>-goods

Examples

仅Spec backend

bash

undefined

/peach-team-dev notice-board mode=backend spec=docs/spec/2026/05/example.md

표준 fullstack

开发后自动链式执行team-e2e

/peach-team-dev product-manage mode=fullstack spec=docs/spec/2026/05/example.md proto=<PROTO_REPO>/src/modules-task/2604/260427-<initial>-goods

/peach-team-dev product-manage mode=fullstack spec=docs/spec/2026/05/example.md e2e=auto

Spec만 backend

prompt模式

/peach-team-dev notice-board mode=backend spec=docs/spec/2026/05/example.md

/peach-team-dev "修复list.vue搜索后点击分页时搜索词被初始化的问题"

undefined

개발 후 team-e2e까지 자동 체인

prompt 모드

—

/peach-team-dev "list.vue 검색 후 페이지네이션 클릭 시 검색어 초기화되는 문제 수정"

undefined

—

peach-team-dev

Original

Translation

Peach Team Dev

Peach Team Dev

핵심 책임

核心职责

입력 모드

输入模式

Modes

Modes

Preconditions

Preconditions

표준 모드

标准模式

Spec만 모드

仅Spec模式

prompt 모드

prompt模式

Inputs

Inputs

표준 모드

标准模式

대규모 기능 큐 모드

大规模功能队列模式

Spec만 모드

仅Spec模式

prompt 모드

prompt模式

구현 기준 우선순위

实现标准优先级

Spec / schema / proto 충돌 처리

Spec / schema / proto冲突处理

항목별 team-dev 기준 vs 최종 검증

各项目team-dev标准 vs 最终验证

Reference 선택

Reference选择

실행 순서

QA与完成

역할 구성

Examples

QA와 완료

标准fullstack

Examples

仅Spec backend

표준 fullstack

开发后自动链式执行team-e2e

Spec만 backend

prompt模式

개발 후 team-e2e까지 자동 체인

相关技能

prompt 모드

관련 스킬