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

peach-team-refactor

Coding & development

View repository

Updated 10-15 21:41

About this skill

Peach Agent Team Refactor

Overview

Refactoring existing PeachSolution legacy modules into the test-data pattern is the dedicated team skill for refactoring.

Existing team-refactoris replaced, and the backend/frontend role definitions and QA procedures are included 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, the DB schema must exist.
  • Perform only structural cleanup, not feature changes.

Orchestration

0. Input validation

Verify that the agent team feature is enabled

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

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

If there is no setting or "1"is not 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 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 sonnet
  • If 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 with test-data, naming inconsistencies
  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-specific 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 the criteria.
  • 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

QA verdict handling (3 steps)

QA agents (backend-qa, frontend-qa) APPROVED / CONDITIONAL / REJECTED make a verdict in 3 steps. The orchestrator performs the Architect role and handles the verdict.

✅ APPROVED

QA → SendMessage → 오케스트레이터: "APPROVED" + 검증 결과
오케스트레이터 → /peach-qa-gate 자동 실행
→ 완료

⚠️ CONDITIONAL

QA → SendMessage → 오케스트레이터: "CONDITIONAL" + 조건 내용 + 왜 REJECTED가 아닌지 근거
오케스트레이터 판단:
    "조건 수용" → dev 에이전트에 수정 지시 → QA 재검증
    "조건 무시" → 판단 근거 기록 후 APPROVED로 처리

Rules:

  • CONDITIONAL is not a Ralph Loop. Do not treat as complete until the orchestrator decides.
  • QA는 At least 1 condition item + rationale for why it is not REJECTEDmust be reported together.
  • If the orchestrator chooses "ignore", include the rationale in the final completion report.

❌ REJECTED → Ralph Loop activates

REJECTED 시 Ralph LoopInject structured feedback using the (Vercel Labs) pattern.

Escalation steps

Iteration count Step Action
1~3회 Autonomous fix Fix code based only on QA feedback
4회 Re-reference guide Re-read the entire test-data baseline skeleton, then fix
5~7회 Codex diagnosis codex:codex-rescueIndependently diagnose the failure cause with and re-reference the guide
8~10회 Minimal fix Focus only on Must Follow items, defer the rest
11+ Stop User escalation

Codex deployment conditions (5–7 times)

  • CODEX_AVAILABLE=true Deploy only when (detected in settings.json as "codex@openai-codex": true detection)
  • CODEX_AVAILABLE=false: Continue the existing Ralph Loop without Codex (refer back to the guide)
  • Codex no response/timeout: wait 60 seconds → if no response, skip and proceed with existing feedback
  • Codex diagnosis results insufficient: orchestrator ignores and proceeds with existing feedback

Application method

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

Escalation report

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

Completion

Completion requires both 100% feature preservation and QA APPROVED to be confirmed.

1. Evidence collection

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

  • If the verdict is ❌, fix the relevant 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