Sonnet 5.5 리팩터링 프롬프트: 여러 파일을 바꿔도 작업 범위 지키기

Sonnet 5.5에 리팩터링을 맡길 때는 바꿔도 되는 파일, 유지해야 하는 동작, 완료를 입증할 결과를 지정해야 합니다. “코드를 정리해 줘”만으로는 세 가지 모두 모델의 판단에 맡기게 됩니다. 여러 파일을 나누는 작업에서는 지속적인 프로젝트 규칙을 CLAUDE.md에, 이번 분리 목표를 작업 프롬프트에 넣고, 나온 코드를 독립적으로 검증하세요.

이 글은 Python으로 작성한 작은 티켓 작업 시간 보고서를 사용합니다. CSV 해석, 합계 계산, 명령행 처리를 분리하면서 기존 공개 인터페이스를 유지하는 실습입니다. 실습 묶음 다운로드에는 시작 프로젝트, 계약 테스트 10개, 작업 프롬프트, 허용 경로 검사기, 참고 구현이 들어 있습니다. Python 3.10 이상과 Git이 필요하며, 오프라인 실습에는 외부 패키지나 API 키가 필요 없습니다.

참고 구현은 Ofox가 작성해 2026년 10월 8일 로컬에서 검사했습니다. Sonnet을 호출해 생성한 코드는 아닙니다. 테스트 통과는 이 구현이 제시한 조건을 만족한다는 뜻이며, 모델의 성공률이나 속도, 모든 지침을 항상 따르는 능력을 측정한 결과가 아닙니다. 모델에 프롬프트를 적용하려면 사용 권한이 있는 Claude Code 세션에서 실행하고 결과를 별도로 보관하세요.

코드 변경 전에 유지할 동작을 정의하기

시작 파일 ticket_report/report.py는 CSV를 읽고 티켓 ID와 시간을 검증한 뒤 팀별로 시간을 합산해 JSON을 출력합니다. 표 머리글은 정확히 id,team,hours 순서입니다. Decimal 계산을 사용하므로 0.1과 0.2의 합이 이진 부동소수점 근삿값으로 바뀌지 않습니다. JSON 값은 문자열로 유지하며 소수 표기도 보존합니다.

제공된 입력 예시를 실행하는 명령입니다.

python3 -m ticket_report fixtures/tickets.csv

예상 출력은 다음과 같습니다.

{"Billing": "1.50", "Support": "0.75"}

이 한 줄은 동작 계약의 일부일 뿐입니다. 기존 호출자는 계속 ticket_report.report에서 parse_rows와 summarize를 import할 수 있어야 합니다. 팀은 정렬된 순서로 나오고, 잘못된 입력 행은 조용히 버리는 대신 오류가 되어야 합니다. 파일이 없거나 명령행 인자가 잘못되면 종료 코드는 2입니다. 오류는 stderr에 기록하고 stdout에는 성공 결과를 출력하지 않습니다.

편집 전에 이런 조건을 적어 두세요. 그렇지 않으면 모델이 리팩터링을 검증 강화, 수치 정규화, 패키지 이름 변경, 명령 문법 변경까지 허용하는 요청으로 받아들일 수 있습니다. 각 변경은 유용할 수 있지만, 한 번에 섞으면 기존 호출이 왜 깨졌는지 찾기 어려워집니다.

이 실습은 티켓 시스템 전체를 다시 설계하는 과제가 아닙니다. 모든 CSV 형식의 완전한 검증, 악성 업로드 방어, 운영 규모의 성능을 보장하지 않습니다. 범위를 좁히면 전체 코드를 직접 읽을 수 있으면서도 여러 파일 사이의 실제 의존 관계를 검증할 수 있습니다.

격리된 기준 버전 준비하기

압축을 풀고 starter 디렉터리로 들어갑니다. 같은 수준의 reference는 작업 저장소 밖에 두세요. 모델이 참고 답안을 기존 애플리케이션 코드로 착각하지 않도록 하기 위해서입니다. 먼저 기준 상태를 만듭니다.

cd sonnet-refactor-kit/starter
git init
git add .
git commit -m "Baseline ticket report exercise"
python3 -m unittest discover -s tests -v
python3 -m ticket_report fixtures/tickets.csv

테스트 10개가 통과해야 합니다. Git이 사용자 정보를 요구하면 평소 프로젝트 정책에 따라 설정하고 다른 사람의 이름이나 이메일을 그대로 복사하지 마세요. 편집 전부터 테스트가 실패한다면 압축 해제와 실행 환경 문제부터 해결합니다. 정상 기준이 없으면 이후 실패가 모델이 만든 것인지 구분할 수 없습니다.

테스트는 소수 합계, 빈 표, 공백과 Unicode, 중복 ID, 잘못된 수치, 열 순서, 빈 팀 이름, 세 가지 CLI 결과를 다룹니다. 잘못된 시간 값에는 음수, 유한하지 않은 수, 빈 값, 숫자가 아닌 문자열을 포함합니다. 정상 입력 하나만 확인하는 것보다 유지해야 할 조건을 훨씬 구체적으로 보여 줍니다.

실제 저장소에서도 시작 커밋과 기존 미커밋 변경을 기록하고 작업 브랜치나 worktree를 선택하세요. 다른 사람의 작업을 없애는 광범위한 reset으로 환경을 정리하면 안 됩니다. 이 예시에서 새 저장소를 만드는 이유는 경로 검사기가 확실한 기준과 비교할 수 있도록 하기 위해서입니다.

CLAUDE.md에는 지속적인 규칙 넣기

Claude Code 메모리 문서는 CLAUDE.md를 지침 문맥으로 설명합니다. 강제 적용되는 설정은 아닙니다. “테스트를 바꾸지 말라”는 문장은 도움이 되지만 권한 통제와 검토를 대체하지 못합니다. /context로 로드된 메모리를 확인하고 의도한 프로젝트 파일이 포함됐는지 살펴보세요.

2026년 10월 8일 캡처한 영어 공식 문서입니다. 모델이 작업에 성공한 화면이 아니라 규칙의 출처를 보여 줍니다.

실습에 포함된 파일 전문입니다. 다운로드 파일 및 코드와 그대로 대조할 수 있도록 지침은 영어로 제공합니다.

# Ticket report exercise
Run commands from this directory. Python 3.10+; standard library only.
Run `python3 -m unittest discover -s tests -v` before and after changes.
Run `python3 -m ticket_report fixtures/tickets.csv` for the CLI contract.
Preserve the public imports `ticket_report.report.parse_rows` and `summarize`.
Keep Decimal arithmetic, JSON strings, sorted keys, error messages and exit codes.
Only edit report.py or add parsing.py and aggregation.py inside ticket_report/.
Do not change tests/, fixtures/, __main__.py, dependencies or this file.
No network, deployment, commits or unrelated cleanup are part of the task.
If a requirement conflicts with existing behavior, report it before changing behavior.
In the final response list files changed, commands and actual results, and limitations.
These instructions are task context, not a filesystem security boundary.

다른 프로젝트에 적용할 때는 명령과 보호할 경로를 먼저 바꾸세요. 존재하지 않는 테스트 명령을 복사하면 검증했다는 착각만 생깁니다. 일시적인 합격 조건은 현재 작업 프롬프트에 넣고, 과거의 모든 요청을 프로젝트 파일에 쌓지 않는 편이 좋습니다. 하위 폴더 지침이 루트 지침과 충돌하면 작업 전에 모순을 해결하세요.

한 번에 완전한 작업 프롬프트 전달하기

먼저 클라이언트에서 원하는 모델을 선택하고 설정을 확인합니다. Sonnet 5.5 Claude Code 설정 안내는 계정과 제공자 확인을 다룹니다. 모델 사용 가능 여부와 별칭이 가리키는 모델은 프롬프트 품질과 별개입니다. 답변에서 스스로 Sonnet이라고 소개하는 것은 실제 처리 모델의 증거가 아닙니다.

시작 프로젝트를 연 다음 아래 프롬프트를 사용합니다.

Refactor ticket_report/report.py without changing behavior.
First read CLAUDE.md and tests/test_contract.py, run the existing tests,
and explain the current contract.
Extract parse_rows to ticket_report/parsing.py and summarize to
 ticket_report/aggregation.py.
Keep report.py as the CLI coordinator and re-export both public functions.
Allowed changes: ticket_report/report.py, ticket_report/parsing.py,
and ticket_report/aggregation.py only.
Do not update tests or fixtures to accommodate your changes.
Do not add dependencies or deploy.
After editing run the full test suite and CLI example; inspect the final diff.
Report actual test output, the file list, and remaining limitations.
If blocked, report the exact blocker.

이 프롬프트는 목표 파일 구조와 외부에서 확인할 수 있는 동작을 함께 지정합니다. “다시 내보내기”가 특히 중요합니다. 함수를 다른 모듈로 옮기는 것만으로는 기존 경로에서 import하는 호출자를 보호할 수 없습니다. 명령행 조정 역할도 원래 자리에 두면 파일을 보기 좋게 나누다가 python -m ticket_report 진입점까지 바꾸는 일을 줄일 수 있습니다.

Anthropic의 Sonnet 5.5 프롬프트 안내는 effort가 자율적인 작업과 검증 행동에 영향을 줄 수 있다고 설명하며, 요청 범위를 명시하라고 권합니다. 설정을 의식적으로 고른 뒤 실제 결과를 평가하세요. 높은 설정이 테스트를 대체하지는 않습니다. effort 단계 안내는 선택에 참고할 수 있지만 이 실습의 합격 조건을 바꾸지는 않습니다.

모델이 더 넓은 정리를 제안하면 후속 작업 메모에 남기세요. 여기서 관련 없는 의존성 업데이트를 제외하는 것은 그 업데이트가 나쁘다는 뜻이 아닙니다. 이번 변경을 검토 가능한 크기로 유지하고, 회귀가 생겼을 때 원인을 적은 변경에서 찾기 위한 선택입니다.

구현, 테스트, 변경 경로를 따로 검증하기

세션이 끝난 뒤 starter에서 직접 명령을 실행하세요. 실제 출력 없이 “모두 성공했다”는 설명만 받아들이면 안 됩니다.

python3 -m unittest discover -s tests -v
python3 -m ticket_report fixtures/tickets.csv
python3 ../scope_check.py
git diff --check
git diff HEAD

범위 검사기는 HEAD 대비 추적 중인 변경과 Git이 무시하지 않는 미추적 파일을 모두 확인합니다. 두 번째 검사가 중요합니다. 새로 분리한 모듈은 아직 추적되지 않아 일반적인 미스테이징 diff에서 빠질 수 있기 때문입니다. 허용 목록은 ticket_report 아래의 report.py, parsing.py, aggregation.py 세 파일뿐입니다.

예상 변경 경로는 이 세 개이며 범위 밖 파일이 없어야 합니다. 그러나 경로 검사 통과가 구현의 정확성을 증명하지는 않습니다. 허용 파일 내부의 잘못된 수정도 경로 검사에는 통과합니다. 반대로 테스트가 성공해도 입력 예시나 설정을 임의로 바꾼 것이 정당화되지는 않습니다. 두 검사를 모두 수행하고, 추적 파일의 diff뿐 아니라 새 파일 내용도 읽어야 합니다.

참고 구현에서는 report.py가 옮겨진 함수를 import하면서 인자, 오류, JSON 처리를 계속 담당합니다. 따라서 기존 공개 import가 유지됩니다. 시작 버전과 참고 버전 모두 같은 테스트 10개를 통과했고 CLI 입력 예시는 위 JSON을 출력했습니다. 이는 로컬 참고 구현의 결과이며 여러분의 모델 실행은 다를 수 있습니다.

기준을 낮추지 말고 실패 부분만 고치기

전체 작업을 처음부터 다시 시키는 것보다 구체적인 수정 프롬프트가 유용합니다.

The original test test_cli_missing_file now fails: expected exit code 2.
Keep the original tests unchanged. Inspect only the allowed files and
restore the prior CLI error behavior. Run all ten tests, the CLI fixture,
and the scope checker again. Report the actual output.

위 오류는 수정 템플릿의 예시입니다. 실제로 다른 테스트가 실패했다면 관찰한 테스트 이름과 출력을 넣으세요. 범위 밖 파일이 수정됐다면 해당 변경을 직접 확인하고 이번 작업에서 의도하지 않은 부분만 복구합니다. 실제 프로젝트에서 관련 없는 작업까지 버릴 수 있는 일괄 명령은 피해야 합니다.

실제 처리 모델의 증거, 전체 프롬프트, 기준 커밋, 패치, 테스트 출력, 수정 시도 내역을 함께 저장하세요. 나중에 Sonnet과 Opus의 코딩 결과를 비교할 때도 같은 시작 상태와 합격 조건을 사용해야 합니다. 작은 리팩터링 한 번의 성공은 그 실행의 증거일 뿐, 모델의 보편적인 우위를 뜻하지 않습니다.

결과를 넘길 때 확인할 조건

같은 방법으로 데이터베이스 접근이나 서식 함수를 분리할 수도 있지만 먼저 해당 동작 계약을 추가해야 합니다. 데이터베이스 작업에는 트랜잭션 경계가, 비동기 작업에는 예외와 취소 동작이 중요합니다. 이 테스트 10개를 모든 프로젝트에 충분한 목록으로 사용하지 마세요. 기존 동작에 의존하는 호출자를 찾은 뒤 필요한 회귀 사례를 정해야 합니다.

기존 import가 작동하고, 수정하지 않은 테스트 10개가 통과하며, CLI 출력이 일치하고, 허용된 세 경로만 바뀌었고, 모듈별 역할을 읽고 이해할 수 있다면 실습을 완료한 것으로 볼 수 있습니다. 검증하지 못한 조건은 기록하고 작업 범위를 조용히 넓히지 마세요. 결과는 확인 가능한 작은 리팩터링과 재사용할 지침입니다. 지침만으로 원하지 않는 모든 편집을 막을 수 있다는 보장은 아닙니다.