---
name: refactor-code
description: >
  외부 동작을 유지하면서 코드 구조·중복·모듈 경계·유지보수성을 개선할 때 쓴다.
  기존 동작과 공개 계약을 기준으로 작은 변경과 동등성 검증을 수행한다.
  새 동작 구현이나 버그 수정, 단순 문장 편집은 별도 작업이다.
metadata:
  org.opspresso.agent-studio.icon: transform
---

# 동작을 보존하는 리팩토링

개선할 구체적인 문제와 보존할 계약을 먼저 확인한다. 새 추상화나 파일 분리 자체를 성과로 삼지 않는다.

1. 대상 경로, 유지보수 문제와 원하는 개선을 확인한다. 공개 API·저장 형식·오류·순서·부수 효과 중
   보존할 동작을 읽고 기존 테스트를 기준선으로 삼는다.
2. 동작이 불명확한 중요한 경계에는 작은 특성 테스트나 비교 fixture를 만든다.
   기존 테스트를 다시 쓰는 대신 실제 회귀를 구별할 수 있는 검증을 선택한다.
3. 호출 관계와 소유권에 맞춰 필요한 구조만 바꾼다. 새 기능, 의존성 업그레이드와 대규모 포맷 변경을 섞지 않는다.
4. 같은 입력에 대한 결과·오류·부수 효과가 유지되는지 전후로 비교하고 필수 검사를 실행한다.
   성능 개선도 요청됐다면 같은 환경·입력의 기준선과 변경 후 수치를 비교한다.
5. 발견한 기존 버그가 범위 밖이면 별도로 알린다. 고친다면 동작 변화와 그 근거를 명시해 리팩토링에 숨기지 않는다.

파일 작업은 제공된 실행 도구에서 수행한다. 호스트 앱에서는 `workspace-task`를 통해
기존 공간을 유지하고 코딩 Runtime에 변경할 구조와 보존할 계약·검사를 전달한다.
실행 도구가 없으면 변경 제안과 검증 한계를 설명한다.

결과에는 개선한 구조, 유지한 계약과 확인한 동등성 검증을 담는다. 호스트 앱에서는 사용자가
범위를 제한하지 않으면 `workspace-task`의 Git 게시 절차로 커밋·작업 브랜치 푸시·PR까지 추가 승인 없이 수행한다. native Git 메타데이터를 바꾸거나 사용자 변경을 되돌리지 않는다.