request-refactor-plan

request-refactor-plan 스킬 개요

request-refactor-plan이 실제로 하는 일

request-refactor-plan 스킬은 막연한 리팩터링 아이디어를 검토 가능하고 범위가 명확하며 점진적으로 실행할 수 있는 계획으로 바꿔, GitHub issue로 바로 등록할 수 있게 도와줍니다. 곧바로 코드 수정에 들어가는 대신, 에이전트가 사용자 인터뷰, 저장소 점검, 대안 비교, 범위 정의, 테스트 관련 질문, 커밋 단위 롤아웃 계획까지 차례대로 진행하도록 안내합니다.

이 스킬이 특히 잘 맞는 경우

request-refactor-plan은 코드베이스의 특정 부분을 재구성해야 한다는 점은 이미 알고 있지만, 아직 안전하게 실행할 계획은 없는 개발자와 팀에 가장 잘 맞습니다. 특히 다음과 같은 상황에서 유용합니다.

• 구현에 들어가기 전에 리팩터링을 먼저 설계하고 싶을 때
• 리팩터링 RFC나 issue를 작성해야 할 때
• 위험한 정리를 아주 작고 되돌릴 수 있는 커밋들로 쪼개고 싶을 때
• 작업 시작 전에 범위, 제약, 테스트 기준을 분명히 하고 싶을 때

이 스킬이 해결하는 진짜 문제

이 스킬의 핵심 가치는 단순히 “리팩터링 계획을 생성한다”가 아닙니다. 먼저 올바른 질문을 하게 만들고, 코드베이스를 직접 확인하게 하며, 실제로 안전하게 실행할 수 있을 만큼 작은 계획을 만들게 함으로써 리팩터링 리스크를 줄이는 데 있습니다. 범위가 불명확하거나, 숨은 의존성이 많거나, 변경이 과하게 커질 위험이 있을 때는 일반적인 프롬프트보다 이런 방식이 훨씬 잘 맞습니다.

request-refactor-plan이 다른 점

가장 큰 차별점은 워크플로 규율에 있습니다. 이 스킬은 순서를 분명히 둡니다.

1. 문제 설명을 구체적으로 받는다
2. 저장소에서 가정을 검증한다
3. 대안을 검토한다
4. 구현 세부사항을 인터뷰한다
5. 포함 범위와 제외 범위를 정한다
6. 테스트 커버리지와 테스트 계획을 점검한다
7. 작업을 아주 작은 커밋으로 나눈다
8. 결과를 GitHub issue로 정리한다

이 구조 덕분에 request-refactor-plan for Refactoring은 “계획 하나 써줘” 식의 일회성 요청보다 훨씬 실전적입니다.

설치 전에 알아둘 점

이 스킬은 가볍습니다. 저장소에서 확인되는 구성은 SKILL.md 하나뿐이고, 별도 스크립트, 템플릿, 헬퍼 파일은 보이지 않습니다. 도입 자체는 쉽지만, 결과물의 품질은 저장소 맥락과 인터뷰 과정에서 제공하는 답변의 질에 크게 좌우됩니다. 보조 자산까지 포함된 고자동화 플래너를 기대한다면 이 스킬은 맞지 않습니다. 반대로, 명확하고 재사용 가능한 계획 수립 워크플로를 원한다면 매우 잘 맞는 선택입니다.

request-refactor-plan 스킬 사용법

request-refactor-plan 설치

skills-enabled 환경에서 request-refactor-plan skill은 다음 명령으로 설치할 수 있습니다.

npx skills add mattpocock/skills --skill request-refactor-plan

이미 소스가 로컬 환경에 있다면 먼저 request-refactor-plan/SKILL.md를 읽어보세요. 이 경우 해당 파일이 사실상 전체 구현 표면이므로, 추가 지원 폴더를 뒤질 필요는 없습니다.

가장 먼저 읽어야 할 파일

시작은 여기서 하면 됩니다.

• SKILL.md

이 스킬에는 README.md, metadata.json, rules/, resources/ 같은 보조 파일이 노출되어 있지 않으므로, 도입 판단에 필요한 대부분의 정보는 이 단일 워크플로 문서에서 확인할 수 있습니다.

request-refactor-plan이 사용자에게 요구하는 입력

request-refactor-plan을 제대로 쓰려면 “X를 리팩터링해줘” 이상을 전달해야 합니다. 첫 메시지에 아래 정보가 들어가면 가장 잘 작동합니다.

• 영향을 받는 영역 또는 파일
• 현재 문제가 무엇인지에 대한 개발자 관점의 설명
• 왜 지금 이 작업이 필요한지
• 이미 알고 있는 제약사항
• 잠정적인 해결 아이디어
• 마감 일정이나 호환성 요구사항
• 지금 바로 구현할 예정인지, 나중에 할 예정인지

약한 입력 예시:

• “Help me refactor the auth module.”

강한 입력 예시:

• “I want a refactor plan for our auth module. src/auth mixes token parsing, session validation, and HTTP concerns. The current pain is duplicated logic across middleware and handlers, which is slowing feature work and creating inconsistent error handling. I think we may need to separate parsing from policy checks, but I’m not sure whether that should be done by extraction or by introducing a service layer. We cannot break existing API responses, and we need a plan that can be shipped in small commits.”

실무에서 request-refactor-plan 사용 흐름

실제 request-refactor-plan usage 흐름은 보통 다음과 같습니다.

1. 에이전트에게 리팩터링 요청서 또는 계획이 필요하다고 말한다.
2. 문제 상황과 대략적인 해결 아이디어를 구체적으로 설명한다.
3. 에이전트가 저장소를 살펴보고 당신의 가정을 검증하게 둔다.
4. 대안, 제약, 범위에 대한 후속 질문에 답한다.
5. 영향을 받는 코드의 테스트 기대치를 확정한다.
6. 최종 결과를 아주 작은 커밋 단계가 포함된 GitHub issue 초안으로 요청한다.

이 스킬은 “한 번 던지고 끝”나는 타입이 아닙니다. 의도적으로 인터뷰 중심으로 설계되어 있습니다.

거친 목표를 좋은 프롬프트로 바꾸는 법

프롬프트는 다음 구조로 잡으면 좋습니다.

• Problem: 지금 무엇이 문제인지
• Current area: 어떤 모듈, 서비스, 파일이 관련되는지
• Suspected causes: 결합도, 중복, 소유권 불명확, 불안정한 테스트, 네이밍 드리프트
• Constraints: 하위 호환성, 일정, 팀 규칙
• Non-goals: 무엇은 절대 바꾸면 안 되는지
• Testing state: 현재 테스트, 빈틈, 불확실한 부분
• Desired output: GitHub issue, RFC, 또는 커밋 단위 계획

예시:

“Use request-refactor-plan to help me prepare a refactor issue. Problem: src/payments mixes provider adapters with domain rules, making it hard to add providers safely. Current area: src/payments/* and checkout integration tests. Constraints: no API contract changes, no schema changes this sprint. Non-goals: do not redesign billing. Testing state: good unit coverage on adapters, weak integration coverage. Desired output: a GitHub issue with tiny commits and clear scope boundaries.”

저장소 점검이 중요한 이유

이 스킬은 에이전트에게 저장소를 직접 탐색하고, 당신의 주장이나 가정을 검증하라고 명시합니다. 이게 중요한 이유는, 리팩터링 계획이 제안자의 머릿속 모델에만 의존할 때 실패하는 경우가 많기 때문입니다. request-refactor-plan을 제대로 활용한다는 것은 에이전트가 다음을 직접 확인하게 두는 뜻입니다.

• 현재 고통 지점이 국소적인지, 아니면 여러 영역에 걸친 문제인지
• 실제로 어떤 모듈들이 결합되어 있는지
• 테스트 커버리지가 존재하는지
• “당연해 보이는” 해결책이 더 넓은 변경 범위를 만들지는 않는지

저장소 점검을 막아버리면, 계획의 품질이 크게 떨어질 가능성이 높습니다.

대안과 범위를 다루는 방식

이 스킬의 좋은 점은, 당신이 처음 떠올린 해결책을 정답으로 전제하지 않는다는 것입니다. 에이전트가 다른 선택지가 있는지 묻고, 대안을 제안하더라도 마찰로 받아들이지 마세요. 그건 이 스킬의 장점입니다. 좋은 리팩터링 계획은 대개 작업을 더 좁히는 과정에서 나옵니다.

• 서브시스템을 통째로 다시 설계하는 대신 책임 하나만 분리하기
• 코드 이동 전에 테스트부터 보강하기
• 먼저 경계면(seam)을 분리한 뒤 동작을 리팩터링하기
• 현재 문제 해결에 꼭 필요하지 않은 아키텍처 변경은 뒤로 미루기

최종 결과물은 어떤 모습이어야 하나

request-refactor-plan guide는 기본적으로 GitHub issue 형태를 지향하며, 최소한 다음 섹션이 들어가는 것이 좋습니다.

• ## Problem Statement
• ## Solution
• 커밋별 구현 단계
• 테스트 기대사항
• 명확한 범위 경계

가장 가치 있는 결과물은 보통 요약 설명문이 아닙니다. 무서운 리팩터링을 실제 실행 가능한 작업으로 바꿔주는 것은 아주 작은 커밋 단위의 분해입니다.

일반 프롬프트 대신 request-refactor-plan을 써야 하는 경우

계획 수립의 엄밀함이 필요할 때 request-refactor-plan을 쓰는 것이 좋습니다. 일반 프롬프트도 그럴듯한 계획은 만들 수 있지만, 다음이 필요하다면 이 스킬이 더 강합니다.

• 실제 저장소를 기준으로 한 검증
• 명시적인 범위 조율
• 구현 전에 대안을 수면 위로 올리기
• 테스트 전략 논의
• 큰 폭의 재작성 대신 매우 작은 커밋 시퀀스

도입 시 가장 흔한 걸림돌

가장 큰 걸림돌은 문제를 너무 추상적으로 설명하는 것입니다. 팀이 개발자 관점의 고통, 제약, 비목표를 분명히 말하지 못하면, 이 스킬은 여전히 좋은 질문을 하겠지만 계획이 실행 가능할 정도로 구체화되지 않을 수 있습니다. 실제로는 “아키텍처를 좀 정리하자” 같은 넓은 요청보다, 하나의 실제 고통 지점과 하나의 구체적인 코드 영역을 가져오는 편이 훨씬 빨리 가치를 얻습니다.

request-refactor-plan 스킬 FAQ

request-refactor-plan은 대규모 리팩터링에만 맞나요?

아닙니다. 오히려 겉보기엔 간단해 보여서 방심하기 쉬운 중간 규모 리팩터링에서 더 빛나는 경우가 많습니다. 대형 리팩터링에도 도움이 되지만, 적당한 정리 작업이 통제 불가능한 재설계로 번지는 것을 막고 싶을 때 특히 강합니다.

초보자도 쓰기 쉬운가요?

네. 문제를 설명하고 코드베이스에 대한 질문에 답할 수 있다면 초보자에게도 충분히 유용합니다. 주니어가 특히 필요로 하는 구조를 이 스킬이 제공해주기 때문입니다. 다만 저장소 이해 자체를 대신해주지는 않으므로, 답변이 부실하면 계획 품질도 그만큼 제한됩니다.

그냥 리팩터링을 요청하는 것과 request-refactor-plan은 어떻게 다른가요?

직접 리팩터링을 요청하면 에이전트는 구현 쪽으로 바로 달려가기 쉽습니다. request-refactor-plan은 의도적으로 그 속도를 늦춥니다. 코드 변경 전에 문제 정의, 대안 검토, 범위 설정, 테스트, 점진적 전달 방식에 초점을 맞춥니다.

request-refactor-plan 스킬이 코드를 작성해주나요?

주된 목적은 구현이 아니라 계획 수립입니다. 이후 코딩 작업을 진행할 때 결과로 나온 issue나 커밋 계획을 가이드로 활용할 수는 있지만, 스킬 자체의 중심은 안전하고 구체적인 리팩터링 요청서를 만드는 데 있습니다.

어떤 경우에는 request-refactor-plan for Refactoring을 쓰지 않는 편이 좋나요?

다음 상황이라면 생략해도 됩니다.

• 변경이 아주 작고 자명할 때
• 이미 완전하고 검토까지 끝난 구현 계획이 있을 때
• 계획보다 즉각적인 코드 수정이 더 필요할 때
• 실제 작업이 리팩터링이 아니라 기능 설계나 아키텍처 제안일 때

이런 경우에는 더 직접적인 프롬프트가 빠를 수 있습니다.

GitHub가 꼭 필요한가요?

워크플로의 끝이 GitHub issue 생성이므로 GitHub와 가장 잘 맞습니다. 다른 트래커를 쓰더라도, 이 issue 템플릿 구조 자체는 다른 곳으로 옮겨 쓸 수 있는 유용한 계획 산출물입니다.

따로 익혀야 할 숨은 파일이나 자동화 도구가 있나요?

노출된 저장소 증거만 보면 그렇지 않습니다. 이 스킬은 단일 문서 기반 워크플로에 가까워 보입니다. 이해하기는 쉽지만, 추가 자동화, 스키마, 강제 규칙까지 기대하면 안 됩니다.

request-refactor-plan 스킬을 더 잘 활용하는 법

문제 설명을 더 날카롭게 쓰기

request-refactor-plan 결과를 가장 빠르게 개선하는 방법은 “코드가 지저분하다” 같은 막연한 품질 불만이 아니라, 개발자 워크플로 관점에서 고통을 설명하는 것입니다. 예를 들어 다음처럼 말할 수 있어야 합니다.

• 지금 어떤 변경이 어려운지
• 어떤 중복이나 결합이 그 원인인지
• 무엇이 신뢰를 떨어뜨리는지
• 현재 구조 때문에 어떤 비용이 생기는지

이렇게 해야 에이전트가 검증할 수 있는 구체적인 대상이 생깁니다.

비목표를 명확히 적기

리팩터링 계획이 불필요하게 커지는 가장 흔한 이유는 비목표가 빠져 있기 때문입니다. 무엇을 절대 바꾸지 말아야 하는지 에이전트에게 분명히 알려주세요.

• public APIs
• database schema
• user-facing behavior
• performance profile
• release timing

그래야 request-refactor-plan이 더 작고 현실적인 작업 순서를 만들 수 있습니다.

파일과 모듈 기준점을 제공하기

에이전트가 저장소를 직접 살펴본다고 해도, 유력한 핫스팟은 먼저 짚어주는 편이 좋습니다. 유용한 기준점은 다음과 같습니다.

• 디렉터리
• 서비스 이름
• 진입점
• 실패하는 테스트
• 중복 구현

이런 단서가 있으면 추측이 줄고, 저장소 검증 단계의 정확도가 올라갑니다.

테스트 커버리지 상태를 솔직하게 공유하기

이 스킬은 해당 코드 영역이 테스트되고 있는지 분명히 확인합니다. 커버리지가 약하다면 초반에 바로 말하는 것이 좋습니다. 좋은 결과물은 보통 아래 중 무엇이 먼저 필요한지 판단하는 데서 나옵니다.

• 현재 동작을 고정하는 characterization tests를 먼저 추가할지
• integration coverage를 확장할지
• 안전망이 생길 때까지 위험한 이동을 미룰지

테스트 공백을 숨기면 계획은 과신 쪽으로 기울기 쉽습니다.

단계만이 아니라 아주 작은 커밋을 요구하기

이 스킬 자체도 작은 단계로 나누도록 유도하지만, 결과를 더 좋게 만들려면 “페이즈”가 아니라 실제 커밋 크기의 세분화를 요구해야 합니다. 예를 들어 “extract service layer”는 여전히 너무 큽니다. 더 나은 커밋 단위 표현은 다음과 같습니다.

• 현재 동작에 대한 characterization tests 추가
• 동작 변경 없이 helper 추출
• 호출 지점 하나만 새 경로로 전환
• 테스트 통과 후 dead path 제거

리팩터링 리스크가 실제로 줄어드는 지점은 바로 이 수준입니다.

대안 비교를 강제하기

흔한 실패 패턴은 첫 번째 해결책에 너무 빨리 고정되는 것입니다. request-refactor-plan skill의 결과를 개선하려면, 최소 두 가지 접근법을 비교하고 왜 하나가 현재 저장소에서는 더 안전하고, 더 작고, 더 되돌리기 쉬운지 설명해달라고 명시적으로 요청하세요.

리뷰 후 첫 초안을 한 번 더 다듬기

첫 번째 계획이 나온 뒤에는 짧게라도 한 번 더 반복하는 것이 좋습니다. 피드백은 다음처럼 구체적일수록 좋습니다.

• 어떤 단계가 아직도 너무 크게 느껴지는지
• 어디서 범위가 모호한지
• 어떤 가정은 추가 검증이 필요한지
• 어떤 테스트 단계 설명이 부족한지

대개 첫 프롬프트를 길게 늘이는 것보다, 이런 식의 짧은 2차 패스가 실행 가능성을 더 크게 높입니다.

이런 흔한 실패 신호를 점검하기

품질 문제로 특히 경계해야 할 것은 다음과 같습니다.

• 범위가 조용히 재설계 수준까지 커지는 경우
• 커밋 단계가 여전히 너무 큰 경우
• 테스트 전략이 빠진 경우
• 저장소 점검 없이 세운 가정에 기대는 경우
• 설명은 좋아 보이지만 실제 파일이나 모듈과 연결되지 않는 경우

이런 징후가 보이면, 검증된 코드 영역과 더 작은 변경 단위를 기준으로 계획을 다시 써달라고 요청하세요.

결과물을 실제 운영에 연결하는 가장 좋은 방법

request-refactor-plan이 좋은 issue 초안을 만들어줬다면, 그 문서를 단순 참고용이 아니라 실제 실행 문서로 다루는 것이 좋습니다.

• 팀과 함께 검토하기
• 너무 큰 커밋은 줄이거나 분할하기
• 위험한 단계는 담당자 지정하기
• 영향을 받는 테스트와 모듈을 링크하기
• 현실이 바뀌면 issue도 같이 업데이트하기

이 스킬의 가장 큰 가치는 계획을 “생성”하는 데서 끝나지 않습니다. 리팩터링을 더 쉽게 시작하고, 더 안전하게 실행하고, 더 쉽게 리뷰할 수 있게 만드는 데 있습니다.