peach-agent-team-refactor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Peach Agent Team Refactor

Peach Agent 团队重构

Overview

概述

PeachSolution 레거시 모듈을

test-data

패턴으로 변환하는 리팩토링 전용 팀 스킬입니다.

기존

team-refactor

를 대체하며, backend/frontend 역할 정의와 QA 절차를 이 문서 안에 포함합니다.

这是专门用于将PeachSolution遗留模块转换为

test-data

模式的团队重构技能。

它替代了原有

team-refactor

，本文档包含后端/前端的角色定义和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 (覆盖子Agent使用的模型，默认值: sonnet)

file=Y|N

ui=crud|two-depth|select-list

tdd=Y|N

undefined

undefined

Preconditions

前置条件

리팩토링 대상 모듈이 존재해야 합니다.
Backend 리팩토링 시 DB 스키마가 존재해야 합니다.
기능 변경이 아니라 구조 정리만 수행합니다.

必须存在待重构的模块。
重构后端时必须存在DB schema。
仅做结构整理，不修改功能。

Orchestration

编排流程

0. 입력 검증

0. 输入校验

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

检查Agent团队功能是否启用

아래 명령으로

~/.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

中已配置Agent团队功能标志：

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
官方文档: https://code.claude.com/docs/ko/agent-teams

必须同时指定layer和模块名才能进入下一步。如果有缺失，必须询问开发者补充。

未指定layer时：

请选择layer：
1. backend — 仅重构后端
2. frontend — 仅重构前端
3. all — 全栈重构

未指定模块名时：

请输入模块名（示例：notice-board, product-manage）：

model选项：

未指定：所有子Agent默认使用sonnet模型执行
指定后：所有子Agent都使用指定的模型覆盖默认配置
允许值：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

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

routing-controllers → Koa / elysia / createElysia → Elysia

DB 스키마 확인

确认DB schema

ls api/db/schema/

undefined

ls api/db/schema/

undefined

1.5. 레거시 코드 분석 (Analyze)

1.5. 遗留代码分析（Analyze）

오케스트레이터가 레거시 모듈의 현재 상태를 분석하고, 서브에이전트 프롬프트에 컨텍스트로 주입합니다.

bash

undefined

编排器分析遗留模块的当前状态，作为上下文注入到子Agent的提示词中。

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 → 确定需保留的逻辑和转换方式

**将分析结果传递给子Agent：**
- 创建每个Agent时，在提示词中包含「遗留分析结果：[差异列表]，保留逻辑：[列表]」

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

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:

"后端重构" (owner: refactor-backend)
"后端QA验证" (blockedBy: Task1, owner: backend-qa)
"前端重构" (blockedBy: Task1, owner: refactor-frontend)
"前端QA验证" (blockedBy: Task3, owner: frontend-qa)

layer=backend

TaskCreate:

"Backend 리팩토링" (owner: refactor-backend)
"Backend QA 검증" (blockedBy: Task1, owner: backend-qa)

TaskCreate:

"后端重构" (owner: refactor-backend)
"后端QA验证" (blockedBy: Task1, owner: backend-qa)

layer=frontend

TaskCreate:

"Frontend 리팩토링" (owner: refactor-frontend)
"Frontend QA 검증" (blockedBy: Task1, owner: frontend-qa)

undefined

TaskCreate:

"前端重构" (owner: refactor-frontend)
"前端QA验证" (blockedBy: Task1, owner: frontend-qa)

undefined

역할별 지시

各角色说明

각 역할의 전체 정의(페르소나, Bounded Autonomy, 워크플로우)는

references/

에 있습니다. 서브에이전트 생성 시 해당 파일의 전체 내용을 프롬프트에 포함합니다.

model=

옵션이 지정된 경우, 각 에이전트 호출 시 model 파라미터로 전달하여 frontmatter 기본값을 override합니다.

역할	참조 파일	핵심 스킬
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)

各角色的完整定义（角色设定、有限自主权、工作流）存放在

references/

目录下。创建子Agent时，需将对应文件的完整内容包含在提示词中。如果指定了

model=

选项，调用每个Agent时将该参数传入，覆盖frontmatter的默认值。

角色	参考文件	核心技能
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

```
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}\``）
保留原有功能，仅优化结构。
4步重构顺序：Type → DAO → Service/Controller → TDD
完成标准：
```
bun test
```
、
```
bun run lint:fixed
```
、
```
bun run build
```
全部通过
详情参考：
```
references/refactor-backend-agent.md
```

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

```
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。
3步重构顺序：Type & Store → Pages → Modals

完成标准：

bunx vue-tsc --noEmit

、

bun run lint:fix

、

bun run build

全部通过

详情参考：
```
references/refactor-frontend-agent.md
```

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冗余代码
详情参考：
```
references/frontend-qa-agent.md
```

Ralph Loop (반복 검증 메커니즘)

Ralph Loop（循环校验机制）

QA 실패 시 Ralph Loop(Vercel Labs) 패턴으로 구조화된 피드백을 주입한다.

QA失败时按照Ralph Loop（Vercel Labs）模式注入结构化反馈。

에스컬레이션 단계

升级流程

반복 횟수	단계	행동
1~3회	자율 수정	QA 피드백만으로 코드 수정
4~7회	가이드 재참조	test-data 기준골격 전체 재읽기 후 수정
8~10회	최소 수정	Must Follow 항목만 집중, 나머지 보류
11+	중단	사용자 에스컬레이션

循环次数	阶段	执行动作
1~3次	自主修正	仅通过QA反馈修改代码
4~7次	重阅规范	完整重读test-data基准规范后再修改
8~10次	最小修正	仅聚焦Must Follow项，其余问题暂存
11次及以上	中止	升级通知人工介入

적용 방식

执行方式

Backend QA 실패 → refactor-backend 수정 → backend-qa 재검증 (SendMessage)
Frontend QA 실패 → refactor-frontend 수정 → frontend-qa 재검증

后端QA失败 → refactor-backend修改 → backend-qa重新验证（SendMessage）
前端QA失败 → refactor-frontend修改 → frontend-qa重新验证

에스컬레이션 보고

升级报告

undefined

undefined

Ralph Loop 에스컬레이션

Ralph Loop 升级通知

모듈: [모듈명]
반복: N/10회
단계: [현재 단계]
미해결: [위반 항목]
권장: [수동 개입 사항]

undefined

模块：[模块名]
循环次数：N/10次
当前阶段：[当前阶段]
未解决问题：[违规项]
建议：[需人工介入的内容]

undefined

Completion

完成条件

기능 100% 보존과 QA 통과가 모두 확인되어야 완료입니다.

必须同时确认100%保留原有功能、所有QA验证通过才算完成。

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-qa：TDD X项通过
✅ refactor-frontend：前端重构完成
✅ frontend-qa：vue-tsc + lint + build通过
✅ qa-gate：生成凭证报告 + 判定可完成

重构后的文件：
后端：
├── api/src/modules/[模块名]/type/
├── api/src/modules/[模块名]/dao/
├── api/src/modules/[模块名]/service/
├── api/src/modules/[模块名]/controller/
└── api/src/modules/[模块名]/test/

前端：
├── front/src/modules/[模块名]/type/[模块名].type.ts
├── front/src/modules/[模块名]/store/[模块名].store.ts
├── front/src/modules/[模块名]/pages/
└── front/src/modules/[模块名]/modals/

变更摘要：
- [遗留模式 → 新模式列表]
- [已移除的AI冗余代码项]
- [结构优化说明]

Examples

示例

bash

undefined

bash

undefined

전체 리팩토링

全栈重构

/peach-agent-team-refactor notice-board layer=all

Backend만 리팩토링

仅重构后端

/peach-agent-team-refactor product-manage layer=backend tdd=Y

Frontend만 리팩토링

仅重构前端

/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

",

peach-agent-team-refactor

Original

Translation

Peach Agent Team Refactor

Peach Agent 团队重构

Overview

概述

Inputs

输入参数

옵션

选项

model=sonnet|opus|haiku (서브에이전트 모델 override, 기본값: sonnet)

model=sonnet|opus|haiku (覆盖子Agent使用的模型，默认值: 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

Preconditions

前置条件

Orchestration

编排流程

0. 입력 검증

0. 输入校验

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

检查Agent团队功能是否启用

1. 환경 확인

1. 环境检查

레거시 모듈 존재 확인

确认遗留模块存在

DAO 라이브러리 감지 (중요!)

检测DAO库（重要!）

from 'bunqldb' → 재할당 방식 (sql${query} AND ...)

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

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

from 'sql-template-strings' → append方式 (.append(SQLAND ...))

Controller 프레임워크 감지

检测Controller框架

routing-controllers → Koa / elysia / createElysia → Elysia

routing-controllers → Koa / elysia / createElysia → Elysia

DB 스키마 확인

确认DB schema

1.5. 레거시 코드 분석 (Analyze)

1.5. 遗留代码分析（Analyze）

레거시 코드 구조 파악

梳理遗留代码结构

주요 파일 읽기

读取核心文件

2. 팀 구성 다이어그램

2. 团队架构图

3. 팀 생성

3. 创建团队

layer=all

layer=all

layer=backend

layer=backend

layer=frontend

layer=frontend

역할별 지시

各角色说明

refactor-backend

refactor-backend

backend-qa

backend-qa

refactor-frontend

refactor-frontend

frontend-qa

frontend-qa

Ralph Loop (반복 검증 메커니즘)

Ralph Loop（循环校验机制）

에스컬레이션 단계

升级流程

적용 방식

执行方式

에스컬레이션 보고

升级报告

Ralph Loop 에스컬레이션

Ralph Loop 升级通知

Completion

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 ...`
))