TL;DR

이 레포는 저장소 전반을 감사해 증거 기반 발견을 표로 정리하고 선택된 항목마다 실행 가능한 마크다운 계획을 작성하는 Agent Skill이다. 동작 방식은 가장 능력 높은 모델을 감사·판단·계획 작성에 할당하고 각 단계에 기계적으로 확인 가능한 검증 게이트와 중지 조건을 넣어 더 저렴한 실행자가 계획을 격리된 워크트리에서 안전하게 수행하도록 만드는 구조다. 결과적으로 판단 비용을 고성능 모델로 한정하면서 구현 비용을 저렴한 실행자에게 위임해 전체 작업 비용과 위험을 낮추되 소스 코드에 직접 쓰지 않고 병합은 여전히 인간이 최종 결정하도록 설계되어 있다.

주요 기능

• 저장소를 매핑해 스택, 관습, 빌드/테스트/린트 명령을 추출한다.
• 병렬 서브에이전트로 정확도·보안·성능·테스트·문서성을 검사해 파일:라인 증거와 메타데이터를 생성한다.
• 선택된 발견 항목별로 self-contained한 마크다운 계획서를 plans/에 작성해 실행자가 기계적으로 따를 수 있게 만든다.
• 격리된 Git 워크트리에서 저비용 실행자를 실행하고 계획의 검증 게이트를 확인해 결과를 보고한다.
• 계획의 상태를 재검증하고 블록된 항목을 재작성하거나 드리프트를 갱신해 백로그를 유지관리한다.

어떻게 동작하는가

저장소 매핑 단계는 스택과 관습, 그리고 정확한 빌드·테스트·린트 명령을 추출해 각 계획의 검증 게이트로 사용한다. 감사 단계는 아홉 개 카테고리(정확성·보안·성능·테스트 커버리지·기술 부채·의존성·DX·문서·방향)를 병렬 서브에이전트로 검사해 파일:라인 근거와 영향·노력·신뢰도를 산출한다. 계획 작성은 선택된 발견에 대해 모든 맥락을 인라인하고 단계별 명령과 기대 출력, STOP 조건을 포함하는 self-contained 마크다운을 생성해 작은 실행자가 판별 대신 기계적으로 수행하도록 만든다.

해결 문제

프로젝트에서 무엇을 고쳐야 하고 어떤 작업이 가장 레버리지가 큰지 판단하는 데 드는 고비용 판단 작업을 줄인다. 가장 성숙한 모델을 판단과 설계에 집중시키고 구현·테스트·커밋 생성 같은 반복적·기계적인 작업은 더 저렴한 실행자에게 위임해 전체 비용을 낮춘다. 또한 각 계획에 검증 게이트와 중지 조건을 포함해 작은 모델이 임의로 불필요한 변경을 하지 않도록 위험을 통제한다.

차별점

• 계획을 self-contained하게 작성해 파일 경로·현재 코드 발췌·검증 명령을 모두 인라인하므로 실행자가 외부 컨텍스트를 필요로 하지 않는다.
• 모든 단계에 검증 게이트와 기대 출력을 포함해 수행 결과를 기계적으로 확인할 수 있게 설계되어 작은 모델의 결정 여지를 제거한다.
• 실행은 격리된 disposable worktree에서 이루어지며 원본 브랜치에는 직접 쓰지 않으므로 실험과 되돌림이 안전하게 수행된다.

사용 사례

• 오픈소스나 내부 코드베이스를 전체적으로 스캔해 기술 부채와 보안·성능 이슈를 정량화하고 우선순위화할 때 사용한다.
• 브랜치 단위로 변경 범위만 감사해 PR 전후의 위험을 줄이고 병합 전 확인을 자동화할 때 적용한다.
• 작은 실행 모델을 이용해 반복적 수정 작업을 자동화하되 인간 리뷰어가 최종 병합 결정을 유지하도록 워크플로를 구성할 때 유용하다.

시작하기

Agent Skills 형식을 지원하는 에이전트 환경에서 npx skills add shadcn/improve 명령으로 스킬을 추가하면 된다. 추가 후 에이전트 내에서 /improve 또는 /improve quick 같은 명령을 실행하면 저장소 매핑→발견 표 생성→선택 항목을 plans/에 작성하는 기본 플로우를 체험할 수 있다. 계획을 생성한 뒤에는 /improve execute <plan>으로 저비용 실행자를 격리된 worktree에서 돌리고 검증 게이트를 다시 실행해 결과를 확인하면 된다.

요구사항

• Agent Skills 형식을 지원하는 에이전트 환경이 필요하다.
• npx를 실행할 수 있는 Node.js/npm 런타임이 있어야 하며 설치 명령은 npx skills add shadcn/improve 이다.
• Git 저장소 접근 권한과 읽기 가능한 코드베이스가 필요하며 실행자는 disposable worktree를 생성할 수 있어야 한다.