improve

# improve — 강력한 모델로 감사하고 저비용 모델로 실행 `improve`는 모든 코드베이스를 감사하고 다른 에이전트가 실행할 구현 계획을 작성하는 에이전트 스킬(Agent Skills 형식)입니다. 전제는 다음과 같습니다. 지능이 집적되는 부분, 즉 코드베이스 이해, 수행 가치 판단, 스펙 작성에 가장 강력한 모델을 투입하고 실행은 저비용 모델에 맡기는 것입니다. 이 스킬은 스스로 아무것도 구현하지 않습니다. 계획이 곧 산출물입니다. ``` you → /improve (비싼 모델, 조언) plans/ → 001-fix-n-plus-one.md (자체 포함 스펙) other agent → 구현, 테스트, 출시 (저비용 모델, 실행) ``` ## 설치 ```bash npx skills add shadcn/improve ``` Agent Skills 형식을 지원하는 모든 에이전트에서 작동합니다. 계획은 일반 마크다운이므로 어떤 에이전트나 인간이든 사용할 수 있습니다. ## 명령 - `/improve` — 전체 감사 → 우선순위 발견 사항 → 계획 - `/improve quick` — 저비용 통과: 핫스팟과 주요 발견 사항만 - `/improve deep` — 전체 패키지와 모든 범주를 대상으로 철저히 - `/improve security` — 보안 중심 감사 (성능, 테스트, 버그 등도 가능) - `/improve branch` — 현재 브랜치가 변경한 부분만 감사 - `/improve next` — 기능 제안, 프로젝트 방향성 - `/improve plan <설명>` — 감사 생략, 특정 항목만 스펙 작성 - `/improve review-plan <파일>` — 기존 계획을 비판적으로 검토하고 다듬기 - `/improve execute <계획>` — 저비용 실행자를 파견하고 작업 검토 - `/improve reconcile` — 백로그 갱신: 검증, 차단 해제, 정리 - `--issues` — 계획을 GitHub 이슈로도 공개 ## 일반적인 첫 실행 1. 저장소에서 에이전트를 열고 `/improve`(또는 비용을 줄이려면 `/improve quick`)를 실행합니다. 2. 저장소를 매핑하고 감사한 후 발견 사항 표를 반환합니다. 계획으로 만들고 싶은 항목(예: "1, 3, 5번 계획")을 답변합니다. 3. 계획은 `plans/` 디렉터리에 각각 하나의 파일로 저장되며, 권장 순서가 포함된 인덱스도 생성됩니다. 검토를 위한 것입니다. 4. 계획을 다른 에이전트에 전달하거나("plans/001-*.md를 구현") 스킬이 직접 실행하게 할 수 있습니다: `/improve execute 001`은 격리된 작업 트리에서 저비용 모델을 파견하고, 계획에 대한 diff를 검토한 후 판정을 보고합니다. 병합은 사용자가 결정합니다. 5. 다음 세션에서 `/improve reconcile`로 백로그를 정리합니다: 반영된 사항 검증, 표류한 사항 갱신, 막힌 사항 해소. PR 전에 `/improve branch`로 동일한 프로세스를 브랜치가 변경한 부분으로만 한정할 수 있습니다. ## 작동 방식 - **정찰.** 저장소를 매핑합니다: 스택, 규칙, 정확한 빌드/테스트/린트 명령은 모든 계획의 검증 관문이 됩니다. 또한 ADR(`docs/adr/`), PRD, `CONTEXT.md`, `DESIGN.md`, `PRODUCT.md` 등 의도 및 설계 문서가 있으면 흡수하여, 결정된 트레이드오프를 다시 지적하지 않고, 방향성 제안이 명시된 제품 의도에 근거하며, 계획이 저장소 고유의 용어를 사용하도록 합니다. - **감사.** 9개 범주에 걸쳐 병렬 서브에이전트를 파견합니다: 정확성, 보안, 성능, 테스트 커버리지, 기술 부채, 의존성 및 마이그레이션, 개발자 경험, 문서, 방향성(기능 제안은 저장소 자체에서 증거를 인용해야 함). 모든 발견 사항은 `file:line` 증거, 영향도, 노력, 신뢰도를 포함합니다. - **검증.** 서브에이전트가 과다 보고하므로, 어드바이저는 모든 인용 위치를 다시 읽고, 오탐은 제거하고 잘못된 귀속은 수정하며 거부 사유를 기록합니다. - **우선순위.** 발견 사항은 영향도 ÷ 노력(신뢰도 가중) 기준의 지렛대 순으로 표에 정리됩니다. 계획으로 만들 항목을 선택합니다. - **계획.** 선택된 각 발견 사항에 대해 `plans/`에 파일 하나씩, 인덱스, 우선순위, 의존성 그래프가 생성됩니다. ## 계획을 실행 가능하게 하는 요소 계획은 가장 약한 실행자를 대상으로 합니다 — 어드바이저 세션을 본 적이 없고 훨씬 작을 수 있는 모델 말입니다. 이를 가능하게 하는 세 가지 속성이 있습니다: - **자체 포함.** 모든 컨텍스트가 인라인 처리됩니다: 정확한 파일 경로, 현재 상태 코드 발췌, 예시 파일이 포함된 저장소 규칙, 검증된 명령. '위에서 논의한 대로'는 없습니다. - **검증 관문.** 모든 단계는 명령과 기대 출력으로 끝납니다. 완료 기준은 기계적으로 확인 가능하므로 실행자가 성공 여부를 판단할 필요가 없습니다. - **명확한 경계.** 현실이 계획과 일치하지 않을 때 작은 모델이 즉흥적으로 대처하는 대신, 명시적인 범위 밖 목록과 중지 조건('X면 중단하고 보고')을 제공합니다. 각 계획은 작성 기준이 된 git 커밋을 새겨 넣으므로, 실행자는 작업 시작 전에 기계적 드리프트 검사를 실행할 수 있습니다. ## 루프 닫기 - **`execute <plan>`** — 격리된 git 작업 트리에서 저비용 실행자 서브에이전트를 생성하고 계획을 전달한 다음, 테크 리드처럼 결과를 검토합니다: 모든 완료 기준을 재실행하고, 범위 준수를 확인하고, 의도를 기준으로 diff를 읽습니다. 판정: 승인(병합은 사용자 결정), 수정 요청(최대 2회), 또는 계획을 차단하고 개선. - **`reconcile`** — 이후 발생한 일을 처리합니다: 완료(DONE) 계획이 여전히 유효한지 확인하고, 차단(BLOCKED)된 계획을 조사해 장애물을 우회하도록 다시 쓰고, 표류한 계획을 갱신하며, 독립적으로 수정된 발견 사항을 제거합니다. - **`--issues`** — 동일한 자체 포함 본문을 가진 계획을 GitHub 이슈로 공개하여, 작업이 이미 있는 곳에서 어떤 에이전트나 인간이든 집어 들 수 있게 합니다. ## 절대 규칙 - 소스 코드 자체를 절대 수정하지 않습니다. 유일한 쓰기는 `plans/`에만 있습니다. 실행자는 일회용 작업 트리에서만 편집하며, 병합은 항상 사용자가 결정합니다. - 작업 트리를 변경하는 명령을 절대 실행하지 않습니다 — 읽기, 검색, 읽기 전용 분석만 허용됩니다. - 비밀 값을 절대 재현하지 않습니다. 위치와 자격 증명 유형만 표시하고 항상 교체를 권장합니다. - 구현을 요청받으면 거절하고 계획을 가리키거나(또는 `execute`를 제안합니다). ## 라이선스 MIT © shadcn