improve: 비싼 모델이 감사(Audit)하고 저렴한 모델이 실행할 계획을 만드는 에이전트 스킬

9bow · 6월 25, 2026, 11:30오전

improve 소개

코드베이스가 커질수록 "무엇을 고쳐야 하는가"를 판단하는 일과 "그것을 실제로 구현하는 일"은 점점 다른 종류의 작업이 됩니다. 앞쪽은 저장소 전체를 이해하고 무엇이 가치 있는지 가려내며 명세를 쓰는 깊은 판단의 영역이고, 뒤쪽은 명세가 분명하기만 하면 비교적 기계적인 작업입니다. 그런데 많은 AI 코딩 도구는 이 둘을 같은 모델로 한꺼번에 처리하다 보니, 비싼 모델의 추론 능력을 단순 구현에까지 똑같이 소모하게 됩니다.

improve는 이 두 단계를 의도적으로 분리하는 에이전트 스킬(Agent Skill)입니다. 가장 똑똑한, 그래서 가장 비싼 모델은 코드베이스를 감사(audit)하고 무엇을 할지 판단해 실행 계획서를 쓰는 데에만 쓰고, 실제 구현은 더 저렴한 모델에게 넘깁니다. improve 자신은 어떤 코드도 직접 구현하지 않습니다. 만든 사람인 shadcn 은 이 점을 "The plan is the product", 즉 계획서 자체가 결과물이라는 한 문장으로 정리합니다.

improve는 특정 에디터에 묶인 제품이 아니라 Agent Skills 형식을 지원하는 어떤 에이전트에서도 동작하는 스킬입니다. 작성된 계획서는 평범한 마크다운이라 다른 에이전트는 물론 사람이 직접 집어 실행해도 됩니다. 아래 그림은 improve가 비싼 모델과 저렴한 모델 사이에 일을 어떻게 나누는지를 요약한 것입니다.

improve의 동작 원리

improve의 한 번 실행은 다섯 단계로 흐릅니다. 정찰에서 시작해 계획서로 끝나며, 비싼 모델이 책임지는 부분은 여기까지입니다.

정찰(Recon) 단계에서는 저장소의 기술 스택과 컨벤션, 그리고 정확한 빌드·테스트·린트 명령을 파악합니다. 이 명령들은 이후 모든 계획서에서 검증 게이트(verification gate)로 다시 쓰입니다. ADR(docs/adr/), PRD, CONTEXT.md, DESIGN.md, PRODUCT.md 같은 의도·설계 문서가 있으면 함께 읽어 들여, 이미 결정된 트레이드오프를 새삼 문제로 잡아내지 않고 방향 제안도 명시된 제품 의도에 근거하도록 합니다.

감사(Audit) 단계에서는 병렬 서브에이전트를 아홉 개 범주에 펼칩니다. 정확성, 보안, 성능, 테스트 커버리지, 기술 부채, 의존성 및 마이그레이션, 개발자 경험(DX), 문서, 그리고 방향(기능 제안)입니다. 마지막 방향 범주의 제안은 모두 저장소 자체에서 나온 근거를 인용해야 하며, 일반론적인 아이디어 나열은 허용되지 않습니다. 모든 발견 항목은 file:line 형태의 근거와 영향도, 노력, 신뢰도를 함께 답니다.

검증(Vet) 단계가 그다음에 옵니다. 서브에이전트는 과하게 보고하는 경향이 있으므로, 어드바이저 모델이 사용자에게 무언가를 보여주기 전에 인용된 모든 위치를 직접 다시 읽습니다. 이 과정에서 거짓 양성(false positive)은 버려지고, 잘못된 위치 지정은 교정되며, 기각된 항목은 다음 실행에서 되살아나지 않도록 사유와 함께 기록됩니다.

우선순위(Prioritize) 단계에서는 발견 항목을 레버리지 순으로 정렬한 표를 만듭니다. 정렬 기준은 영향도를 노력으로 나눈 값에 신뢰도로 가중치를 준 것입니다. 어떤 항목을 계획서로 만들지는 사용자가 직접 고릅니다.

계획(Plan) 단계에서는 선택된 발견 항목마다 파일 하나씩을 plans/ 디렉토리에 씁니다. 권장 순서를 담은 인덱스와 의존성 그래프가 함께 만들어집니다.

improve가 만드는 실행 가능한 계획

improve의 계획서는 "가장 약한 실행자"를 기준으로 작성됩니다. 어드바이저 세션을 한 번도 본 적이 없고 훨씬 작을 수도 있는 모델이 그 계획서만 읽고도 작업을 끝낼 수 있어야 한다는 뜻입니다. 이를 위해 세 가지 속성을 갖춥니다.

자기완결성(Self-contained): 정확한 파일 경로, 현재 상태의 코드 발췌, 모범 파일을 곁들인 저장소 컨벤션, 검증된 명령까지 모든 맥락을 계획서 안에 인라인으로 담습니다. "위에서 논의한 대로" 같은 외부 참조가 없습니다.
검증 게이트(Verification gates): 모든 단계는 명령 하나와 그 기대 출력으로 끝납니다. 완료 기준이 기계적으로 확인 가능하므로, 실행자는 자신이 성공했는지를 스스로 판단할 필요가 없습니다.
명확한 경계(Hard boundaries): 범위 밖 항목을 명시적으로 나열하고, "만약 X라면 멈추고 보고하라"는 형태의 STOP 조건을 둡니다. 작은 모델이 현실과 계획이 어긋날 때 임의로 즉흥 대응하는 것을 막기 위함입니다.

각 계획서는 자신이 작성된 시점의 git 커밋을 함께 기록해 둡니다. 그래서 실행자는 무언가를 건드리기 전에 기계적인 드리프트(drift) 검사를 먼저 수행할 수 있습니다.

improve가 루프를 닫는 방식

계획서는 한 번 던져 두고 마는 산출물이 아닙니다. improve는 계획 이후의 흐름까지 명령으로 제공합니다.

execute <plan> 은 더 저렴한 실행자 서브에이전트를 격리된 git 워크트리에서 띄워 계획서를 넘긴 뒤, 그 결과를 테크 리드처럼 검토합니다. 완료 기준을 모두 다시 실행하고, 범위를 지켰는지 확인하며, 변경된 diff를 의도와 대조해 읽습니다. 판정은 승인(병합 여부는 여전히 사용자 몫), 수정 요청(최대 2회), 또는 차단 후 계획서 재정비 중 하나입니다.

reconcile 은 직전 실행 이후 일어난 일을 정리합니다. 완료된(DONE) 계획이 여전히 유효한지 검증하고, 막힌(BLOCKED) 계획은 원인을 조사해 장애물을 우회하도록 다시 쓰며, 드리프트된 계획을 갱신하고, 다른 경로로 이미 고쳐진 항목은 폐기합니다.

--issues 옵션을 붙이면 계획서를 GitHub 이슈로 발행합니다. 같은 자기완결 본문이 그대로 들어가므로, 작업이 이미 진행되는 곳에서 어떤 에이전트나 사람이든 집어 들 수 있습니다.

improve의 하드 룰

improve는 권한 측면에서 보수적으로 설계되어 있습니다. 만든 사람이 README에 명시한 하드 룰은 다음과 같습니다.

소스 코드를 직접 수정하지 않습니다. 쓰기 작업은 오직 plans/ 로만 향하고, 실행자는 폐기 가능한 워크트리에서만 코드를 편집하며, 병합은 항상 사용자의 결정입니다.
작업 트리를 변경하는 명령을 실행하지 않습니다. 읽기, 검색, 읽기 전용 분석만 수행합니다.
비밀 값(secret)을 재현하지 않습니다. 위치와 자격 증명 유형만 다루고, 회전(rotation)을 항상 권고합니다.
구현을 요청받으면 거절하고 계획서를 가리키거나 execute 를 제안합니다.

improve 설치 및 사용법

Agent Skills 형식을 지원하는 에이전트에서 다음 명령으로 설치합니다.

npx skills add shadcn/improve

설치 후에는 /improve 계열 명령으로 호출합니다. 전체 감사부터 단일 항목 계획, 실행 위임까지 용도별로 나뉘어 있습니다.

/improve                        전체 감사 → 우선순위 발견 항목 → 계획서
/improve quick                  핫스팟과 상위 발견 항목만 보는 저비용 패스
/improve deep                   모든 패키지·모든 범주를 훑는 철저한 감사
/improve security               보안에 집중한 감사 (perf, tests, bugs 등도 가능)
/improve branch                 현재 브랜치가 바꾼 부분만 감사
/improve next                   프로젝트를 어디로 끌고 갈지 기능 제안
/improve plan <description>     감사를 건너뛰고 한 가지만 명세
/improve review-plan <file>     기존 계획서를 비평하고 다듬기
/improve execute <plan>         더 저렴한 실행자에게 위임하고 결과를 검토
/improve reconcile              백로그 갱신: 검증, 차단 해제, 폐기
/improve ... --issues           계획서를 GitHub 이슈로도 발행

처음 실행할 때의 전형적인 흐름은 다음과 같습니다. 저장소에서 에이전트를 열고 /improve(저렴하게 가려면 /improve quick)를 실행하면, improve가 저장소를 매핑하고 감사한 뒤 발견 항목 표를 들고 돌아옵니다. 계획으로 만들고 싶은 항목을 "1, 3, 5번을 계획해 줘"처럼 답하면, 계획서가 plans/ 에 한 파일씩 권장 순서와 함께 쌓입니다. 그 계획서를 아무 에이전트에게나 넘기거나 /improve execute 001 로 직접 실행하게 할 수 있고, 다음 세션에서는 /improve reconcile 로 백로그를 정리합니다. PR을 올리기 전이라면 /improve branch 가 같은 일을 브랜치 변경분에만 한정해 수행합니다.

저장소의 examples/ 디렉토리에는 shadcn/ui를 대상으로 한 실제 감사에서 1번 항목을 골라 만든 예시 계획서가 들어 있어, improve가 만드는 계획서의 형태를 직접 확인할 수 있습니다.

improve의 실제 감사 예시

README에는 shadcn/ui 저장소를 대상으로 돌린 실제 감사 결과의 일부가 실려 있습니다. improve가 돌려준 발견 항목 표는 아래와 같은 형태입니다.

#	발견 항목	범주	노력	신뢰도
1	shadow-config 로직이 `search.ts`/`view.ts`에 중복되어 있고, 두 사본이 이미 어긋남 (`search.ts:31`에 TODO)	tech-debt	M	HIGH
2	O(n^2) 아이콘 마이그레이션 (`migrate-icons.ts:168`)	perf	S	HIGH

표에서 보듯 모든 항목은 file:line 형태의 근거와 함께 노력, 신뢰도를 답니다. 같은 실행에서 일부 항목은 사유와 함께 기각되어, 다음 실행에서 같은 항목이 다시 올라오지 않도록 기록됩니다. 예를 들어 https_proxy 환경 변수를 SSRF로 의심한 보안 항목은 "표준 프록시 관례이며 모든 CLI가 따른다, 의도된 동작" 이라는 사유로 기각되었습니다. 위 표의 1번 항목을 골라 만든 결과가 앞서 링크한 예시 계획서로, 현재 코드 발췌와 정확한 단계, 저장소 자체의 테스트·린트 명령을 검증 게이트로 삼은 형태를 그대로 보여줍니다.

improve의 라이선스

improve는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

improve 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~