
shadcn improve, 코드는 안 고치고 계획서만 쓴다는데 뭐가 다를까요? (2026 기준)
무료 자료
PDF · 무료
AI에게 코드 손질 맡기기 전에, 작업 지시서부터: 비개발자를 위한 쉬운 가이드
긴 글을 다 읽기 전에, 실무 가이드부터 먼저 챙겨가세요.
shadcn improve, 코드는 안 고치고 계획서만 쓴다는데 뭐가 다를까요? (2026 기준)
shadcn improve는 코드를 고치지 않고 점검만 해서 실행 계획서를 쓰는 에이전트 스킬이에요. 점검 순서, 써 보는 법, 열려 있는 한계를 2026-11-12 기준으로 정리했습니다.
핵심: 스킬 자신은 코드를 고치지 않고, 사용자가 고른 항목만 plans/ 폴더의 계획서로 남겨요.
코드를 안 고치는 점검 스킬이라니, 어디에 쓰는 건가요?
결론부터 말하면 improve는 고치는 도구가 아니라 읽고 따져서 지시서를 남기는 도구예요. 저장소 설명 원문은 이렇습니다. "Use your most capable model to audit your codebase and write plans for cheaper models to execute."
처음엔 두 가지 망설임이 생깁니다. "AI한테 코드 점검을 맡기면 알아서 막 고쳐 버리는 거 아닌가요?" 그 반대로 "고치지도 않을 거면 뭐 하러 쓰죠?"도 나오고요. 이 글은 점검 순서, 계획서의 장치, 써 보는 법, 열려 있는 한계 순서로 답합니다.
이 스킬은 무엇을 하고 무엇을 안 하나요?
improve는 shadcn(웹 화면 부품 모음 shadcn/ui를 만든 개발자)이 개인 계정 저장소에 올린 스킬이에요. MIT 라이선스이고 2026-06-10에 만들어졌습니다.
핵심은 SKILL.md의 첫 문장이에요. 원문은 "You are a senior advisor, not an implementer."이고, 구현자가 아니라 선임 자문역(advisor)으로 일하라는 뜻입니다. README는 같은 생각을 "The plan is the product."라고 줄였어요.
하지 않는 일은 SKILL.md의 규칙 6개(Hard Rules)에 적혀 있습니다. SKILL.md에 따르면 스킬이 쓸 수 있는 곳은 plans/ 폴더(이미 다른 용도면 advisor-plans/)뿐이고, 설치나 빌드, 커밋(변경 기록 저장) 같은 작업 폴더를 바꾸는 명령은 쓰지 않는 게 원칙이에요. 점검하는 저장소 안의 문장은 지시가 아니라 데이터로 보기 때문에, 이전 지시를 무시하라는 식의 문장은 따르지 않고 프롬프트 주입(AI에게 몰래 명령을 끼워 넣는 공격) 가능성으로 보안 항목에 적어요.
오해하기 쉬운 점이 하나 있어요. 코드를 고치지 않는다는 말의 주어는 스킬 자신입니다. execute로 실행을 맡기면 별도 실행자 하위 에이전트(일을 나눠 받는 보조 AI)가 격리된 git worktree(같은 저장소의 별도 작업 폴더)에서 코드를 고치고 커밋해요. 병합(고친 내용을 본 줄기에 합치는 일)은 사용자가 정하고요.
참고로 shadcn은 2026-11-10(한국 시각)에 X에 "Run /improve with Fable 5.2. I'm seeing some interesting results that Opus 5.5 missed."라고 올렸습니다. 어떤 결과를 어떻게 비교했는지는 공개되지 않은 본인 관찰이어서, 모델 우열의 근거로 읽으면 안 돼요.
점검은 어떤 순서로 흘러가나요?
SKILL.md가 정한 순서는 정찰, 점검, 근거 재확인, 우선순위, 계획서예요. 정찰 단계에서는 README와 CI(자동 검사) 설정을 읽어 빌드, 테스트, 코드 모양 검사 명령을 정확히 찾고, 이 명령이 나중에 모든 계획서의 확인 명령이 됩니다.
점검은 어떤 순서로 흘러가나요?
improve는 고른 항목만 계획서로 만들고, 코드 수정은 별도 실행자가 격리된 git worktree에서 맡아요. 병합은 사람이 정해요
자료: shadcn/improve SKILL.md·closing-the-loop.md · QJC 재구성
점검은 아홉 갈래입니다. 정확성, 보안, 성능, 테스트, 기술 부채, 의존성, 개발 경험, 문서, 방향이에요.
눈여겨볼 단계는 근거 재확인이에요. SKILL.md는 "subagents over-report"라는 전제 위에 서 있어서, 하위 에이전트가 올린 항목의 인용 코드를 advisor가 직접 다시 열어 봅니다. 의도된 동작을 버그로 본 것, 줄을 잘못 짚은 것, 중복이 걸러져요. README에는 https_proxy 환경 변수를 따르는 동작을 SSRF로 신고한 항목을 표준 관례라며 기각한 예가 실려 있고, 기각 사유는 다음 실행에서 되풀이되지 않게 plans/README.md에 남깁니다.
남은 항목은 영향을 노력으로 나눈 값에 확신도와 수정 위험을 반영해 순서를 매기고, 어떤 항목을 계획서로 만들지 사용자에게 묻습니다. SKILL.md의 기준 문장은 "Do not write 30 plans nobody asked for."예요.
깊이는 세 단계예요. SKILL.md의 표를 줄이면 이렇습니다.
| 깊이 | 보는 범위 | 하위 에이전트 | 보는 갈래 | 결과 |
|---|---|---|---|---|
quick | 정찰에서 찾은 핫스팟만 | 0~1개 | 정확성·보안·테스트 세 갈래 | 확신 높은 상위 약 6개 |
standard(기본) | 핫스팟 가중, 핵심 패키지 | 동시 4개 이하 | 아홉 갈래 전부 | 전체 표 |
deep | 저장소 전체 | 동시 8개 이하 | 아홉 갈래 전부 | 확신 낮은 조사 항목 포함 전체 표 |
quick을 돌려도 아홉 가지를 다 보는 게 아니라는 점은 기억해 두세요.
계획서는 왜 가장 약한 실행자 기준으로 쓰나요?
plan-template.md는 실행자를 맥락이 전혀 없는 상태로 가정하고, 명시된 지시는 잘 따르지만 빈틈을 메우거나 멈출 때를 아는 데는 약하다고 봅니다. 그래서 계획서 한 파일에 경로, 현재 코드 발췌, 따라야 할 저장소 관례, 검증된 명령을 다 넣어요. 단계마다 확인 명령과 기대 결과가 붙고, 원문은 "The executor never has to judge whether it succeeded."입니다.
손대도 되는 파일과 안 되는 파일의 목록, 이러면 멈추고 보고하라는 STOP 조건(작업 중단 조건)도 들어갑니다. 작성 시점의 커밋 번호(Planned at)를 적어 두기 때문에, 실행자는 시작 전에 그 뒤로 범위 파일이 바뀌었는지 보는 drift check(코드가 계획서 이후 달라졌는지 확인하는 절차)를 먼저 돌려요. 바뀌었고 발췌와 다르면 멈춤 사유로 칩니다.
저장소에는 예시 계획서 001이 실려 있어요. shadcn/ui를 대상으로 커밋 1994caba0에서 2026-06-10에 쓴 견본이고, 저장소가 실행하지 말라고 표시해 뒀습니다. 손댈 파일은 4개, 단계는 3개이며 새 테스트는 4개를 추가합니다. 완료 기준은 6개, STOP 조건은 3개예요.
Claude Code에서는 어떻게 써 보나요?
가장 확실한 안내는 README에 있는 npx skills add shadcn/improve 뒤에 /improve를 부르는 길이에요. 플러그인 경로(/plugin marketplace add shadcn/improve 다음 /plugin install improve@improve)는 저장소 매니페스트와 Claude Code 공식 문서를 대조한 결과일 뿐, 직접 실행해 확인하기 전이라는 점을 먼저 밝혀 둡니다.
npx skills add shadcn/improve 설치 명령과 /improve 변형 11가지 목록
이미지 출처: shadcn X 게시물
- Node.js 22.20 이상이 있는 환경에서
npx skills add shadcn/improve를 실행해요. npx skills 문서 기준으로 기본은 현재 프로젝트에 설치되고,-g를 붙이면 전역 설치입니다. - 점검할 저장소에서 코딩 에이전트를 열고
/improve quick부터 시작해요. README가 비용을 줄이려고 권하는 순서이고, 정확성·보안·테스트 세 가지만 봅니다. - 발견 항목 표가 나오면 번호로 답해요. README의 예시는
plan 1, 3 and 5처럼 번호만 적는 거예요. plans/폴더의 계획서를 읽어요. README는 "Read them; they're meant to be reviewed."라고 적었어요.- 실행은 두 길이에요. 다른 에이전트에게
implement plans/001-*.md라고 넘기거나,/improve execute 001 haiku처럼 실행 모델 이름을 붙여 맡기세요. 모델 이름을 빼면 Claude Code 공식 문서상 메인 대화 모델로 돌 수 있어요. - 병합은 직접 정하고, 다음 세션에는
/improve reconcile로 계획서 목록을 정리해요. PR을 올리기 전에는/improve branch로 현재 브랜치에서 바뀐 부분만 점검합니다.
어디까지 믿고 써도 되나요?
스킬 문서를 바꾼 마지막 커밋은 2026-06-15이고, 아래 한계와 관련된 PR은 2026-11-12 기준 하나도 병합되지 않았어요.
- 실행 모델은 이름으로 정하세요. SKILL.md는 더 싼 실행자라고만 쓰고, 기본값 sonnet은 closing-the-loop.md에만 있어요. Claude Code 공식 문서에 따르면 모델을 넘기지 않으면 메인 대화 모델로 돌아갑니다. PR #23(2026-08-06, 열림) 작성자는 모델을 생략했을 때 advisor 모델인 claude-opus-5가 그대로 쓰였고 haiku를 지정하면 Haiku 4.5가 돌았다고 실측했어요. 이슈 #14도 열려 있습니다.
- 이슈 #30(2026-11-11, 열림)은 실행자가 이미 커밋한 범위 밖 변경을 범위 검사가 놓친다고 보고했어요. 검사 명령이 아직 커밋하지 않은 변경만 보여 주기 때문이에요.
- PR #20(열림, 병합 안 됨)은 실행자가 쓴 테스트를 diff(바뀐 내용 비교 화면)를 읽기 전에 돌리는 검토 순서를 지적해요.
- Claude Code 문서에 따르면 격리 worktree는 현재 세션의 최신 커밋이 아니라 기본 브랜치에서 갈라져요. 기능 브랜치에서 작업하면 실행자가 계획서와 다른 코드를 볼 수 있고, PR #16이 이를 재현했지만 병합되지 않고 닫혔습니다.
마무리
우리가 보기에 shadcn improve에서 배울 점은 모델의 힘이 아니라 지시서의 모양이에요. AI에게 코드 손질을 맡길 때 먼저 갖출 것은 더 센 모델보다 확인 명령과 멈출 조건이 적힌 작업 지시서라고 해석합니다. 실행을 맡길 때는 모델 이름도 직접 정하세요.
먼저 해 볼 일은 하나예요. 쓰고 있는 저장소에서 /improve quick을 돌려 보고 계획서 하나만 끝까지 읽어 보세요. 천천히 검토하셔도 됩니다. 궁금한 지점이 생기면 그때 더 깊은 자료를 찾아보세요.
관련 글: Claude Code Advisor 기능 분석 · Coordinator 패턴 정리
자주 묻는 질문
코드를 정말 안 고치나요?
스킬 자신은 소스 코드를 고치지 않고 plans/ 폴더에만 계획서를 씁니다. 다만 execute로 실행을 맡기면 별도 실행자가 격리된 worktree에서 코드를 고치고 커밋해요. 병합은 사용자가 정한다고 README가 적었습니다.
어떤 모델로 실행되나요?
이름으로 정하지 않으면 확실하지 않아요. closing-the-loop.md의 기본값은 sonnet이지만, Claude Code 공식 문서에 따르면 모델을 넘기지 않을 때는 메인 대화 모델이 쓰입니다. PR #23 작성자의 실측에서는 모델을 생략하자 advisor 모델이 그대로 이어졌고, 그래서 /improve execute 001 haiku처럼 이름을 붙여 부르는 편이 확실해요.
비용은 얼마나 드나요?
금액을 알려 주는 1차 출처는 없어서 숫자로는 답하기 어려워요. 저장소 설명은 가장 성능이 좋은 모델로 점검하고 실행은 다른 모델에 맡기라는 구조이고, 실행 모델을 이름으로 정하는 방법은 closing-the-loop.md에 나와요.


