peach-team-refactor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Peach Agent Team Refactor

Peach Agent Team Refactor

Overview

概述

PeachSolution 레거시 모듈을
test-data
패턴으로 변환하는 리팩토링 전용 팀 스킬입니다.
기존
team-refactor
를 대체하며, backend/frontend 역할 정의와 QA 절차를 이 문서 안에 포함합니다.
这是一款专门用于将PeachSolution遗留模块转换为
test-data
模式的重构团队技能。
它将替代原有的
team-refactor
,并在本文档中包含了backend/frontend的角色定义和QA流程。

Inputs

输入参数

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

undefined
undefined

Preconditions

前置条件

  • 리팩토링 대상 모듈이 존재해야 합니다.
  • Backend 리팩토링 시 DB 스키마가 존재해야 합니다.
  • 기능 변경이 아니라 구조 정리만 수행합니다.
  • 必须存在要重构的目标模块。
  • 进行Backend重构时,必须存在DB架构。
  • 仅进行结构整理,不修改功能。

Orchestration

编排流程

0. 입력 검증

0. 输入验证

에이전트 팀 기능 활성화 확인

确认代理团队功能已启用

아래 명령으로
~/.claude/settings.json
에 에이전트 팀 플래그가 설정되어 있는지 확인합니다:
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
공식 문서: 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으로 모든 서브에이전트 실행
  • 지정 시: 모든 서브에이전트를 해당 모델로 override
  • 허용 값: sonnet, opus, haiku
通过以下命令检查
~/.claude/settings.json
中是否设置了代理团队标志:
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
공식 문서: 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
undefined
bash
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 ...
)

from 'bunqldb' → 重赋值方式 (sql
${query} AND ...
)

from 'sql-template-strings' → append 방식 (.append(SQL
AND ...
))

from 'sql-template-strings' → append方式 (.append(SQL
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/
undefined
ls api/db/schema/
undefined

1.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-qa
layer=backend
refactor-backend ──→ backend-qa
layer=frontend
refactor-frontend ──→ frontend-qa
layer=all
refactor-backend ──→ backend-qa        (并行)
         └──→ refactor-frontend ──→ frontend-qa
layer=backend
refactor-backend ──→ backend-qa
layer=frontend
refactor-frontend ──→ frontend-qa

3. 팀 생성

3. 创建团队

TeamCreate: team_name="[모듈명]-refactor-team"
TeamCreate: team_name="[모듈명]-refactor-team"

layer=all

layer=all

TaskCreate:
  1. "Backend 리팩토링" (owner: refactor-backend)
  2. "Backend QA 검증" (blockedBy: Task1, owner: backend-qa)
  3. "Frontend 리팩토링" (blockedBy: Task1, owner: refactor-frontend)
  4. "Frontend QA 검증" (blockedBy: Task3, owner: frontend-qa)
TaskCreate:
  1. "Backend重构" (owner: refactor-backend)
  2. "Backend QA验证" (blockedBy: Task1, owner: backend-qa)
  3. "Frontend重构" (blockedBy: Task1, owner: refactor-frontend)
  4. "Frontend QA验证" (blockedBy: Task3, owner: frontend-qa)

layer=backend

layer=backend

TaskCreate:
  1. "Backend 리팩토링" (owner: refactor-backend)
  2. "Backend QA 검증" (blockedBy: Task1, owner: backend-qa)
TaskCreate:
  1. "Backend重构" (owner: refactor-backend)
  2. "Backend QA验证" (blockedBy: Task1, owner: backend-qa)

layer=frontend

layer=frontend

TaskCreate:
  1. "Frontend 리팩토링" (owner: refactor-frontend)
  2. "Frontend QA 검증" (blockedBy: Task1, owner: frontend-qa)
undefined
TaskCreate:
  1. "Frontend重构" (owner: refactor-frontend)
  2. "Frontend QA验证" (blockedBy: Task1, owner: frontend-qa)
undefined

역할별 지시

各角色指令

각 역할의 전체 정의(페르소나, Bounded Autonomy, 워크플로우)는
references/
에 있습니다. 서브에이전트 생성 시 해당 파일의 전체 내용을 프롬프트에 포함합니다.
model=
옵션이 지정된 경우, 각 에이전트 호출 시 model 파라미터로 전달하여 frontmatter 기본값을 override합니다.
역할참조 파일핵심 스킬
refactor-backendreferences/refactor-backend-agent.mdpeach-refactor-backend
backend-qareferences/backend-qa-agent.md검증 전용 (읽기전용, worktree)
refactor-frontendreferences/refactor-frontend-agent.mdpeach-refactor-frontend
frontend-qareferences/frontend-qa-agent.md검증 전용 (읽기전용, worktree)
各角色的完整定义(人设、边界自治、工作流)位于
references/
目录下。创建子代理时,需将对应文件的全部内容包含到提示词中。若指定了
model=
选项,调用每个代理时需传递model参数以覆盖frontmatter默认值。
角色参考文件核心技能
refactor-backendreferences/refactor-backend-agent.mdpeach-refactor-backend
backend-qareferences/backend-qa-agent.md专用验证(只读、worktree)
refactor-frontendreferences/refactor-frontend-agent.mdpeach-refactor-frontend
frontend-qareferences/frontend-qa-agent.md专用验证(只读、worktree)

refactor-backend

refactor-backend

  • peach-refactor-backend
    기준으로 type/dao/service/controller/test를 정리합니다.
  • DAO 라이브러리 분기:
    • bunqldb
      감지 시: 재할당 방식 (
      sql\
      ${query} AND field = ${val}``)
    • sql-template-strings
      감지 시: append 방식 (
      .append(SQL\
      AND field = ${val}``)
  • 기존 기능은 유지하고 구조만 개선합니다.
  • 4단계 리팩토링 순서: Type → DAO → Service/Controller → TDD
  • 완료 기준:
    bun test
    ,
    bun run lint:fixed
    ,
    bun run build
  • 상세:
    references/refactor-backend-agent.md
    참조
  • 按照
    peach-refactor-backend
    标准整理type/dao/service/controller/test。
  • DAO库分支:
    • 检测到
      bunqldb
      时:使用重赋值方式 (
      sql\
      ${query} AND field = ${val}``)
    • 检测到
      sql-template-strings
      时:使用append方式 (
      .append(SQL\
      AND field = ${val}``)
  • 保留原有功能,仅优化结构。
  • 四步重构顺序: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항목):
    1. type/
      ,
      dao/
      ,
      service/
      ,
      controller/
      ,
      test/
      구조 존재
    2. Service static 메서드 규칙 준수
    3. FK 제약조건 없음
    4. bun test
      통과
    5. bun run lint:fixed
      통과
    6. bun run build
      성공
    7. 기능 100% 보존 확인
  • 상세:
    references/backend-qa-agent.md
    참조
  • 验证重构后的结构、模式、测试及构建结果。
  • 检查是否符合
    test-data
    模式。
  • QA检查清单(7项):
    1. 存在
      type/
      dao/
      service/
      controller/
      test/
      结构
    2. 遵循Service静态方法规则
    3. 无FK约束
    4. bun test
      通过
    5. bun run lint:fixed
      通过
    6. bun run build
      成功
    7. 确认功能100%保留
  • 详情:参考
    references/backend-qa-agent.md

refactor-frontend

refactor-frontend

  • peach-refactor-frontend
    기준으로 type/store/pages/modals를 정리합니다.
  • URL watch 패턴, Composition API, Pinia Option API를 강제합니다.
  • 3단계 리팩토링 순서: Type & Store → Pages → Modals
  • 완료 기준:
    bunx vue-tsc --noEmit
    ,
    bun run lint:fix
    ,
    bun run build
  • 상세:
    references/refactor-frontend-agent.md
    참조
  • 按照
    peach-refactor-frontend
    标准整理type/store/pages/modals。
  • 强制使用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항목):
    1. 파일 구조 (pages/, modals/, store/, type/) 존재
    2. Composition API (
      <script setup>
      ) 패턴 준수
    3. Pinia Option API Store 패턴 준수
    4. URL watch 패턴 적용 여부
    5. listAction
      ,
      resetAction
      ,
      listMovePage
      함수 존재
    6. bunx vue-tsc --noEmit
      통과
    7. bun run lint:fix
      통과
    8. bun run build
      성공 + AI Slop 제거 확인
  • 상세:
    references/frontend-qa-agent.md
    참조
  • 验证文件结构、watch模式、UI模式及构建结果。
  • 检查是否存在禁用的UI模式和类型规则违反情况。
  • QA检查清单(8项):
    1. 存在文件结构(pages/, modals/, store/, type/)
    2. 遵循Composition API (
      <script setup>
      )模式
    3. 遵循Pinia Option API Store模式
    4. 是否应用URL watch模式
    5. 存在
      listAction
      resetAction
      listMovePage
      函数
    6. bunx vue-tsc --noEmit
      通过
    7. bun run lint:fix
      通过
    8. bun run build
      成功 + 确认已移除AI Slop
  • 详情:参考
    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 진단
codex:codex-rescue
로 실패 원인 독립 진단 + 가이드 재참조
8~10회최소 수정Must Follow 항목만 집중, 나머지 보류
11+중단사용자 에스컬레이션
重复次数阶段行动
1~3次自主修改仅根据QA反馈修改代码
4次重新参考指南完整阅读test-data标准框架后修改
5~7次Codex诊断使用
codex:codex-rescue
独立诊断失败原因 + 重新参考指南
8~10次最小化修改仅聚焦Must Follow项,其余暂不处理
11+次终止升级至用户手动介入

Codex 투입 조건 (5~7회)

Codex投入条件(5~7次)

  • CODEX_AVAILABLE=true
    시에만 투입 (settings.json에서
    "codex@openai-codex": true
    감지)
  • CODEX_AVAILABLE=false
    : Codex 없이 기존 Ralph Loop 계속 (가이드 재참조)
  • Codex 무응답/타임아웃: 60초 대기 → 응답 없으면 스킵, 기존 피드백으로 진행
  • Codex 진단 결과 부실: 오케스트레이터가 무시하고 기존 피드백으로 진행
  • 仅当
    CODEX_AVAILABLE=true
    时投入(检测settings.json中的
    "codex@openai-codex": true
  • CODEX_AVAILABLE=false
    : 继续原Ralph Loop流程(重新参考指南)
  • 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重新验证

에스컬레이션 보고

升级报告

undefined
undefined

Ralph Loop 에스컬레이션

Ralph Loop升级

  • 모듈: [모듈명]
  • 반복: N/10회
  • 단계: [현재 단계]
  • 미해결: [위반 항목]
  • 권장: [수동 개입 사항]
undefined
  • 模块: [모듈명]
  • 重复次数: N/10次
  • 当前阶段: [当前阶段]
  • 未解决项: [违规项]
  • 建议: [手动介入事项]
undefined

Completion

完成标准

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