refactor
코드베이스 전체를 인지하고 LSP와 AST-grep으로 수행하는 코드맵 기반 지능형 리팩터입니다.
refactor 스킬은 LazyCodex(LZX)가 무작정 찾아 바꾸기 대신 지능적이고 결정론적인 리팩터를 수행하는 방식입니다. 무언가를 건드리기 전에 코드베이스를 매핑하고, 테스트 커버리지를 평가해 검증 전략을 정하고, 꼼꼼히 계획한 뒤 LSP와 AST-grep으로 단계별로 실행합니다. 변경마다 테스트를 돌려 리팩터가 회귀를 만들지 않게 합니다. LazyCodex가 Codex에 설치하는 OmO(oh-my-openagent) 플러그인에 포함되어 있습니다.
"refactor", "refactoring", "cleanup", "restructure", "extract", "simplify", "modernize"가 트리거입니다.
사용법
/refactor <refactoring-target> [--scope=<file|module|project>] [--strategy=<safe|aggressive>]- refactoring-target — 파일 경로, 심볼 이름, 패턴, 또는 "검증 로직을 별도 모듈로 추출" 같은 설명입니다.
--scope—file,module(기본값),project중 하나입니다.--strategy—safe(기본값, 최대 테스트 커버리지 요구) 또는aggressive(적정 커버리지 하의 더 넓은 변경)입니다.
페이즈
Phase 0 — 의도 게이트
어떤 행동 전에도 요청을 분류합니다. 구체적인 파일·심볼이나 "X를 Y로 리팩터"는 바로 분석으로 넘어갑니다. 막연한 "개선해 줘" / "정리해 줘", 모호한 범위, 부족한 맥락은 무엇이든 움직이기 전에 명확화 질문을 트리거해야 합니다.
Phase 1 — 코드베이스 분석
병렬 explore 에이전트를 띄워 대상, 의존하는 코드, 비슷한 패턴, 관련 테스트, 아키텍처 맥락을 찾습니다. 그동안 직접 도구를 씁니다: 정의·참조·심볼에는 LSP, 구조적 패턴 분석에는 AST-grep을 씁니다.
Phase 2 — 코드맵 구축
분석 결과로 확정적인 코드맵을 만듭니다: 핵심 파일, 의존성 그래프(imports / imported-by / used-by), 위험도와 커버리지로 등급 매긴 영향 영역, 리팩터가 따라야 할 기존 패턴. 여기서 따라야 할 기존 패턴, 깨면 안 되는 것, 안전하게 바꿀 수 있는 것, 마이그레이션이 필요한 것을 표시합니다.
Phase 3 — 테스트 평가
테스트 인프라를 감지하고 커버리지를 분석합니다. 커버리지가 검증 전략을 정합니다: 높음(>80%)은 단계마다 기존 테스트를 돌리고, 중간(50~80%)은 안전 어서션을 더하고, 낮음(<50%)은 멈춰서 테스트 먼저 추가를 제안하고, 없음은 aggressive 리팩터를 즉시 막습니다.
Phase 4 — 계획 생성
코드맵, 커버리지, 제약과 함께 Plan 에이전트를 불러 원자적이고 독립 검증 가능한 단계를 의존성 순으로 만듭니다. 각 단계에는 정확한 파일과 라인 범위, 롤백 전략이 들어갑니다. 계획을 세밀한 투두로 변환합니다.
Phase 5 — 실행
각 단계를 엄격한 프로토콜로 실행합니다: 현재 상태 읽기, 기준 진단 확인, 실행, 그다음 검증(진단 깨끗, 테스트 통과, 타입 체크 깨끗). 어떤 실패든 즉시 멈추고 되돌립니다. 테스트가 깨진 채 다음 단계로 가지 않습니다.
Phase 6 — 최종 검증
전체 테스트 스위트, 타입 체크, 린트, 빌드(해당 시), 변경된 모든 파일의 최종 진단을 돌리고, 무엇이 바뀌었는지와 검증 결과를 요약합니다.
구조적 검색·재작성 — AST-grep이 사는 곳
리팩터가 바로 AST-grep이 실제로 동작하는 곳입니다. ast_grep_search는 텍스트가 아니라 모양으로 코드를 찾고, ast_grep_replace는 매칭된 패턴을 재작성합니다. 핵심 규칙: ast_grep_replace는 항상 dryRun=true로 먼저 돌려 미리보기를 검토한 뒤 dryRun=false로 실행합니다.
LSP와 AST-grep은 서로 보완합니다. LSP는 실제 심볼에 대한 의미적 질문에 답합니다. 안전한 워크스페이스 전역 이름 변경에는 lsp_prepare_rename 다음 lsp_rename을, 편집마다 lsp_diagnostics를 씁니다. AST-grep은 단일 심볼 이름 변경이 아닌 변형을 위해 구문 트리 수준의 패턴 매칭과 편집을 수행합니다.
핵심 규칙
- 변경 후 진단 확인을 건너뛰지 않고, 테스트가 실패한 채로 진행하지 않습니다.
as any,@ts-ignore,@ts-expect-error를 쓰지 않고, 통과시키려고 테스트를 지우지 않습니다.- 기존 패턴을 이해한 뒤에만 리팩터하고, 적용 전에 미리봅니다.
- 폐기된 API는
librarian에게 현대적 대체를 묻되, 사용자가 마이그레이션을 명시적으로 요청하지 않는 한 라이브러리 버전을 자동으로 올리지 않습니다. - 복잡한 아키텍처 판단은 읽기 전용 reviewer 역할에 맡깁니다.
- 커버리지 0, 공개 API 깨짐, 불분명한 범위, 연속 세 번의 검증 실패에서는 중단하고 사용자에게 묻습니다.