peach-team-3a

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Peach Team 3A

Peach Team 3A

Overview

概述

Architect → Builder → Reviewer → Architect 루프로 단일 기능을 완성하는 3-에이전트 팀 스킬입니다.
에이전트역할핵심 원칙
Architect설계 계획 수립 + 최종 결정권BRIEF를 SendMessage로 전달 → Reviewer 판정 수용/거부
BuilderBRIEF 기반 코드 구현범위 밖 터치 금지, 완료 후 파일 수정 금지, 자기 검토 + 검증 증거 제출
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-teampeach-team-3a
에이전트 수최대 5개3개 고정
적합 케이스대규모 fullstack단일 기능, 소규모 수정
판정 방식통과/실패 2단계APPROVED / CONDITIONAL / REJECTED 3단계
애매한 경우무조건 재작업Architect가 최종 판단
peach-teampeach-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가 판단)

undefined
undefined

Orchestration

编排流程

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
undefined
bash
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)
undefined
SKILL_BASE=$(dirname "$(find ~/.claude ~/.agents -path "*/peach-gen-backend/references" -type d 2>/dev/null | head -1)" 2>/dev/null)
undefined

2. 팀 구성 다이어그램

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. 各角色指令

각 역할의 전체 정의는
references/
에 있습니다. 서브에이전트 생성 시 해당 파일의 전체 내용을 프롬프트에 포함합니다.
model=
옵션이 지정된 경우, model 파라미터로 전달하여 frontmatter 기본값을 override합니다.
역할참조 파일실행 환경
architectreferences/architect-agent.md일반
builderreferences/builder-agent.md일반
reviewerreferences/reviewer-agent.mdworktree 격리
各角色的完整定义位于
references/
目录下。创建子Agent时,需将对应文件的全部内容纳入提示词中。若指定了
model=
选项,则通过model参数传递以覆盖frontmatter默认值。
角色参考文件运行环境
architectreferences/architect-agent.md普通环境
builderreferences/builder-agent.md普通环境
reviewerreferences/reviewer-agent.mdworktree隔离

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 진단
codex:codex-rescue
로 실패 원인 독립 진단 + 가이드 재참조
8~10회최소 수정Must Follow 항목만 집중, 나머지 보류
11+중단사용자 에스컬레이션
重复次数阶段行动
1~3次自主修正Builder仅通过Reviewer反馈进行修正
4次重新参考指南完整阅读test-data基准框架后修正
5~7次Codex诊断通过
codex:codex-rescue
独立诊断失败原因 + 重新参考指南
8~10次最小化修正仅聚焦Must Follow项,其余暂不处理
11+终止升级至人工介入

Codex 투입 조건 (5~7회 또는 REJECTED 2회 연속)

Codex介入条件(5~7次或连续2次REJECTED)

  • CODEX_AVAILABLE=true
    시에만 투입 (settings.json에서
    "codex@openai-codex": true
    감지)
  • REJECTED 2회 연속 시: Ralph Loop 5회 대기 없이 즉시
    codex:codex-rescue
    투입 (3A는 소규모 루프 특성상 조기 탈출 유도)
  • CODEX_AVAILABLE=false
    : Codex 없이 기존 Ralph Loop 계속 (가이드 재참조)
  • Codex 무응답/타임아웃: 60초 대기 → 응답 없으면 스킵, 기존 피드백으로 진행
  • Codex 진단 결과 부실: 오케스트레이터가 무시하고 기존 피드백으로 진행
  • 仅当
    CODEX_AVAILABLE=true
    时介入(检测settings.json中的
    "codex@openai-codex": true
  • 连续2次REJECTED时: 无需等待Ralph Loop到第5次,立即启动
    codex:codex-rescue
    (3A为小规模循环,鼓励提前退出)
  • CODEX_AVAILABLE=false
    : 不使用Codex,继续执行原有Ralph Loop(重新参考指南)
  • Codex无响应/超时: 等待60秒 → 仍无响应则跳过,按原有反馈继续
  • Codex诊断结果无效: 编排器忽略该结果,按原有反馈继续

에스컬레이션 보고

升级报告

undefined
undefined

Ralph 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 →
    completed
    / REJECTED → Builder 재작업
与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 →
    completed
    / 判定为REJECTED → Builder重新工作

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
undefined
bash
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