전임 개발자가 인수인계 없이 떠나면 PHP 코드만 남습니다. 배송비가 왜 이렇게 나오는지는 코드를 한 줄씩 읽어야 압니다. 앤트로픽 공식 마켓의 code-modernization 플러그인은 옛 코드를 분석해 새 코드로 옮기는 과정을 안내하고, 그중 /code-modernization:modernize-extract-rules가 업무 규칙을 뽑아 줍니다. 플러그인은 무료이고 클로드 유료 요금제의 사용량을 씁니다. 2026-11-01 macOS 26.1, Claude Code 2.1.299에서 규칙을 숨겨 둔 주문 계산 PHP 코드로 플러그인 없이 2번, 이 명령으로 2번 규칙 문서를 만든 기록입니다.
- 미리 숨겨 둔 업무 규칙 14개를 4번 모두 빠짐없이 찾았습니다. 주석과 코드가 다른 곳(“10개 이상”인데 실제로는 11개부터)도 4번 모두 짚었습니다.
- 플러그인 없이 한 쪽은 2분 안팎, 0.3달러대로 한국어 문서 한 장을 만들었고, 원본 PHP를 직접 돌려 경계값까지 확인했습니다. 다만 근거 줄 번호가 없습니다.
- 플러그인 쪽은 작업 에이전트(한 가지 일을 맡는 별도 클로드) 52개와 66개가 규칙마다
파일:줄근거와 예시를 달고 서로 검증했습니다. 대신 문서가 영어로 나왔고, 비용은 2달러대로 7배쯤 들었습니다.
결과부터 보기: 같은 코드, 찾은 규칙은 같았다
실습 코드는 2009년에 짰다는 설정의 가상 쇼핑몰 주문 금액 계산 PHP 4개 파일, 135줄입니다. 회원 등급 할인, VIP 생일 달 할인, 대량 구매 할인, 쿠폰, 적립금, 제주·도서산간 배송비, 출고일 계산을 넣었습니다. 일부러 함정도 심었습니다. 모바일 주문만 무료배송 기준을 3만 원으로 낮추는 줄을 설정 파일이 아닌 계산 파일 중간에 숨겼고, 주석은 “10개 이상”인데 코드는 11개부터 할인하게 짰습니다. 2012년에만 동작하는 이벤트 코드도 남겨 뒀습니다.
직접 눌러 보기: 옛 PHP 코드와 결과 문서 4개 나란히 보기, 플러그인이 만든 한 장짜리 보고서. 결과 문서는 손대지 않은 그대로입니다.
| 조건 | 숨긴 규칙(14) | 확인할 점(3) | 줄 번호 근거 | 걸린 시간 | 비용(달러) |
|---|---|---|---|---|---|
| 플러그인 없이 1 | 14 | 3 | 없음 | 1분 반쯤 | 0.31 |
| 플러그인 없이 2 | 14 | 3 | 없음 | 2분쯤 | 0.37 |
| modernize-extract-rules 1 | 14 | 2 | 있음(표본 5개 모두 맞음) | 3분쯤 | 2.51 |
| modernize-extract-rules 2 | 14 | 2 | 있음(표본 5개 모두 맞음) | 2분 반쯤 | 2.05 |
채점 기준은 실행 전에 플러그인 안내문에서 뽑아 고정했습니다. 숨긴 규칙 14개, 사람에게 물어야 할 이상한 점 3개, 규칙마다 근거 줄이 있는지 1점으로 18점 만점이고, 4번 모두 17점이었습니다. 플러그인 없이 한 쪽은 근거 줄 번호가 없어 1점을 잃었습니다. 플러그인 쪽은 “무료배송은 정가 기준, 쿠폰 최소금액은 할인 후 기준이라 기준이 서로 다르다”는 점을 짚지 못해 1점을 잃었습니다. 지어낸 규칙은 4번 모두 없었습니다.
직접 실행 확인한 날짜 2026-11-01
- 실행 환경
- macOS 26.1 · Claude Code 2.1.299 · Sonnet 5.5 · 생각 깊이 중간 (4번 모두 같은 설정, 플러그인의 작업 에이전트도 Sonnet 5.5)
- 설치 난이도
- 클로드 코드 안에서 명령 한 줄(공식 README). 이번에는 플러그인 폴더를 그 실행에만 불러 씀
- 비용
- 플러그인 무료. 135줄 규칙 뽑기 한 번에 실행 기록 기준 2.05~2.51달러어치(없이는 0.31~0.37달러)
- 라이선스
- Apache-2.0 · anthropics/claude-plugins-official(별 45,589개, 2026-11-01 기준)
code-modernization 플러그인에 든 것
code-modernization 1.0.0은 anthropics/claude-plugins-official 공식 마켓에 들어 있습니다. Claude 앱 플러그인 디렉터리에는 앤트로픽 검토를 마쳤고 클로드 코드·코워크·클로드 앱에서 쓸 수 있다고 표시돼 있습니다(디렉터리 표시, 2026-11-01 확인). README가 내세우는 것은 네 가지입니다. 옛 코드가 무엇을 하는지 파악하고, 사람이 승인할 계획을 세우고, 새 코드로 옮기고, 새 코드가 옛 코드와 똑같이 동작한다는 증거를 남깁니다. 명령 13개, 코드 읽기·검증 같은 일을 맡는 전문 에이전트 8개, 여러 에이전트를 한꺼번에 돌리는 워크플로 6개로 이뤄져 있습니다.
| 명령 | 하는 일 |
|---|---|
| /code-modernization:modernize | 시작 명령. 무엇을 하고 싶은지 두 가지만 묻고 다음 명령을 알려 줌 |
| modernize-preflight | 빌드·테스트 환경 점검, 사람만 답할 수 있는 질문 5개 |
| modernize-assess · modernize-map | 코드 규모·복잡도·부채 평가, 구조와 데이터 흐름 지도 |
| modernize-extract-rules | 업무 규칙을 Given/When/Then(주어진 조건/할 때/결과) 카드로, 파일:줄 근거와 함께(이 글에서 써 봄) |
| modernize-review · modernize-brief | 사람이 규칙을 확인하고, 단계별 계획을 승인 |
| modernize-uplift · transform · reimagine | 같은 기술 새 버전으로 올리기, 다른 기술로 다시 쓰기, 새 구조로 다시 짓기 |
| modernize-verify · modernize-harden | 옛 코드와 새 코드에 같은 입력을 넣어 결과 비교, 보안 점검 |
| modernize-status | 지금 어디까지 했고 다음에 무엇을 칠지 |
README는 COBOL 은행 프로그램, PHP 쇼핑몰(osCommerce), 자바 8 서버 같은 공개 코드에 실제로 돌려 본 결과도 적어 두었습니다. 계획을 승인하기 전에는 아무것도 새로 짓지 않고, 원본 코드는 고치지 않으며 결과는 analysis/와 modernized/ 폴더에만 쓴다고 밝힙니다. 또 사용 횟수를 숫자로만 앤트로픽에 보내는 훅이 들어 있습니다. 코드·파일 이름·요청문은 보내지 않는다고 적혀 있고, 클로드 코드의 원격 측정을 끄거나 CODE_MODERNIZATION_TELEMETRY=0을 두면 보내지 않습니다. 이번 실험은 이 값을 0으로 두고 돌렸습니다.
따라 해 보기: 요청문과 실습 재료
플러그인 없이 한 쪽은 코드가 든 폴더에서 클로드 코드에 아래 요청을 보냈습니다.
legacy/shop 폴더는 예전 개발자가 인수인계 없이 남기고 간 쇼핑몰 주문 금액 계산 PHP 코드입니다. 이 코드에 들어 있는 업무 규칙을 빠짐없이 정리해 주세요. 다음 개발자가 이 문서만 보고 새로 만들 수 있어야 합니다. 원본 코드는 고치지 말고, 결과는 analysis/ 폴더에 만들어 주세요.
플러그인 쪽은 명령 한 줄만 보냈습니다. 이 명령은 뒤에 시스템 이름과 대상 폴더 패턴만 받아서 요청문을 붙이지 않았습니다. 코드는 legacy/shop 폴더에 두었습니다.
/code-modernization:modernize-extract-rules shop
좋은 답이라면 “11개부터 할인”처럼 실제 동작을 적고, 주석과 다르다는 점은 기획 담당자에게 물을 질문으로 따로 모읍니다. 지금은 쓰이지 않는 2012년 이벤트 코드도 “지워도 되는지” 묻습니다. 실습 재료(zip)에는 PHP 코드 4개 파일과 주문 예시, 요청문, 숨긴 규칙 정답이 든 채점 기준을 넣었습니다. 회사·사람 이름은 모두 지어낸 것입니다.
1단계. 플러그인 넣기 (약 1분)
이 단계에서는 클로드 코드가 code-modernization 명령을 쓸 수 있게 합니다. 공식 README의 설치 방법은 클로드 코드 안에서 아래 한 줄입니다. 이 설치 명령은 이번에 실행하지 않았습니다.
/plugin install code-modernization@claude-plugins-official
이번 실험은 공식 마켓에서 받아 둔 플러그인 폴더를 그 실행에만 불러왔습니다. 설정 파일을 건드리지 않아 시험해 보기에 좋습니다. 터미널에서 아래처럼 하면 비슷한 상태가 됩니다.
git clone --depth 1 https://github.com/anthropics/claude-plugins-official.git
CODE_MODERNIZATION_TELEMETRY=0 claude --plugin-dir claude-plugins-official/plugins/code-modernization
이렇게 나오면 성공 이번에는 --plugin-dir로 불러온 상태에서 2단계 명령이 바로 인식돼 실행됐습니다. 명령이 “알 수 없는 명령”으로 나오면 플러그인이 불러와지지 않은 것입니다.
- 분석할 코드는
legacy/<이름>폴더에 두거나,/code-modernization:modernize <이름> --source <코드 경로>로 연결합니다. 이 폴더가 없으면 명령이 멈추고 이 방법을 알려 줍니다. command not found: claude가 나오면 터미널을 닫았다 다시 열고claude --version을 먼저 확인합니다.- 필요 없어지면
claude plugin uninstall code-modernization으로 지웁니다.--plugin-dir로 불렀다면 설정은 바뀌지 않습니다. 다만~/.claude/plugins/data/code-modernization-inline빈 폴더가 생길 수 있고, 비어 있으면 지워도 됩니다.
2단계. 같은 코드로 업무 규칙 뽑기 (2~3분)
이 단계에서는 같은 코드로 규칙 문서 4개를 만들어 비교합니다. 4번 모두 원본 PHP 파일은 바뀌지 않았습니다(실행 전후 파일 지문이 같음). 플러그인 명령은 2번 모두 코드 크기를 먼저 세고 “4개 파일, 135줄이라 작은 코드용 방식(lens 모드)으로 에이전트 15~40개쯤 쓴다”고 알린 뒤 워크플로를 시작했습니다. 실제로는 66개와 52개가 돌았습니다.

플러그인 없이: 한국어 문서 한 장, 직접 돌려 확인까지
플러그인 없이 2번은 모두 analysis/order-calc-business-rules.md 한 장을 만들었습니다. 입력·출력 칸, 설정값, 계산 순서, 규칙별 설명, 새로 짤 때 쓸 의사코드(사람 말에 가까운 코드)까지 들어 있습니다. 2번 모두 원본 PHP를 직접 실행해 예시 주문의 최종 금액 31,920원을 손계산과 맞춰 봤고, 49,999원과 50,000원 같은 경계값을 12~14건 더 돌려 표로 넣었습니다.
기획 담당자에게 확인할 점은 1번째가 13가지, 2번째가 15가지로 모았습니다. 숨긴 이상한 점 3개가 모두 들어 있었고, 채점표에 없던 문제도 하나 찾았습니다. 쿠폰이 상품 금액보다 크면 실제로는 상품 금액까지만 깎이는데, 결과에 찍히는 쿠폰 금액은 입력값 그대로 남는다는 점입니다. 정산 화면에 이 값을 쓰면 금액이 어긋납니다.

modernize-extract-rules: 줄 번호 근거가 붙은 규칙 카드 19장
플러그인 쪽은 2번 모두 규칙 19개를 찾아 BUSINESS_RULES.md, 데이터 항목 정리 DATA_OBJECTS.md, 한 장짜리 보고서 REPORT.html을 만들었습니다. 규칙마다 분류(계산·검증·정책), 중요도(P0은 틀리면 돈이 잘못 나가는 규칙), 근거 order_calc.php:47-49 같은 위치, Given/When/Then 예시, 확신도가 붙습니다. 근거 줄을 표본 5개 골라 원본과 대조했더니 모두 맞는 줄이었습니다.

안에서는 이렇게 일했습니다. 규칙을 찾는 에이전트 셋이 서로 다른 관점으로 코드를 읽고, 다른 에이전트가 인용한 줄을 다시 읽어 근거가 맞는지 확인합니다. 중요도 P0 규칙은 판정 에이전트 둘이 한 번 더 봅니다. 2번째 실행에서는 경로를 util.php로 잘못 적은 후보 하나를 검증 단계가 걸러 냈습니다. 같은 동작을 말하는 후보는 하나로 합쳤습니다.

아쉬운 점도 분명했습니다. 문서가 영어로 나왔습니다. 요청에 언어를 지정할 칸이 없어, 한국어가 필요하면 결과를 다시 번역시켜야 합니다. 합친 뒤에도 겹치는 카드가 남았습니다. 2번째는 “최종 결제액”과 “최종 결제액과 적립 포인트”가 따로 있었고, 실행 스스로 겹침 4쌍을 손으로 합치라고 알렸습니다. 2번 모두 정해진 2라운드에서 멈추면서 “더 찾을 규칙이 남았을 수 있다”고 밝혔습니다. 쿠폰 금액이 그대로 찍히는 문제는 2번 모두 짚지 못했습니다.

보고서 맨 위에는 다음 단계 명령(modernize-preflight)과 진행 표시가 있습니다. 규칙 뽑기만 끝난 상태라 나머지 단계는 “아직”으로 나옵니다.
# 플러그인 없이: 요청문 그대로 / 플러그인: --plugin-dir 추가, 요청은 명령 한 줄
claude -p "$(cat tools/request.txt)" --model claude-sonnet-5-5 --effort medium \
--setting-sources project,local --permission-mode acceptEdits [--plugin-dir skill/code-modernization] \
--allowedTools "Bash(python3:*),Bash(php:*),Bash(ls:*),Read,Write,Edit,Skill,Glob,Grep,Agent,Task,Workflow" --output-format stream-json --verbose
조건 번호 시작 끝 걸린 시간 비용(USD, 실행 기록) 턴 작업 에이전트 규칙 수
없이 1 12:44:12 12:45:43 1분 반쯤 0.31 13 0 14 + 확인 사항 13
없이 2 12:44:12 12:46:08 2분쯤 0.37 17 0 14 + 확인 사항 15
플러그인 1 12:44:12 12:47:09 3분쯤 2.51 3+6 66 19(P0 6)
플러그인 2 12:44:12 12:46:51 2분 반쯤 2.05 5+6 52 19(P0 6)
이런 사람에게 권합니다
- ✅ 인수인계 없이 받은 작은 프로그램의 규칙을 빨리 알고 싶은 사람. 이번 135줄 코드에서는 플러그인 없이 위 요청문만으로도 규칙을 모두 찾았고, 한국어 문서로 2분 안팎에 끝났습니다.
- ✅ 규칙마다 근거 줄을 남겨 다른 사람이 확인해야 하는 경우. 감사·인수 검토, 기획자 확인용이면 플러그인의 줄 번호 근거와 검증 단계가 쓸모 있습니다.
- ✅ 큰 옛 시스템을 실제로 옮길 계획인 팀. 규칙 뽑기 뒤에 계획 승인, 옮기기, 옛 코드와 결과 비교까지 이어지는 흐름은 이 플러그인만의 것입니다.
- ❌ 작은 코드를 한 번 훑어보려는 사람. 이번 조건에서는 비용이 7배쯤 들었습니다.
한계와 주의할 점
- 135줄짜리 작은 코드로 조건마다 2번씩 돌렸습니다. 명령 안내문에는 프로그램 44개, 3만 줄 규모에서 에이전트 466~647개, 50~80분이 든 예가 적혀 있습니다. README는 큰 코드를 한 모듈씩 나눠 시작하라고 권합니다.
- 규칙 뽑기 명령만 써 봤습니다. 계획 승인, 새 코드로 옮기기, 옛 코드와 결과 비교, 보안 점검은 확인하지 않았습니다.
- 심어 둔 규칙과 정답은 실험용으로 직접 만든 것이라 실제 회사 코드보다 쉬울 수 있습니다.
- 회사 코드는 외부 AI에 올려도 되는지 정책을 먼저 확인합니다. 코드 안의 비밀번호·키는 플러그인이 가린다고 밝히지만, 이번 실습 코드에는 넣지 않아 확인하지 못했습니다.
대안
| 이름 | 다른 점 | 이럴 때 고르세요 |
|---|---|---|
| 클로드 코드에 요청만 | 설치 없음, 한국어, 직접 실행해 경계값 확인. 근거 줄은 요청해야 붙음 | 작은 코드를 빨리 파악할 때 |
| modernize-extract-rules(이 글) | 파일:줄 근거, 검증 에이전트, 영어 카드와 보고서 | 근거를 남겨 다른 사람이 확인해야 할 때 |
| 리팩토링 글(code-simplifier) | 동작은 그대로 두고 코드를 정리 | 규칙 파악보다 코드 정돈이 먼저일 때 |
| 스펙킷 | 명세부터 쓰고 새로 짓는 개발 방식 | 옛 코드를 버리고 새로 만들 때 |
| 클로드 코드 리뷰 글 | 바뀐 코드의 문제를 찾는 검사 | 옮긴 뒤 새 코드를 검사할 때 |
자주 묻는 질문
요청문 끝에 “줄 번호도 적어 줘”를 붙이면 되지 않나요?
이번에는 그 조건을 돌려 보지 않았습니다. 플러그인 없이 만든 문서도 파일 이름은 적었으니, 줄 번호를 요청에 넣으면 붙을 가능성이 큽니다. 플러그인과의 차이는 다른 에이전트가 그 줄을 다시 읽어 확인하는 단계입니다.
플러그인 결과를 한국어로 받을 수 있나요?
이번 2번은 모두 영어로 나왔습니다. 명령이 시스템 이름만 받아서 언어를 지정하지 못했습니다. 끝난 뒤 “BUSINESS_RULES.md를 한국어로 옮겨 줘”라고 따로 시키면 됩니다.
COBOL이나 자바 코드도 되나요?
README는 COBOL, 자바, .NET, PHP, 파이썬, C 등 어떤 언어든 된다고 하고, 실제로 돌려 본 공개 코드 목록을 적어 두었습니다. 이번에는 PHP만 해 봤습니다.
돈이 드나요?
플러그인 자체는 무료입니다. 이번 135줄 코드에서 든 사용량은 위 표에 있습니다. 여러 에이전트를 한꺼번에 돌려서 코드가 클수록 사용량이 빠르게 늘어납니다.
출처
anthropics/claude-plugins-official 저장소, code-modernization 플러그인(README·명령 안내문) (2026-11-01 확인)