peach-team-3a
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePeach Team 3A
Peach Team 3A
Overview
概述
Architect → Builder → Reviewer → Architect 루프로 단일 기능을 완성하는 3-에이전트 팀 스킬입니다.
| 에이전트 | 역할 | 핵심 원칙 |
|---|---|---|
| Architect | 설계 계획 수립 + 최종 결정권 | BRIEF를 SendMessage로 전달 → Reviewer 판정 수용/거부 |
| Builder | BRIEF 기반 코드 구현 | 범위 밖 터치 금지, 완료 후 파일 수정 금지, 자기 검토 + 검증 증거 제출 |
| Reviewer | 독립 검증 + 3단계 판정 | qa-gate + 코드 리뷰 통합, 읽기전용, worktree 격리, CONDITIONAL 남용 금지 |
这是一套通过Architect → Builder → Reviewer → Architect循环完成单一功能的3-Agent团队技能。
| Agent | 职责 | 核心原则 |
|---|---|---|
| Architect | 制定设计方案 + 拥有最终决定权 | 通过SendMessage传递BRIEF → 接受/拒绝Reviewer的判定 |
| Builder | 基于BRIEF实现代码 | 禁止触碰范围外内容,完成后禁止修改文件,提交自我审查+验证证据 |
| Reviewer | 独立验证 + 三级判定 | 整合qa-gate+代码审查,只读模式,worktree隔离,禁止滥用CONDITIONAL |
peach-team과의 차이
与peach-team的差异
| peach-team | peach-team-3a | |
|---|---|---|
| 에이전트 수 | 최대 5개 | 3개 고정 |
| 적합 케이스 | 대규모 fullstack | 단일 기능, 소규모 수정 |
| 판정 방식 | 통과/실패 2단계 | APPROVED / CONDITIONAL / REJECTED 3단계 |
| 애매한 경우 | 무조건 재작업 | Architect가 최종 판단 |
| peach-team | peach-team-3a | |
|---|---|---|
| Agent数量 | 最多5个 | 固定3个 |
| 适用场景 | 大规模全栈开发 | 单一功能、小规模修改 |
| 判定方式 | 通过/失败二级 | APPROVED / CONDITIONAL / REJECTED三级 |
| 模糊情况处理 | 无条件重新工作 | 由Architect最终判定 |
Inputs
输入
bash
/peach-team-3a [작업 설명]bash
/peach-team-3a [작업 설명]옵션
옵션
model=sonnet|opus|haiku (서브에이전트 모델 override, 기본값: sonnet)
model=sonnet|opus|haiku (서브에이전트 모델 override, 기본값: sonnet)
layer=backend|frontend|fullstack (구현 범위, 미지정 시 Architect가 판단)
layer=backend|frontend|fullstack (구현 범위, 미지정 시 Architect가 판단)
undefinedundefinedOrchestration
编排流程
0. 입력 검증
0. 输入验证
에이전트 팀 기능 활성화 확인
确认Agent团队功能是否启用
bash
cat ~/.claude/settings.json | grep -i "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"설정이 없거나 이 아니면 즉시 중단하고 안내를 출력합니다:
"1"⚠️ 에이전트 팀 기능이 비활성화되어 있습니다.
~/.claude/settings.json에 아래 내용을 추가한 후 Claude Code를 재시작하세요:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
설정 가이드: https://github.com/peachSolution/peach-harness/blob/main/docs/06-에이전트팀-설정.md작업 설명이 누락된 경우 질문합니다:
어떤 기능을 구현할까요? (예: "공지사항 목록 API 추가", "회원 상태 필드 수정")model 옵션:
- 미지정: 기본값 sonnet으로 서브에이전트 실행
- 지정 시: 모든 서브에이전트를 해당 모델로 override
- 허용 값: sonnet, opus, haiku
bash
cat ~/.claude/settings.json | grep -i "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"若不存在该设置或值不为,则立即终止并输出提示:
"1"⚠️ Agent团队功能未启用。
请在~/.claude/settings.json中添加以下内容后重启Claude Code:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
设置指南: https://github.com/peachSolution/peach-harness/blob/main/docs/06-에이전트팀-설정.md若缺少任务描述,则询问用户:
需要实现什么功能?(示例:"添加公告列表API"、"修改会员状态字段")model选项:
- 未指定:默认使用sonnet模型运行子Agent
- 指定后:所有子Agent均使用该模型覆盖默认设置
- 允许值:sonnet, opus, haiku
1. 환경 확인
1. 环境检查
bash
undefinedbash
undefined프로젝트 구조 파악
识别项目结构
ls api/src/modules/ 2>/dev/null
ls front/src/modules/ 2>/dev/null
ls api/src/modules/ 2>/dev/null
ls front/src/modules/ 2>/dev/null
test-data 가이드코드 존재 확인
检查test-data示例代码是否存在
ls api/src/modules/test-data/ 2>/dev/null
ls front/src/modules/test-data/ 2>/dev/null
ls api/src/modules/test-data/ 2>/dev/null
ls front/src/modules/test-data/ 2>/dev/null
DAO 라이브러리 감지
检测DAO库
head -5 api/src/modules/test-data/dao/test-data.dao.ts 2>/dev/null
head -5 api/src/modules/test-data/dao/test-data.dao.ts 2>/dev/null
from 'bunqldb' → 재할당 방식
from 'bunqldb' → 重分配方式
from 'sql-template-strings' → append 방식
from 'sql-template-strings' → 追加方式
Controller 프레임워크 감지
检测Controller框架
head -3 api/src/modules/test-data/controller/test-data.controller.ts 2>/dev/null
head -3 api/src/modules/test-data/controller/test-data.controller.ts 2>/dev/null
_common 구성 감지
检测_common配置
ls api/src/modules/_common/ 2>/dev/null
ls api/src/modules/_common/constants/ 2>/dev/null
ls api/src/modules/_common/ 2>/dev/null
ls api/src/modules/_common/constants/ 2>/dev/null
스킬 references 경로 감지
识别技能references路径
SKILL_BASE=$(dirname "$(find ~/.claude ~/.agents -path "*/peach-gen-backend/references" -type d 2>/dev/null | head -1)" 2>/dev/null)
undefinedSKILL_BASE=$(dirname "$(find ~/.claude ~/.agents -path "*/peach-gen-backend/references" -type d 2>/dev/null | head -1)" 2>/dev/null)
undefined2. 팀 구성 다이어그램
2. 团队架构图
Architect
│
│ SendMessage: BRIEF 전달
▼
Builder ──────────────────────────────────┐
│ │ REJECTED → Ralph Loop
│ SendMessage: 구현 완료 + 자기 검토 │
▼ │
Reviewer (worktree 격리) │
│ │
├── APPROVED ──→ SendMessage → Architect│
├── CONDITIONAL → SendMessage → Architect│
└── REJECTED ──→ SendMessage → Builder ─┘Architect
│
│ SendMessage: 传递BRIEF
▼
Builder ──────────────────────────────────┐
│ │ REJECTED → Ralph Loop
│ SendMessage: 实现完成 + 自我审查 │
▼ │
Reviewer (worktree隔离) │
│ │
├── APPROVED ──→ SendMessage → Architect│
├── CONDITIONAL → SendMessage → Architect│
└── REJECTED ──→ SendMessage → Builder ─┘3. 팀 생성 및 작업 등록
3. 团队创建与任务登记
TeamCreate: team_name="3a-[작업축약명]-team"
TaskCreate:
1. "설계 계획 수립" (owner: architect)
2. "코드 구현" (blockedBy: Task1, owner: builder)
3. "검증 및 판정" (blockedBy: Task2, owner: reviewer)TeamCreate: team_name="3a-[작업축약명]-team"
TaskCreate:
1. "制定设计方案" (owner: architect)
2. "代码实现" (blockedBy: Task1, owner: builder)
3. "验证与判定" (blockedBy: Task2, owner: reviewer)4. 역할별 지시
4. 各角色指令
각 역할의 전체 정의는 에 있습니다.
서브에이전트 생성 시 해당 파일의 전체 내용을 프롬프트에 포함합니다.
옵션이 지정된 경우, model 파라미터로 전달하여 frontmatter 기본값을 override합니다.
references/model=| 역할 | 참조 파일 | 실행 환경 |
|---|---|---|
| architect | references/architect-agent.md | 일반 |
| builder | references/builder-agent.md | 일반 |
| reviewer | references/reviewer-agent.md | worktree 격리 |
各角色的完整定义位于目录下。创建子Agent时,需将对应文件的全部内容纳入提示词中。若指定了选项,则通过model参数传递以覆盖frontmatter默认值。
references/model=| 角色 | 参考文件 | 运行环境 |
|---|---|---|
| architect | references/architect-agent.md | 普通环境 |
| builder | references/builder-agent.md | 普通环境 |
| reviewer | references/reviewer-agent.md | worktree隔离 |
Architect 지시 포인트
Architect指令要点
오케스트레이터가 Architect 에이전트 생성 시 프롬프트에 포함할 컨텍스트:
- 작업 설명:
[사용자 입력 그대로] - 환경 정보: DAO 라이브러리, Controller 프레임워크, modules 경로, _common 상수 목록
- 가이드코드 위치: ,
api/src/modules/test-data/front/src/modules/test-data/ - references 경로: ,
${SKILL_BASE}/peach-gen-backend/references/${SKILL_BASE}/peach-gen-ui/references/ - 상세: 참조
references/architect-agent.md
编排器创建Architect Agent时,需在提示词中包含以下上下文:
- 任务描述:
[用户输入内容] - 环境信息: DAO库、Controller框架、modules路径、_common常量列表
- 示例代码位置: ,
api/src/modules/test-data/front/src/modules/test-data/ - references路径: ,
${SKILL_BASE}/peach-gen-backend/references/${SKILL_BASE}/peach-gen-ui/references/ - 详情: 参考
references/architect-agent.md
Builder 지시 포인트
Builder指令要点
Architect가 BRIEF를 SendMessage로 전달한 후 Builder를 스핀업합니다.
오케스트레이터는 Builder 에이전트 생성 시 아래를 포함합니다:
- Architect의 BRIEF 내용 (SendMessage로 수신한 전체 텍스트)
- 환경 정보: Architect 지시와 동일
- 상세: 참조
references/builder-agent.md
Architect通过SendMessage传递BRIEF后,启动Builder。编排器创建Builder Agent时需包含以下内容:
- Architect的BRIEF内容(通过SendMessage接收的全部文本)
- 环境信息: 与Architect指令相同
- 详情: 参考
references/builder-agent.md
Reviewer 지시 포인트
Reviewer指令要点
Builder가 구현 완료를 SendMessage로 보고한 후 Reviewer를 스핀업합니다.
오케스트레이터는 Reviewer 에이전트 생성 시 아래를 포함합니다:
- Builder의 구현 보고 내용 (구현 파일 목록 + 자기 검토 결과)
- Architect의 BRIEF 내용 (판정 기준)
- 상세: 참조
references/reviewer-agent.md
Builder通过SendMessage报告实现完成后,启动Reviewer。编排器创建Reviewer Agent时需包含以下内容:
- Builder的实现报告内容(实现文件列表 + 自我审查结果)
- Architect的BRIEF内容(判定标准)
- 详情: 参考
references/reviewer-agent.md
5. Reviewer 판정 처리
5. Reviewer判定处理
Reviewer가 판정 결과를 SendMessage로 오케스트레이터에게 보고하면, 오케스트레이터가 처리합니다.
Reviewer通过SendMessage向编排器报告判定结果后,由编排器进行处理。
✅ APPROVED
✅ APPROVED
Reviewer → SendMessage → 오케스트레이터: "APPROVED" + 검증 결과
오케스트레이터 → SendMessage → Architect: 완료 보고
오케스트레이터 → /peach-qa-gate 자동 실행 (최종 증거 수집)
오케스트레이터 → 팀 정리Reviewer → SendMessage → 编排器: "APPROVED" + 验证结果
编排器 → SendMessage → Architect: 完成报告
编排器 → 自动运行/peach-qa-gate(收集最终证据)
编排器 → 清理团队⚠️ CONDITIONAL
⚠️ CONDITIONAL
Reviewer → SendMessage → 오케스트레이터: "CONDITIONAL" + 조건 내용
오케스트레이터 → SendMessage → Architect: 조건 전달 + 판단 요청
Architect → SendMessage → 오케스트레이터:
"조건 수용" → 오케스트레이터 → SendMessage → Builder: 수정 지시 → Reviewer 재검증
"조건 무시" → 판단 근거 기록 후 APPROVED로 처리규칙:
- CONDITIONAL은 Ralph Loop가 아닙니다. Architect 판단 전까지 완료 처리 금지입니다.
- Reviewer는 조건 항목 + 왜 REJECTED가 아닌지 이유를 함께 보고해야 합니다.
- Architect가 "무시"를 선택한 경우 오케스트레이터는 근거를 최종 완료 보고에 포함합니다.
Reviewer → SendMessage → 编排器: "CONDITIONAL" + 条件内容
编排器 → SendMessage → Architect: 传递条件 + 请求判定
Architect → SendMessage → 编排器:
"接受条件" → 编排器 → SendMessage → Builder: 修改指令 → Reviewer重新验证
"忽略条件" → 记录判定依据后按APPROVED处理规则:
- CONDITIONAL不属于Ralph Loop。在Architect做出判定前,禁止标记为完成。
- Reviewer必须同时报告条件项 + 未判定为REJECTED的原因。
- 若Architect选择"忽略",编排器需将依据纳入最终完成报告。
❌ REJECTED — Ralph Loop 작동
❌ REJECTED — Ralph Loop启动
Reviewer → SendMessage → 오케스트레이터: "REJECTED" + 수정 필요 항목
오케스트레이터 → Ralph Loop 단계 판단
오케스트레이터 → SendMessage → Builder: 피드백 + 수정 지시
Builder 수정 완료 → SendMessage → 오케스트레이터 → Reviewer 재검증Reviewer → SendMessage → 编排器: "REJECTED" + 需要修改的项
编排器 → 判断Ralph Loop阶段
编排器 → SendMessage → Builder: 反馈 + 修改指令
Builder完成修改 → SendMessage → 编排器 → Reviewer重新验证Ralph Loop (반복 검증 메커니즘)
Ralph Loop(重复验证机制)
REJECTED 시 단순 재시도가 아닌 구조화된 피드백 주입으로 반복합니다.
当判定为REJECTED时,并非简单重试,而是通过结构化反馈注入进行循环。
에스컬레이션 단계
升级阶段
| 반복 횟수 | 단계 | 행동 |
|---|---|---|
| 1~3회 | 자율 수정 | Reviewer 피드백만으로 Builder 수정 |
| 4회 | 가이드 재참조 | test-data 기준골격 전체 재읽기 후 수정 |
| 5~7회 | Codex 진단 | |
| 8~10회 | 최소 수정 | Must Follow 항목만 집중, 나머지 보류 |
| 11+ | 중단 | 사용자 에스컬레이션 |
| 重复次数 | 阶段 | 行动 |
|---|---|---|
| 1~3次 | 自主修正 | Builder仅通过Reviewer反馈进行修正 |
| 4次 | 重新参考指南 | 完整阅读test-data基准框架后修正 |
| 5~7次 | Codex诊断 | 通过 |
| 8~10次 | 最小化修正 | 仅聚焦Must Follow项,其余暂不处理 |
| 11+ | 终止 | 升级至人工介入 |
Codex 투입 조건 (5~7회 또는 REJECTED 2회 연속)
Codex介入条件(5~7次或连续2次REJECTED)
- 시에만 투입 (settings.json에서
CODEX_AVAILABLE=true감지)"codex@openai-codex": true - REJECTED 2회 연속 시: Ralph Loop 5회 대기 없이 즉시 투입 (3A는 소규모 루프 특성상 조기 탈출 유도)
codex:codex-rescue - : Codex 없이 기존 Ralph Loop 계속 (가이드 재참조)
CODEX_AVAILABLE=false - Codex 무응답/타임아웃: 60초 대기 → 응답 없으면 스킵, 기존 피드백으로 진행
- Codex 진단 결과 부실: 오케스트레이터가 무시하고 기존 피드백으로 진행
- 仅当时介入(检测settings.json中的
CODEX_AVAILABLE=true)"codex@openai-codex": true - 连续2次REJECTED时: 无需等待Ralph Loop到第5次,立即启动(3A为小规模循环,鼓励提前退出)
codex:codex-rescue - : 不使用Codex,继续执行原有Ralph Loop(重新参考指南)
CODEX_AVAILABLE=false - Codex无响应/超时: 等待60秒 → 仍无响应则跳过,按原有反馈继续
- Codex诊断结果无效: 编排器忽略该结果,按原有反馈继续
에스컬레이션 보고
升级报告
undefinedundefinedRalph Loop 에스컬레이션
Ralph Loop升级
- 작업: [작업 설명]
- 반복: N/10회
- 단계: [현재 단계]
- 미해결: [위반 항목]
- 권장: [수동 개입 사항]
undefined- 任务: [任务描述]
- 重复次数: N/10次
- 当前阶段: [当前阶段]
- 未解决项: [违规项]
- 建议: [人工介入事项]
undefined에이전트 간 통신 구조
Agent间通信架构
peach-team 계열과 동일하게 SendMessage + TaskUpdate로 통신합니다.
Architect → 오케스트레이터 (SendMessage): BRIEF 내용
오케스트레이터 → Builder 프롬프트에 BRIEF 포함하여 스핀업
Builder → 오케스트레이터 (SendMessage): 구현 완료 + 자기 검토 + 파일 목록
오케스트레이터 → Reviewer 프롬프트에 BRIEF + 구현 보고 포함하여 스핀업
Reviewer → 오케스트레이터 (SendMessage): 판정 + 검증 결과각 단계 완료 시 TaskUpdate로 상태를 갱신합니다:
- Task #1 (설계): Architect 완료 →
completed - Task #2 (구현): Builder 완료 →
completed - Task #3 (검증): Reviewer APPROVED → / REJECTED → Builder 재작업
completed
与peach-team系列相同,采用SendMessage + TaskUpdate进行通信。
Architect → 编排器 (SendMessage): BRIEF内容
编排器 → 在Builder提示词中包含BRIEF并启动
Builder → 编排器 (SendMessage): 实现完成 + 自我审查 + 文件列表
编排器 → 在Reviewer提示词中包含BRIEF + 实现报告并启动
Reviewer → 编排器 (SendMessage): 判定结果 + 验证结果每个阶段完成时,通过TaskUpdate更新状态:
- Task #1(设计): Architect完成 →
completed - Task #2(实现): Builder完成 →
completed - Task #3(验证): Reviewer判定为APPROVED → / 判定为REJECTED → Builder重新工作
completed
Completion
完成流程
1. 증거 수집
1. 证据收集
오케스트레이터가 를 자동 실행 → 증거 보고서 생성
/peach-qa-gate- 판정이 ❌이면 해당 항목 수정 후 재실행
- 판정이 ✅이면 다음 단계 진행
编排器自动运行 → 生成证据报告
/peach-qa-gate- 若判定为❌,修改对应项后重新运行
- 若判定为✅,进入下一阶段
2. 팀 정리
2. 团队清理
SendMessage(shutdown_request) → 모든 팀원에게
TeamDelete → 팀 정리SendMessage(shutdown_request) → 发送给所有团队成员
TeamDelete → 清理团队완료 보고 형식
完成报告格式
✅ 3A 팀 작업 완료
작업: [작업 설명]
반복: [총 Reviewer 검증 횟수]회
결과:
✅ Architect: BRIEF 수립 완료
✅ Builder: 구현 완료
✅ Reviewer: APPROVED (또는 CONDITIONAL → Architect 수용)
✅ qa-gate: 증거 보고서 생성 + 완료 가능 판정
생성/수정된 파일:
[파일 목록]
다음 단계:
[실행 방법 안내]✅ 3A团队任务完成
任务: [任务描述]
Reviewer验证总次数: [次数]
结果:
✅ Architect: BRIEF制定完成
✅ Builder: 实现完成
✅ Reviewer: APPROVED(或CONDITIONAL → Architect已接受)
✅ qa-gate: 生成证据报告 + 判定可完成
生成/修改的文件:
[文件列表]
下一步:
[执行方法说明]Examples
示例
bash
undefinedbash
undefined단일 API 추가
添加单一API
/peach-team-3a 공지사항 목록 조회 API 추가
/peach-team-3a 公告列表查询API添加
기존 기능 수정
修改现有功能
/peach-team-3a 회원 상태 필드에 '정지' 값 추가 layer=backend
/peach-team-3a 会员状态字段添加'停用'值 layer=backend
UI 컴포넌트 수정
修改UI组件
/peach-team-3a 상품 목록 페이지에 엑셀 다운로드 버튼 추가 layer=frontend
/peach-team-3a 商品列表页面添加Excel下载按钮 layer=frontend
opus 모델로 실행
使用opus模型运行
/peach-team-3a 결제 상태 전이 로직 구현 model=opus
undefined/peach-team-3a 支付状态流转逻辑实现 model=opus
undefined