---
name: refactor-plan
description: 동작을 보존하는 코드 정리·의존성 갱신·스택 전환의 범위와 검증을 계획한다. 영향 문서와 필요한 작업만 보완하고 실행 요청이면 구현·검증까지 이어 수행한다.
---

# 리팩토링 계획과 실행 연결

## 목적과 입력

보존할 동작과 바꿀 구조를 명확히 하여 코드 정리·라이브러리 갱신·스택 전환을 수행한다.
요청, 관련 코드·설정·테스트, 기존 요구·설계·계획과 운영 합의를 읽는다.
문서나 하네스가 없다고 전체 문서화부터 강제하지 않는다.

## 최소 산출물

변경 대상·이유·목표 구조·보존 동작·검증 방법을 짧은 목록이나 기존 작업 기록에 남긴다.
결정/구조가 바뀌거나 인계가 필요한 문서에 `## 리팩토링 N: <이름>` 절을 붙인다.
N은 기존 리팩토링 번호의 최댓값 다음이며 같은 요청의 영향 문서에는 같은 번호를 쓴다.
계획 관리가 필요하면 끝번호 `plan_setup/phase-NN/phase-NN-refactor-<이름>.md`와 필요한 태스크를 더한다.
작은 정리는 기존 작업/LOG의 짧은 계획으로 충분하며 후미 절·새 phase·전체 레이어를 의무로 만들지 않는다.

## 진행

1. 요청에서 범위와 계획만/실행 포함 여부를 읽고 관련 코드와 문서의 차이를 조사한다.
   기존 합의를 재사용하고 사용자만 정할 동작 변경·권한·예산의 미결만 실행 전에 해소한다.
2. 보존할 동작과 관찰 가능한 구조 조건을 정한다. 예: 중복 정의 위치·의존 방향·공개 API 호환.
   함께 바꿔야 검증되는 여러 파일을 한 작업으로 묶고 실제 선행 관계만 둔다.
3. 관련 기존 검사를 실행해 기준을 남긴다. 미커밋 상태도 파일/차이와 실행 결과로 기준을 보존할 수 있다.
   검사 공백은 위험에 필요한 테스트나 HTTP·CLI·브라우저 관찰로 먼저 보완한다.
   작은 독립 리팩토링에는 전체 현행 고정 phase나 네 게이트 활성을 요구하지 않는다. 기존 Loop 제품 변경은 아래 계약을 따른다.
4. 중요한 기술 결정이 바뀌면 `docs/TRD.md`, 경계·계약·의존이 바뀌면 `docs/ARCHITECTURE/`만 갱신한다.
   요구가 그대로면 PRD에 새 FR을 만들지 않는다. 무관한 문서를 열거나 모든 스킬을 호출하지 않는다.
5. 계획 관리 시 구조 조건과 행위 보존 기준·의존·검증을 연결한다.
   새 태스크 필수 키는 `id`, `status`, `depends_on`, `acceptance_criteria`, `verification`이다.
   기존 확장 필드와 상태를 읽고 유지하며 `PLAN.md`·`STATE.md`·`LOG.md`의 관련 부분만 맞춘다.
6. 검사 명령·환경이 바뀔 때만 harness를, 운영/충돌 조정이 바뀔 때만 loop를 보완한다.
   필요한 다른 스킬은 읽거나 호출해 이어 수행한다. 요청 범위를 넘어 다음 단계로 넘어갈 때는 명시 승인 범위가 아니면 제안해 승인을 받는다.
7. 계획만 요청하면 실행 전제·위험·검증 가능한 계획으로 끝낸다.
   실행 요청이면 구현과 영향 검증까지 이어 수행하고 상태·증거를 갱신한다. 사용자에게 루프 실행을 넘기고 끝내지 않는다.

## 필수 제약

- 기존 FR/NFR/US/TD/OQ/CF·phase·태스크 ID와 `파일명 §절번호`, 완료 이력·사용자 편집을 보존한다.
  새 번호는 끝에 붙이고 결정/절 교체는 기존 후미 절과 연결하며 원래 요구·TD 위치에 현재 기준 포인터를 둔다. 사용자 편집·메모·후미 절·완료 작업을 보존한다.
- 함께 요청된 버그/기능은 각 수용 기준과 회귀 증거를 구분해 필요한 절차를 함께 수행한다.
  동작 변경을 행위 보존으로 위장하거나 다른 스킬 안내만 하고 요청을 버리지 않는다.
- 스택 전환은 기존 검사 실행 가능성을 확인하고 못 쓰는 검사는 동등한 행동 관찰과 새 검사로 대체한다.
  케이스 수만으로 동등성을 입증하지 않고 주요 성공·실패 경로를 비교한다. 기준을 몰래 낮추지 않는다.
- `in_progress`나 미커밋만으로 사람 대기를 만들지 않는다. 실제 실행 주체·수정 소유권·충돌을 조사한다.
  공유 상태는 기존 필자가 안전한 경계에서 반영하게 조율하고 독립 준비를 진행한다.
  사용자 변경과 살아 있는 프로세스를 보존하며 겹치는 변경만 직렬화한다.
- Loop 이후 합의 안에서 질문·재승인·수동 조치 요청 없이 구현·환경 조정·복구한다.
  권한/예산으로 해소 불가하면 독립 작업 후 실패 증거·미완료 범위·재개 조건을 남긴다.
- 커밋·게시·새 외부 비용은 기존 권한을 따른다. 루트 지침 양쪽의 전체 동기화를 요구하지 않는다.

- 시작·중요한 범위/결정·검증·분석 전환에서 해당 문서 또는 기존 STATE/LOG를 증분 저장한다.
  현재 단계·확정/미결·누적 시도/전략·사용/잔여 예산·다음 행동과 대상 코드/지속 증거를 연결한다.
  새 세션은 이 기록과 실제 코드·미커밋·살아 있는 실행/미반영 결과를 대조해 이어가며 완료·실패 이력을 초기화하지 않는다.
  작은 문서/계획 요청은 해당 문서의 짧은 재개 기록으로 충분하며 전체 계획 체계를 만들지 않는다.

시각을 보존하는 리팩토링은 새 디자인 승인을 요구하지 않는다. 새 방향·승인 범위 밖 시각 변경에만 PRD의 미리보기·사용자 확정을 본격적인 화면 구현·관련 Loop 전에 연결한다.

## 기존 Loop의 제품 변경

현재 요청·유효한 합의·태스크 연결상 기존 Loop의 재개·추가·검증·복구에 속하는 제품 변경은 계약을 계승한다.
LOOP.md의 존재나 과거 완료 이력만으로 새 독립 요청을 편입하지 않는다. 적용 범위와 근거를 기록하고 Loop 작업을 작게 나눠 면제하지 않는다.
`loop_setup/LOOP.md`·STATE와 HARNESS를 읽고 `lint → unit → e2e → task_validation` 판정 순서를 계승한다.
task_validation은 해당 변경 미구현·구현 대화/추론/자체 통과 결론을 비상속한 별도 세션이 맡는다. 앞 실패 뒤 후행 완료 판정을 하지 않는다.
환경 선택(Orca/일반/Others)·충돌/자원 조건·누적 시도와 전체 예산을 보존한다. 같은 방식의 수정은 3회 이내 심층 분석·새 전략으로 전환하며 이력/예산을 초기화하지 않는다.
상세 검증·복구·배정은 `harness-setup`·`harness-update`·`loop-setup`·`loop-update`의 필요한 절차로 이어 수행한다.
새 사용자 지시·계획만·자식 실행 금지가 우선하며 변경된 보장과 미검증을 기록한다. 금지된 실행을 강행하거나 독립 검증 PASS를 꾸미지 않는다.

## 완료 증거

계획 요청은 목표 구조·행위 보존 기준·작업/의존·실행 가능한 검증 수단이 연결되면 완료다.
실행 요청은 구조 조건과 관련 동작/회귀 결과로 판정한다. 명령·관찰 결과·미검증·잔여 위험을 보고한다.

## 환경 참고

- [Claude Code](references/claude-code.md)
- [Codex](references/codex.md)