SuperAPI AI Directory
Partner中文AI newsFavorites
Skillspeach-agent-team-refactor

peach-agent-team-refactor

Coding & development

View repository

Updated 10-15 21:37

About this skill

Peach Agent Team Refactor

Overview

Converting the PeachSolution legacy module to the test-data pattern, this is a dedicated refactoring team skill.

Existing team-refactorand includes the backend/frontend role definitions and QA procedures in this document.

Inputs

/peach-agent-team-refactor [모듈명] layer=backend|frontend|all [옵션]

# 옵션
# model=sonnet|opus|haiku  (서브에이전트 모델 override, 기본값: sonnet)
# file=Y|N
# ui=crud|two-depth|select-list
# tdd=Y|N

Preconditions

  • The module to be refactored must exist.
  • When refactoring the backend, a DB schema must exist.
  • Perform only structural cleanup, not functional changes.

Orchestration

0. Input validation

Check that the agent team feature is enabled

Use the command below to ~/.claude/settings.jsoncheck whether the agent team flag is set:

cat ~/.claude/settings.json | grep -i "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"

If the setting is absent or "1"is not the case, stop immediatelyand output the following guidance:

⚠️  에이전트 팀 기능이 비활성화되어 있습니다.

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

Both layer and module name must be specified to proceed to the next step. If either is missing, must ask the developer.

When layer is unspecified:

layer를 선택해주세요:
1. backend — Backend만 리팩토링
2. frontend — Frontend만 리팩토링
3. all — 전체 리팩토링

When module name is unspecified:

모듈명을 입력해주세요 (예: notice-board, product-manage):

model option:

  • Unspecified: run all subagents with the default value sonnet
  • When specified: override all subagents to that model
  • Allowed values: sonnet, opus, haiku

1. Environment check

# 레거시 모듈 존재 확인
ls api/src/modules/[모듈명]/
ls front/src/modules/[모듈명]/

# DAO 라이브러리 감지 (중요!)
head -5 api/src/modules/test-data/dao/test-data.dao.ts
# from 'bunqldb' → 재할당 방식 (sql`${query} AND ...`)
# from 'sql-template-strings' → append 방식 (.append(SQL`AND ...`))

# Controller 프레임워크 감지
head -3 api/src/modules/test-data/controller/test-data.controller.ts
# routing-controllers → Koa / elysia / createElysia → Elysia

# DB 스키마 확인
ls api/db/schema/

1.5. Legacy code analysis (Analyze)

The orchestrator analyzes the current state of the legacy module and injects it as context into the subagent prompts.

# 레거시 코드 구조 파악
ls -la api/src/modules/[모듈명]/
ls -la front/src/modules/[모듈명]/

# 주요 파일 읽기
cat api/src/modules/[모듈명]/**/*.ts
cat front/src/modules/[모듈명]/**/*.{vue,ts}

Analysis items:

  1. Structural gap: file separation status compared to test-data, naming mismatches
  2. Logic gap: identify business logic not present in test-data
  3. Preservation list: list the logic that must be retained as functionality
  4. Adaptation decision: Must Follow → forced conversion / May Adapt → logic to preserve and conversion method

Pass the analysis results to the subagents:

  • When creating each agent, include "legacy analysis results: [gap list], preserved logic: [list]" in the prompt

2. Team composition diagram

layer=all

refactor-backend ──→ backend-qa        (병렬)
         │
         └──→ refactor-frontend ──→ frontend-qa

layer=backend

refactor-backend ──→ backend-qa

layer=frontend

refactor-frontend ──→ frontend-qa

3. Team creation

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

# 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)

# layer=backend
TaskCreate:
1. "Backend 리팩토링" (owner: refactor-backend)
2. "Backend QA 검증" (blockedBy: Task1, owner: backend-qa)

# layer=frontend
TaskCreate:
1. "Frontend 리팩토링" (owner: refactor-frontend)
2. "Frontend QA 검증" (blockedBy: Task1, owner: frontend-qa)

Role-by-role instructions

The full definition of each role (persona, Bounded Autonomy, workflow) is in references/. When creating subagents, include the full contents of that file in the prompt. model= If the option is specified, pass it as the model parameter when invoking each agent to override the frontmatter default.

Role Reference file Core skill
refactor-backend references/refactor-backend-agent.md peach-refactor-backend
backend-qa references/backend-qa-agent.md Verification only (read-only, worktree)
refactor-frontend references/refactor-frontend-agent.md peach-refactor-frontend
frontend-qa references/frontend-qa-agent.md Verification only (read-only, worktree)

refactor-backend

  • peach-refactor-backend Organize type/dao/service/controller/test based on this.
  • DAO library branching:
    • bunqldb When detected: reassignment method (sql\${query} AND field = ${val}``)
    • sql-template-strings On detection: append method (.append(SQL\AND field = ${val}``)
  • Maintain existing functionality and improve only the structure.
  • 4-step refactoring order: Type → DAO → Service/Controller → TDD
  • Completion criteria: bun test, bun run lint:fixed, bun run build
  • Details: references/refactor-backend-agent.md reference

backend-qa

  • After refactoring, verify structure, patterns, tests, and build.
  • test-data Verify pattern compliance.
  • QA checklist (7 items):
    1. type/, dao/, service/, controller/, test/ structure exists
    2. Comply with Service static method rules
    3. No FK constraints
    4. bun test passed
    5. bun run lint:fixed passed
    6. bun run build succeeded
    7. Confirm 100% functionality preservation
  • Details: references/backend-qa-agent.md reference

refactor-frontend

  • peach-refactor-frontend Organize type/store/pages/modals based on the criteria.
  • Enforce URL watch pattern, Composition API, and Pinia Option API.
  • 3-step refactoring order: Type & Store → Pages → Modals
  • Completion criteria: bunx vue-tsc --noEmit, bun run lint:fix, bun run build
  • Details: references/refactor-frontend-agent.md reference

frontend-qa

  • Verify file structure, watch pattern, UI pattern, and build results.
  • Check for violations of prohibited UI patterns and type rules.
  • QA checklist (8 items):
    1. File structure (pages/, modals/, store/, type/) exists
    2. Composition API (<script setup>) pattern compliance
    3. Comply with Pinia Option API Store pattern
    4. Whether URL watch pattern is applied
    5. listAction, resetAction, listMovePage function exists
    6. bunx vue-tsc --noEmit passed
    7. bun run lint:fix passed
    8. bun run build succeeded + AI Slop removal confirmed
  • Details: references/frontend-qa-agent.md reference

Ralph Loop (iterative verification mechanism)

On QA failure, Ralph LoopInject structured feedback using the (Vercel Labs) pattern.

Escalation stages

Iteration count Stage Action
1~3회 Autonomous fix Fix code using only QA feedback
4~7회 Re-reference guide Re-read the entire test-data baseline skeleton, then fix
8~10회 Minimal fix Focus only on Must Follow items, defer the rest
11+ Stop User escalation

Application method

  • Backend QA failure → refactor-backend fix → backend-qa re-verification (SendMessage)
  • Frontend QA failure → refactor-frontend fix → frontend-qa re-verification

Escalation report

## Ralph Loop 에스컬레이션
- 모듈: [모듈명]
- 반복: N/10회
- 단계: [현재 단계]
- 미해결: [위반 항목]
- 권장: [수동 개입 사항]

Completion

Completion requires both 100% functionality preservation and QA pass to be confirmed.

1. Evidence collection

The orchestrator automatically runs /peach-qa-gate→ generate evidence report

  • If the verdict is ❌, fix the item and re-run
  • If the verdict is ✅, proceed to the next step

2. Team cleanup

SendMessage(shutdown_request) → 모든 팀원에게
TeamDelete → 팀 정리

Completion report format

✅ 리팩토링 팀 작업 완료

모듈: [모듈명]
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 항목]
- [개선된 구조 설명]

Examples

# 전체 리팩토링
/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 모델로 전체 리팩토링
/peach-agent-team-refactor notice-board layer=all model=opus