source-command-refactor

name	source-command-refactor
description	audit·code-review 리포트에서 지정한 항목을 수정 반영. 테스트 먼저(TDD red) → 수정 → 병렬 자체 검증 + CTO 게이트로 자기완결. 빌드·커밋 안 함.

source-command-refactor

Use this skill when the user asks to run the migrated source command refactor.

Command Template

/audit·/code-review가 뱉은 발견 목록 중 사용자가 지정한 항목을 실제로 고치는 단계 전용 스킬. 리포트는 진단, /refactor는 그 처방의 실행이다. AGENTS.md 권장 흐름의 "픽스/리팩터" 칸을 채운다.

구조는 /implement와 동일한 자기완결 골격: 수정 본체는 메인 스레드 단일 실행이고, 병렬은 ① 수정 전 조사(Explore 병렬)와 ② 수정 후 자체 검증(전문 에이전트 병렬) 두 군데에만. 차이는 입력이 "신규 tasks/테스트"가 아니라 이미 진단된 기존 코드의 발견 항목이라는 점.

순서 원칙 — 테스트 먼저(TDD red → 수정 → green). 리포트 항목을 정리·분류한 뒤, 손대기 전에 /tdd의 regression 규율대로 고칠 발견을 재현하는 실패 테스트를 먼저 박는다. 픽스 전에 red를 확인해야 "진짜 그 버그를 잡았다"가 보장된다. 그다음 수정으로 green 전환한다(컴포넌트·DOM·OAuth 등 TDD 스킵 대상은 이유 남기고 사후 검증).

이 스킬의 핵심 가드: 무차별 수정 금지. 지정 항목이라도 회귀 위험·트레이드오프가 있으면 강행 전에 방향을 확인한다 (리포트의 발견은 "고칠 수 있다"이지 "고쳐야 안전하다"가 아니다).

사용

• /refactor <지정> — 직전 /audit·/code-review 리포트에서 고칠 항목을 번호·키워드·시급도로 지정.
  • 예: /refactor 1 3 5 · /refactor FIFO 통일이랑 settle 보강 · /refactor 🔴 전부 · /refactor 다 고쳐
• 리포트가 직전 컨텍스트에 있어야 번호 참조가 유효하다. 없으면 발견 목록을 사용자에게 요청하거나 /audit·/code-review를 먼저 권한다(자동 실행하지 않음).

다른 스킬과의 분리

• /audit·/code-review — 리포트 전용. 진단만, fix 안 함.
• /implement — 신규 구현(tasks/테스트 기반). 없던 코드를 만든다.
• /simplify — 변경분(git diff) 재검토 후 fix. 스코프가 리포트가 아니라 diff.
• /refactor ← 여기. 리포트 지정 항목 수정. 진단을 처방으로 옮긴다. 빌드·커밋 안 함.
• /push — 푸시 + 문서 신선도.

절차

1. 대상 확정 + 사전 분류

• 사용자 지정(번호/키워드/시급도/"전부")을 직전 리포트에 매핑해 수정 대상을 추린다. 매핑이 모호하면 확인한다.

• 지정 안 된 항목은 건드리지 않는다 (외과적).

• 추린 항목을 세 부류로 분류한다 — 이 분류가 이 스킬의 본질이다:

  부류	판단 기준	처리
  안전 수정	동작 불변·국소·근거 명확 (상수 추출, 의존성 정리, 데드 코드 제거 등)	바로 고침
  회귀 위험 / 트레이드오프	정상 동작에 영향·정책 결정 필요 (FIFO 정책, 타임아웃 상향, race 보강 등)	강행 전 AskUserQuestion으로 방향 확인
  수정 부적절	의도된 설계·견고한 수정 불가·/AGENTS.md 원칙 위반(요청 안 한 추상화 등)	이유 달아 보고하고 스킵 제안

• 사용자가 "전부"로 지정했어도 위 분류는 적용한다 — 회귀 위험 항목까지 묻지도 않고 일괄 수정하지 않는다.

• 멀티 항목이면 TaskCreate로 추적. 단계마다 완료 즉시 마킹.

2. 수정 전 조사 (Explore 병렬)

손대기 전, 각 항목의 영향 영역 기존 패턴·참조 파일·제약을 병렬로 수집한다. read-only라 충돌이 없다.

• 변경 대상과 같은 역할의 기존 구현 (패턴 복제용)
• 건드릴 타입·메시지·store 키의 현재 정의·사용처
• 관련 AGENTS.md / docs/ARCHITECTURE.md 제약 (해당 영역만)

대상이 한 파일·한 영역에 집중되면 Explore 없이 직접 Read.

착수 전 회고 조회 (메인, 값싸다). Explore와 병행해, 수정 대상 파일·영역 키워드로 docs/POSTMORTEM.md를 grep한다 — 이 파일은 같은 자리에서 반복해 터진 버그의 재발 방지 신호(grep 패턴·file:func)를 담는다. 매칭 항목의 증상·근본 원인·재발 방지를 읽고, 이번 수정이 그 함정을 다시 밟지 않는지(그리고 3단계 회귀 테스트가 그 재발까지 덮는지) 확인한다. 매칭 0이면 한 줄로 넘어간다.

grep -ni -e '<수정 파일명>' -e '<영역 키워드>' docs/POSTMORTEM.md

예: StyleCssView·CSS 뷰 수정이면 -e StyleCssView -e 'CSS 뷰' -e cross-origin. (영역 키워드는 회고 제목의 반복어 — cross-origin·picker·slack·i18n·마이그레이션·user gesture·capture 등.)

3. 회귀 테스트 먼저 (TDD red)

수정에 손대기 전, /tdd의 regression 규율대로 고칠 발견을 재현하는 실패 테스트를 먼저 박는다. 이 단계가 이 스킬의 "테스트 우선" 게이트다.

• 1단계에서 추린 안전 수정·(방향 확정된) 회귀 위험 항목마다 /tdd의 강제/스킵 분류표로 테스트 대상 여부를 판정한다:
  • TDD 강제 → 실패 테스트 먼저: 순수 함수 헬퍼(src/lib/*·src/sidepanel/lib/build*·parse/format/extract), 마이그레이션, 초기값·reconcile, 정규식·매핑 테이블, 부수효과 없는 mapper, 재현되는 버그.
  • TDD 스킵 OK → 이유 한 줄 남기고 사후 검증: React 컴포넌트 동작·레이아웃·인터랙션, content script DOM 측정(picker·overlay·MutationObserver), MV3 메시지 라우터 자체, OAuth 플로우, 외부 API 직접 호출, SW lifecycle.
• 테스트는 픽스 후 기대값을 박는다("이 입력 → 이 결과"). 기존 __tests__/*.test.ts에 케이스 추가가 자연스러우면 신규 파일 금지.
• 리포트가 버그를 전제로 한 기존 테스트의 잘못된 기대값을 결함으로 지목했으면, 그 한 케이스만 고치고 이유를 보고한다(그 외 기존 테스트 임의 수정 금지).
• pnpm test --run <파일>로 red 확인. 예상과 달리 green이면 테스트가 버그를 재현 못 하는 것 — 입력·기대값 재검토.
• 지정 항목이 전부 스킵 분류(컴포넌트·DOM·OAuth)면 "테스트 대상 없음 — 이유" 한 줄로 통과하고 4단계로 간다.

4. 수정 (메인 스레드 단일)

• 3단계에서 박은 red 테스트를 green으로 전환하는 방향으로 수정한다.
• 메인 스레드에서 순차 수정. 서브에이전트에게 쓰기 위임 금지.
• 외과적: 지정 항목 범위만. 범위 밖 인접 리팩터 금지. 기존 dead code는 건드리지 않는다(내 변경이 만든 고아만 제거).
• 회귀 위험 항목은 1단계에서 확인받은 방향대로만 수정한다.
• 기존 패턴 복제 — size·variant·className·구조·에러 처리를 같은 역할 코드와 일치.
• 경로 @/ → src/. 주석 최소화(WHY 비자명할 때 한 줄). UI는 shadcn/ui 우선.
• bugshot 동시 갱신 지점을 한 번에: 새 메시지 타입 → BgRequest union + handler + BG_REQUEST_TYPES 3곳 / 노출 텍스트 → i18n ko·en / 새 store 키 → session-keys + 마이그레이션 / 어댑터 변경 → 플랫폼 대칭.

5. 테스트 green 확인

• 3단계에서 박은 red 테스트가 이제 green으로 전환됐는지 pnpm test --run <파일>로 확인.
• 수정하며 새로 순수 함수를 만들었으면 그 테스트도 추가(위치: 대상과 같은 디렉터리 __tests__/*.test.ts, 도구 Vitest). 동작 불변 리팩터(상수 추출 등)면 기존 테스트 통과로 갈음.
• 마지막에 pnpm test --run 전체 + pnpm typecheck 통과 확인.
• pnpm build는 돌리지 않는다.

6. 자체 검증 (전문 에이전트 병렬)

수정이 끝나면 이번 변경분(git diff, 미커밋)을 전문 에이전트 병렬로 검증한다. 변경 영역에 해당하는 에이전트만 활성화.

키워드	관점	핵심
ui	UI/UX·i18n	shadcn/ui, 버튼 사이즈, IconButton(h-8/h-9), Tailwind 변수, data-[state=inactive]:hidden, ko/en 대칭
security	인증·MV3	OAuth proxy, 토큰 갱신, user gesture, MAIN world self-contained, env 가드
dataflow	세션·picker·이슈	editor:${tabId} 키, phase별 보존, 섹션 구성, 토큰 resolve, 마이그레이션 멱등성, union 3곳 일치
codehealth	스타일·품질	@/ 경로, 주석 최소화, 데드 코드, 불필요한 추상화·shim, race condition

각 에이전트(subagent_type: general-purpose)에게 전달:

• 이번 git diff 중 자기 영역 변경 파일
• 수정 의도: 원 리포트의 해당 발견 항목 (= 무엇을 왜 고쳤나, 통과 기준)
• 패턴 비교용 참조 파일 (2단계 조사 산출)
• 체크 가이드(위 표) + 공통 원칙(더 단순한 방법·외과적·패턴 일관성)

에이전트는 파일:줄 — 요약 (근거) + 시급도(🔴/🟡/⚪)로 보고. 변경이 한 영역에 집중되면 단일 에이전트로 충분.

7. 자체 발견 수정 루프

• 🔴 심각·🟡 권장 — 즉시 수정. ⚪ 사소 — 보고만.
• 새로 나온 항목도 TDD 강제 대상(순수 함수·재현 버그)이면 red 테스트를 먼저 박고 고친다(3단계 규율 재적용). 스킵 대상은 이유 남기고 사후 검증.
• 단, 자체 검증에서 새로 나온 항목이 또 회귀 위험이면 강행하지 말고 1단계 가드대로 확인한다.
• 수정 후 5단계 테스트·typecheck 재실행. 새 🔴/🟡가 또 나오면 한 번 더 루프 (최대 2회 — 이후 남은 건 보고하고 종료).

8. CTO 최종 게이트 (통합 리뷰 + 수정)

영역별 4관점이 놓치는 크로스-커팅 이슈를 단일 CTO 에이전트가 총괄 점검한다.

CTO 에이전트(subagent_type: general-purpose, "CTO" 페르소나)에게 전달:

• 6·7단계를 거친 현재 git diff 전체
• 원 리포트의 지정 항목 (해소돼야 할 발견)
• 4관점에서 나온 발견·수정 요약 (중복 점검 방지)

CTO가 보는 것 (영역별 세부는 반복 안 함):

• 원 발견 해소 확인: 지정 항목이 실제로 고쳐졌나, 표면만 덮고 근본을 놓치지 않았나.
• 새 회귀: 수정이 기존 플로우·user gesture 체인·마이그레이션 멱등성을 깼나.
• 대칭 짝 누락: 한쪽만 고치고 어댑터·union·i18n 짝을 빠뜨렸나.
• 오버엔지니어링: 발견 수정을 빌미로 요청 안 한 추상화·shim이 끼었나.

CTO는 파일:줄 — 요약 (근거) + 시급도로 보고만. 메인 스레드가 🔴/🟡 수정, ⚪는 보고에 남기고, 5단계 테스트·typecheck 재확인. 변경이 작으면 "이슈 없음" 한 줄로 통과 무방.

9. 보고 + 종료

대상 리포트: <audit / code-review · 지정: 항목들>

수정 항목: 고침 N · 확인 후 처리 M · 스킵 K
- 고침: <항목 — 변경 파일:줄 한 줄>
- 확인 후 처리: <항목 — 사용자가 정한 방향 / 보류>
- 스킵(부적절): <항목 — 이유>

회귀 테스트(TDD): red→green N개 · TDD 스킵 K개(이유)
- <항목 — 테스트 파일:케이스 / 또는 스킵 이유>

변경 파일:
- <경로> — <한 줄 요약>

자체 검증(4관점): <활성 에이전트> / 발견 🔴 X · 🟡 Y · ⚪ Z
- 수정함: <🔴/🟡 한 줄씩>
- 미수정(⚪): <한 줄씩>

CTO 최종 게이트: 이슈 없음 / 발견 🔴 X · 🟡 Y · ⚪ Z
- 수정함: <한 줄씩>

테스트: pnpm test 전체 green (N tests) / typecheck 통과
원 발견 해소: <지정 항목별 해소됨 / 보류 — 이유>

• 보고 후 종료. 빌드·커밋·푸시 안 함.
• /code-review·/tdd regression·/push 등 후속 스킬을 자동 제안·실행하지 않는다.

금지 사항

• 서브에이전트로 쓰기 위임 금지 — 수정 본체는 메인 스레드만. 병렬은 조사(Explore)·검증(general-purpose)에만.
• 회귀 위험 항목 무단 강행 금지 — "전부"로 지정받았어도 트레이드오프 항목은 방향 확인 후 수정.
• 지정 안 한 항목·범위 밖 리팩터 금지 — 리포트에 있어도 사용자가 안 고른 건 손대지 않는다.
• 빌드·커밋·푸시 금지 — pnpm build 안 돌리고, staging·commit 안 한다.
• ⚪ 임의 수정 금지 — 자체 검증에서 나온 ⚪는 보고만 (단, 사용자가 ⚪ 발견을 명시 지정했으면 고침).
• red 없이 수정 금지 — TDD 강제 대상(순수 함수·재현 버그)은 수정 전 실패 테스트(red)를 먼저 박는다. 스킵 대상만 이유 남기고 사후 검증.
• 테스트 없이 종료 금지 — 순수 함수 변경 시 관련 테스트 통과 확인이 완료 조건.
• 무한 검증 루프 금지 — 수정 루프 최대 2회.
• 후속 스킬 자동 제안 금지.