peach-team-refactor
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChinesePeach Agent Team Refactor
Peach Agent Team Refactor
Overview
概述
PeachSolution 레거시 모듈을 패턴으로 변환하는 리팩토링 전용 팀 스킬입니다.
test-data기존 를 대체하며, backend/frontend 역할 정의와 QA 절차를 이 문서 안에 포함합니다.
team-refactor这是一款专门用于将PeachSolution遗留模块转换为模式的重构团队技能。
test-data它将替代原有的,并在本文档中包含了backend/frontend的角色定义和QA流程。
team-refactorInputs
输入参数
bash
/peach-agent-team-refactor [모듈명] layer=backend|frontend|all [옵션]bash
/peach-agent-team-refactor [모듈명] layer=backend|frontend|all [옵션]옵션
옵션
model=sonnet|opus|haiku (서브에이전트 모델 override, 기본값: sonnet)
model=sonnet|opus|haiku (서브에이전트 모델 override, 기본값: sonnet)
file=Y|N
file=Y|N
ui=crud|two-depth|select-list
ui=crud|two-depth|select-list
tdd=Y|N
tdd=Y|N
undefinedundefinedPreconditions
前置条件
- 리팩토링 대상 모듈이 존재해야 합니다.
- Backend 리팩토링 시 DB 스키마가 존재해야 합니다.
- 기능 변경이 아니라 구조 정리만 수행합니다.
- 必须存在要重构的目标模块。
- 进行Backend重构时,必须存在DB架构。
- 仅进行结构整理,不修改功能。
Orchestration
编排流程
0. 입력 검증
0. 输入验证
에이전트 팀 기능 활성화 확인
确认代理团队功能已启用
아래 명령으로 에 에이전트 팀 플래그가 설정되어 있는지 확인합니다:
~/.claude/settings.jsonbash
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
공식 문서: https://code.claude.com/docs/ko/agent-teamslayer와 모듈명이 모두 지정되어야 다음 단계로 진행합니다.
누락된 경우 반드시 개발자에게 질문합니다.
layer 미지정 시:
layer를 선택해주세요:
1. backend — Backend만 리팩토링
2. frontend — Frontend만 리팩토링
3. all — 전체 리팩토링모듈명 미지정 시:
모듈명을 입력해주세요 (예: notice-board, product-manage):model 옵션:
- 미지정: 기본값 sonnet으로 모든 서브에이전트 실행
- 지정 시: 모든 서브에이전트를 해당 모델로 override
- 허용 값: sonnet, opus, haiku
通过以下命令检查中是否设置了代理团队标志:
~/.claude/settings.jsonbash
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
공식 문서: https://code.claude.com/docs/ko/agent-teams必须同时指定layer和模块名才能进入下一步。若有缺失,务必向开发者询问。
未指定layer时:
请选择layer:
1. backend — 仅重构Backend
2. frontend — 仅重构Frontend
3. all — 全量重构未指定模块名时:
请输入模块名(示例: notice-board, product-manage):model选项:
- 未指定:默认使用sonnet模型运行所有子代理
- 指定后:所有子代理将覆盖为该模型
- 允许值:sonnet, opus, haiku
1. 환경 확인
1. 环境检查
bash
undefinedbash
undefined레거시 모듈 존재 확인
检查遗留模块是否存在
ls api/src/modules/[모듈명]/
ls front/src/modules/[모듈명]/
ls api/src/modules/[모듈명]/
ls front/src/modules/[모듈명]/
DAO 라이브러리 감지 (중요!)
检测DAO库(重要!)
head -5 api/src/modules/test-data/dao/test-data.dao.ts
head -5 api/src/modules/test-data/dao/test-data.dao.ts
from 'bunqldb' → 재할당 방식 (sql${query} AND ...
)
${query} AND ...from 'bunqldb' → 重赋值方式 (sql${query} AND ...
)
${query} AND ...from 'sql-template-strings' → append 방식 (.append(SQLAND ...
))
AND ...from 'sql-template-strings' → append方式 (.append(SQLAND ...
))
AND ...Controller 프레임워크 감지
检测Controller框架
head -3 api/src/modules/test-data/controller/test-data.controller.ts
head -3 api/src/modules/test-data/controller/test-data.controller.ts
routing-controllers → Koa / elysia / createElysia → Elysia
routing-controllers → Koa / elysia / createElysia → Elysia
DB 스키마 확인
检查DB架构
ls api/db/schema/
undefinedls api/db/schema/
undefined1.5. 레거시 코드 분석 (Analyze)
1.5. 遗留代码分析(Analyze)
오케스트레이터가 레거시 모듈의 현재 상태를 분석하고, 서브에이전트 프롬프트에 컨텍스트로 주입합니다.
bash
undefined编排器将分析遗留模块的当前状态,并将上下文注入到子代理的提示词中。
bash
undefined레거시 코드 구조 파악
分析遗留代码结构
ls -la api/src/modules/[모듈명]/
ls -la front/src/modules/[모듈명]/
ls -la api/src/modules/[모듈명]/
ls -la front/src/modules/[모듈명]/
주요 파일 읽기
读取核心文件
cat api/src/modules/[모듈명]//*.ts
cat front/src/modules/[모듈명]//*.{vue,ts}
**분석 항목**:
1. 구조 gap: test-data 대비 파일 분리 상태, 네이밍 불일치
2. 로직 gap: test-data에 없는 비즈니스 로직 식별
3. 보존 목록: 기능으로서 반드시 유지해야 할 로직 목록화
4. 적응 결정: Must Follow → 강제 변환 / May Adapt → 보존할 로직과 변환 방식
**분석 결과를 서브에이전트에게 전달**:
- 각 에이전트 생성 시 프롬프트에 "레거시 분석 결과: [gap 목록], 보존 로직: [목록]"을 포함cat api/src/modules/[모듈명]//*.ts
cat front/src/modules/[모듈명]//*.{vue,ts}
**分析项**:
1. 结构差异:与test-data相比的文件拆分状态、命名不一致问题
2. 逻辑差异:识别test-data中没有的业务逻辑
3. 保留列表:必须作为功能保留的逻辑清单
4. 适配决策:Must Follow → 强制转换 / May Adapt → 保留逻辑及转换方式
**向子代理传递分析结果**:
- 创建每个代理时,在提示词中包含「遗留分析结果: [差异列表], 保留逻辑: [清单]」2. 팀 구성 다이어그램
2. 团队构成示意图
layer=all
refactor-backend ──→ backend-qa (병렬)
│
└──→ refactor-frontend ──→ frontend-qalayer=backend
refactor-backend ──→ backend-qalayer=frontend
refactor-frontend ──→ frontend-qalayer=all
refactor-backend ──→ backend-qa (并行)
│
└──→ refactor-frontend ──→ frontend-qalayer=backend
refactor-backend ──→ backend-qalayer=frontend
refactor-frontend ──→ frontend-qa3. 팀 생성
3. 创建团队
TeamCreate: team_name="[모듈명]-refactor-team"TeamCreate: team_name="[모듈명]-refactor-team"layer=all
layer=all
TaskCreate:
- "Backend 리팩토링" (owner: refactor-backend)
- "Backend QA 검증" (blockedBy: Task1, owner: backend-qa)
- "Frontend 리팩토링" (blockedBy: Task1, owner: refactor-frontend)
- "Frontend QA 검증" (blockedBy: Task3, owner: frontend-qa)
TaskCreate:
- "Backend重构" (owner: refactor-backend)
- "Backend QA验证" (blockedBy: Task1, owner: backend-qa)
- "Frontend重构" (blockedBy: Task1, owner: refactor-frontend)
- "Frontend QA验证" (blockedBy: Task3, owner: frontend-qa)
layer=backend
layer=backend
TaskCreate:
- "Backend 리팩토링" (owner: refactor-backend)
- "Backend QA 검증" (blockedBy: Task1, owner: backend-qa)
TaskCreate:
- "Backend重构" (owner: refactor-backend)
- "Backend QA验证" (blockedBy: Task1, owner: backend-qa)
layer=frontend
layer=frontend
TaskCreate:
- "Frontend 리팩토링" (owner: refactor-frontend)
- "Frontend QA 검증" (blockedBy: Task1, owner: frontend-qa)
undefinedTaskCreate:
- "Frontend重构" (owner: refactor-frontend)
- "Frontend QA验证" (blockedBy: Task1, owner: frontend-qa)
undefined역할별 지시
各角色指令
각 역할의 전체 정의(페르소나, Bounded Autonomy, 워크플로우)는 에 있습니다.
서브에이전트 생성 시 해당 파일의 전체 내용을 프롬프트에 포함합니다.
옵션이 지정된 경우, 각 에이전트 호출 시 model 파라미터로 전달하여 frontmatter 기본값을 override합니다.
references/model=| 역할 | 참조 파일 | 핵심 스킬 |
|---|---|---|
| refactor-backend | references/refactor-backend-agent.md | peach-refactor-backend |
| backend-qa | references/backend-qa-agent.md | 검증 전용 (읽기전용, worktree) |
| refactor-frontend | references/refactor-frontend-agent.md | peach-refactor-frontend |
| frontend-qa | references/frontend-qa-agent.md | 검증 전용 (읽기전용, worktree) |
各角色的完整定义(人设、边界自治、工作流)位于目录下。创建子代理时,需将对应文件的全部内容包含到提示词中。若指定了选项,调用每个代理时需传递model参数以覆盖frontmatter默认值。
references/model=| 角色 | 参考文件 | 核心技能 |
|---|---|---|
| refactor-backend | references/refactor-backend-agent.md | peach-refactor-backend |
| backend-qa | references/backend-qa-agent.md | 专用验证(只读、worktree) |
| refactor-frontend | references/refactor-frontend-agent.md | peach-refactor-frontend |
| frontend-qa | references/frontend-qa-agent.md | 专用验证(只读、worktree) |
refactor-backend
refactor-backend
- 기준으로 type/dao/service/controller/test를 정리합니다.
peach-refactor-backend - DAO 라이브러리 분기:
- 감지 시: 재할당 방식 (
bunqldb${query} AND field = ${val}``)sql\ - 감지 시: append 방식 (
sql-template-stringsAND field = ${val}``).append(SQL\
- 기존 기능은 유지하고 구조만 개선합니다.
- 4단계 리팩토링 순서: Type → DAO → Service/Controller → TDD
- 완료 기준: ,
bun test,bun run lint:fixedbun run build - 상세: 참조
references/refactor-backend-agent.md
- 按照标准整理type/dao/service/controller/test。
peach-refactor-backend - DAO库分支:
- 检测到时:使用重赋值方式 (
bunqldb${query} AND field = ${val}``)sql\ - 检测到时:使用append方式 (
sql-template-stringsAND field = ${val}``).append(SQL\
- 检测到
- 保留原有功能,仅优化结构。
- 四步重构顺序:Type → DAO → Service/Controller → TDD
- 完成标准:、
bun test、bun run lint:fixed全部通过bun run build - 详情:参考
references/refactor-backend-agent.md
backend-qa
backend-qa
- 리팩토링 후 구조, 패턴, 테스트, 빌드를 검증합니다.
- 패턴 준수 여부를 확인합니다.
test-data - QA 체크리스트 (7항목):
- ,
type/,dao/,service/,controller/구조 존재test/ - Service static 메서드 규칙 준수
- FK 제약조건 없음
- 통과
bun test - 통과
bun run lint:fixed - 성공
bun run build - 기능 100% 보존 확인
- 상세: 참조
references/backend-qa-agent.md
- 验证重构后的结构、模式、测试及构建结果。
- 检查是否符合模式。
test-data - QA检查清单(7项):
- 存在、
type/、dao/、service/、controller/结构test/ - 遵循Service静态方法规则
- 无FK约束
- 通过
bun test - 通过
bun run lint:fixed - 成功
bun run build - 确认功能100%保留
- 存在
- 详情:参考
references/backend-qa-agent.md
refactor-frontend
refactor-frontend
- 기준으로 type/store/pages/modals를 정리합니다.
peach-refactor-frontend - URL watch 패턴, Composition API, Pinia Option API를 강제합니다.
- 3단계 리팩토링 순서: Type & Store → Pages → Modals
- 완료 기준: ,
bunx vue-tsc --noEmit,bun run lint:fixbun run build - 상세: 참조
references/refactor-frontend-agent.md
- 按照标准整理type/store/pages/modals。
peach-refactor-frontend - 强制使用URL watch模式、Composition API、Pinia Option API。
- 三步重构顺序:Type & Store → Pages → Modals
- 完成标准:、
bunx vue-tsc --noEmit、bun run lint:fix全部通过bun run build - 详情:参考
references/refactor-frontend-agent.md
frontend-qa
frontend-qa
- 파일 구조, watch 패턴, UI 패턴, 빌드 결과를 검증합니다.
- 금지된 UI 패턴과 타입 규칙 위반 여부를 확인합니다.
- QA 체크리스트 (8항목):
- 파일 구조 (pages/, modals/, store/, type/) 존재
- Composition API () 패턴 준수
<script setup> - Pinia Option API Store 패턴 준수
- URL watch 패턴 적용 여부
- ,
listAction,resetAction함수 존재listMovePage - 통과
bunx vue-tsc --noEmit - 통과
bun run lint:fix - 성공 + AI Slop 제거 확인
bun run build
- 상세: 참조
references/frontend-qa-agent.md
- 验证文件结构、watch模式、UI模式及构建结果。
- 检查是否存在禁用的UI模式和类型规则违反情况。
- QA检查清单(8项):
- 存在文件结构(pages/, modals/, store/, type/)
- 遵循Composition API ()模式
<script setup> - 遵循Pinia Option API Store模式
- 是否应用URL watch模式
- 存在、
listAction、resetAction函数listMovePage - 通过
bunx vue-tsc --noEmit - 通过
bun run lint:fix - 成功 + 确认已移除AI Slop
bun run build
- 详情:参考
references/frontend-qa-agent.md
QA 판정 처리 (3단계)
QA判定处理(三阶段)
QA 에이전트(backend-qa, frontend-qa)는 APPROVED / CONDITIONAL / REJECTED 3단계로 판정합니다.
오케스트레이터가 Architect 역할을 수행하여 판정을 처리합니다.
QA代理(backend-qa, frontend-qa)将以APPROVED / CONDITIONAL / REJECTED三个阶段进行判定。编排器将承担Architect角色处理判定结果。
✅ APPROVED
✅ APPROVED
QA → SendMessage → 오케스트레이터: "APPROVED" + 검증 결과
오케스트레이터 → /peach-qa-gate 자동 실행
→ 완료QA → SendMessage → 编排器: "APPROVED" + 验证结果
编排器 → 自动执行/peach-qa-gate
→ 完成⚠️ CONDITIONAL
⚠️ CONDITIONAL
QA → SendMessage → 오케스트레이터: "CONDITIONAL" + 조건 내용 + 왜 REJECTED가 아닌지 근거
오케스트레이터 판단:
"조건 수용" → dev 에이전트에 수정 지시 → QA 재검증
"조건 무시" → 판단 근거 기록 후 APPROVED로 처리규칙:
- CONDITIONAL은 Ralph Loop가 아닙니다. 오케스트레이터 판단 전까지 완료 처리 금지.
- QA는 조건 항목 최소 1개 + 왜 REJECTED가 아닌지 근거를 함께 보고해야 합니다.
- 오케스트레이터가 "무시"를 선택한 경우 근거를 최종 완료 보고에 포함합니다.
QA → SendMessage → 编排器: "CONDITIONAL" + 条件内容 + 未判定为REJECTED的理由
编排器判定:
"接受条件" → 指示开发代理修改 → QA重新验证
"忽略条件" → 记录判定理由后按APPROVED处理规则:
- CONDITIONAL不属于Ralph Loop。在编排器判定前禁止完成处理。
- QA必须同时上报至少1项条件 + 未判定为REJECTED的理由。
- 若编排器选择「忽略」,需将理由包含在最终完成报告中。
❌ REJECTED → Ralph Loop 작동
❌ REJECTED → 触发Ralph Loop
REJECTED 시 Ralph Loop(Vercel Labs) 패턴으로 구조화된 피드백을 주입합니다.
判定为REJECTED时,将以Ralph Loop(Vercel Labs)模式注入结构化反馈。
에스컬레이션 단계
升级阶段
| 반복 횟수 | 단계 | 행동 |
|---|---|---|
| 1~3회 | 자율 수정 | QA 피드백만으로 코드 수정 |
| 4회 | 가이드 재참조 | test-data 기준골격 전체 재읽기 후 수정 |
| 5~7회 | Codex 진단 | |
| 8~10회 | 최소 수정 | Must Follow 항목만 집중, 나머지 보류 |
| 11+ | 중단 | 사용자 에스컬레이션 |
| 重复次数 | 阶段 | 行动 |
|---|---|---|
| 1~3次 | 自主修改 | 仅根据QA反馈修改代码 |
| 4次 | 重新参考指南 | 完整阅读test-data标准框架后修改 |
| 5~7次 | Codex诊断 | 使用 |
| 8~10次 | 最小化修改 | 仅聚焦Must Follow项,其余暂不处理 |
| 11+次 | 终止 | 升级至用户手动介入 |
Codex 투입 조건 (5~7회)
Codex投入条件(5~7次)
- 시에만 투입 (settings.json에서
CODEX_AVAILABLE=true감지)"codex@openai-codex": true - : Codex 없이 기존 Ralph Loop 계속 (가이드 재참조)
CODEX_AVAILABLE=false - Codex 무응답/타임아웃: 60초 대기 → 응답 없으면 스킵, 기존 피드백으로 진행
- Codex 진단 결과 부실: 오케스트레이터가 무시하고 기존 피드백으로 진행
- 仅当时投入(检测settings.json中的
CODEX_AVAILABLE=true)"codex@openai-codex": true - : 继续原Ralph Loop流程(重新参考指南)
CODEX_AVAILABLE=false - Codex无响应/超时: 等待60秒 → 无响应则跳过,按原反馈继续
- Codex诊断结果不合格: 编排器忽略该结果,按原反馈继续
적용 방식
执行方式
- Backend QA REJECTED → refactor-backend 수정 → backend-qa 재검증 (SendMessage)
- Frontend QA REJECTED → refactor-frontend 수정 → frontend-qa 재검증
- Backend QA判定REJECTED → refactor-backend修改 → backend-qa重新验证(SendMessage)
- Frontend QA判定REJECTED → refactor-frontend修改 → frontend-qa重新验证
에스컬레이션 보고
升级报告
undefinedundefinedRalph Loop 에스컬레이션
Ralph Loop升级
- 모듈: [모듈명]
- 반복: N/10회
- 단계: [현재 단계]
- 미해결: [위반 항목]
- 권장: [수동 개입 사항]
undefined- 模块: [모듈명]
- 重复次数: N/10次
- 当前阶段: [当前阶段]
- 未解决项: [违规项]
- 建议: [手动介入事项]
undefinedCompletion
完成标准
기능 100% 보존과 QA APPROVED가 모두 확인되어야 완료입니다.
必须同时确认功能100%保留和QA APPROVED才能完成。
1. 증거 수집
1. 收集证据
오케스트레이터가 를 자동 실행 → 증거 보고서 생성
/peach-qa-gate- 판정이 ❌이면 해당 항목 수정 후 재실행
- 판정이 ✅이면 다음 단계 진행
编排器自动执行 → 生成证据报告
/peach-qa-gate- 若判定为❌,修改对应项后重新执行
- 若判定为✅,进入下一步
2. 팀 정리
2. 清理团队
SendMessage(shutdown_request) → 모든 팀원에게
TeamDelete → 팀 정리SendMessage(shutdown_request) → 发送给所有团队成员
TeamDelete → 清理团队완료 보고 형식
完成报告格式
✅ 리팩토링 팀 작업 완료
모듈: [모듈명]
layer: [all|backend|frontend]
결과:
✅ refactor-backend: Backend 리팩토링 완료
✅ backend-qa: TDD X개 통과
✅ refactor-frontend: Frontend 리팩토링 완료
✅ 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
├── front/src/modules/[모듈명]/pages/
└── front/src/modules/[모듈명]/modals/
변경 요약:
- [레거시 패턴 → 신규 패턴 목록]
- [제거된 AI Slop 항목]
- [개선된 구조 설명]✅ 重构团队任务完成
模块: [모듈명]
layer: [all|backend|frontend]
结果:
✅ refactor-backend: Backend重构完成
✅ backend-qa: 通过X项TDD测试
✅ refactor-frontend: Frontend重构完成
✅ 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
├── front/src/modules/[모듈명]/pages/
└── front/src/modules/[모듈명]/modals/
变更摘要:
- [遗留模式 → 新模式列表]
- [已移除的AI Slop项]
- [结构优化说明]Examples
示例
bash
undefinedbash
undefined전체 리팩토링
全量重构
/peach-agent-team-refactor notice-board layer=all
/peach-agent-team-refactor notice-board layer=all
Backend만 리팩토링
仅重构Backend
/peach-agent-team-refactor product-manage layer=backend tdd=Y
/peach-agent-team-refactor product-manage layer=backend tdd=Y
Frontend만 리팩토링
仅重构Frontend
/peach-agent-team-refactor member-data layer=frontend ui=two-depth
/peach-agent-team-refactor member-data layer=frontend ui=two-depth
opus 모델로 전체 리팩토링
使用opus模型全量重构
/peach-agent-team-refactor notice-board layer=all model=opus
undefined/peach-agent-team-refactor notice-board layer=all model=opus
undefined