@kood/claude-code 0.2.4 → 0.3.0

package/templates/.claude/commands/docs-refactor.md

@@ -1,168 +1,455 @@
 ---
-description: Claude Code 문서 리팩토링 가이드. 기존 CLAUDE.md, SKILL.md 개선 시 사용.
+description: 기존 Claude Code 문서 개선
+allowed-tools: Read, Edit, Glob, Grep
+argument-hint: <문서 경로>
 ---
 
-# Docs Refactor
+# Docs Refactor Command
 
-기존 Claude Code 문서를 베스트 프랙티스에 맞게 개선하는 가이드.
+> 기존 CLAUDE.md, SKILL.md, COMMAND.md 문서를 Anthropic 가이드라인에 맞게 개선
 
-## 리팩토링 필요 신호
+<purpose>
 
-| 신호 | 문제 | 우선순위 |
-|------|------|---------|
-| 200줄+ CLAUDE.md | 컨텍스트 과부하 | 높음 |
-| 500줄+ SKILL.md | 로딩 지연, 품질 저하 | 높음 |
-| Claude가 지침 무시 | 과도한 지침 (150+개) | 높음 |
-| 중첩 참조 (A→B→C) | 불완전한 파일 읽기 | 중간 |
-| 코드 스타일 지침 | 린터 역할 강요 | 중간 |
-| 시간 의존 정보 | 오래된 지침 | 낮음 |
+**목표:** 토큰 효율 50% 개선, 명확성 향상, 유지보수성 강화
 
-## 분석 워크플로우
+</purpose>
 
-### 1단계: Subagent로 현황 분석
+---
+
+<trigger_conditions>
+
+| 상황 | 리팩토링 필요 |
+|------|--------------|
+| **토큰 과다** | 파일 500줄 초과 |
+| **가독성 저하** | XML 태그 미사용, 구조 불명확 |
+| **중복 발견** | 동일 내용 2회 이상 반복 |
+| **설명 과다** | 코드 예시보다 설명 많음 |
+| **@imports 미사용** | 공통 규칙 반복 |
+| **모호한 지시** | "적절히", "필요시" 등 |
+| **부정형 과다** | Don't, Never, Avoid 위주 |
+
+</trigger_conditions>
+
+---
+
+<forbidden>
+
+| 분류 | 금지 사항 |
+|------|----------|
+| **구조** | XML 태그 제거, 단순 삭제 |
+| **내용** | 핵심 정보 손실, 버전 정보 제거 |
+| **표현** | 모호한 지시 유지, 부정형 → 부정형 |
+| **스타일** | 일관성 없는 마커 |
+
+</forbidden>
+
+---
+
+<required>
+
+| 분류 | 필수 작업 |
+|------|----------|
+| **분석** | 전체 읽기 → 토큰 확인 → 중복 식별 |
+| **구조화** | XML 태그 적용 |
+| **압축** | 표 형식 변환, 설명 제거 |
+| **예시화** | 설명 → 코드 예시 |
+| **검증** | Before/After 50% 감소 확인 |
+
+</required>
+
+---
+
+<refactoring_patterns>
+
+### Pattern 1: 장황한 설명 → 표 형식
+
+**절약:** 60-70%
+
+```markdown
+❌ Before (80 토큰):
+파일을 읽을 때는 Read 도구를 사용하세요. 파일을 수정할 때는 Edit...
+
+✅ After (25 토큰):
+| 작업 | 도구 |
+|------|------|
+| 읽기 | Read |
+| 수정 | Edit |
+| 생성 | Write |
+```
 
+---
+
+### Pattern 2: 중복 내용 → @imports
+
+**절약:** 70-80%
+
+```markdown
+❌ Before (각 파일 150 토큰):
+Git 커밋: "Co-Authored-By:" 금지, 한 줄, 이모지 금지...
+(CLAUDE.md, SKILL.md에 동일 내용 반복)
+
+✅ After (각 파일 10 토큰):
+# CLAUDE.md
+@instructions/git-rules.md
+
+# git-rules.md (60 토큰, 공유)
+<git_commit>
+| 규칙 | 설명 |
+|------|------|
+| **형식** | `<prefix>: <설명>` |
+| **금지** | 이모지, "Co-Authored-By:" |
+</git_commit>
 ```
-Explore agent에게:
-"현재 CLAUDE.md/SKILL.md를 분석하고 보고해줘:
-- 총 줄 수
-- 섹션별 줄 수
-- 지침 개수 (명령형 문장)
-- 중첩 참조 깊이
-- 린터 역할 지침 여부
-- 시간 의존 정보 여부"
+
+---
+
+### Pattern 3: XML 태그 미사용 → 구조화
+
+**절약:** 30-40%
+
+```markdown
+❌ Before (120 토큰):
+절대 하지 말 것: any 타입, 불필요한 추상화
+반드시 할 것: 명시적 return type, const 함수
+
+✅ After (75 토큰):
+<forbidden>
+| 분류 | 금지 |
+|------|------|
+| **타입** | any |
+| **구조** | 불필요한 추상화 |
+</forbidden>
+
+<required>
+| 분류 | 필수 |
+|------|------|
+| **타입** | 명시적 return type |
+| **선언** | const 함수 |
+</required>
 ```
 
-### 2단계: 개선 계획 수립
+---
+
+### Pattern 4: 설명 과다 → 코드 예시
+
+**절약:** 50-60%
 
+```markdown
+❌ Before (180 토큰):
+Server Function을 만들 때는 createServerFn을 사용합니다.
+method를 지정하고, 인증이 필요하면 middleware를...
+
+✅ After (65 토큰):
+```typescript
+// POST + Validation + Auth
+export const createUser = createServerFn({ method: 'POST' })
+  .middleware([authMiddleware])
+  .inputValidator(schema)
+  .handler(async ({ data }) => ...)
 ```
-Plan agent에게:
-"분석 결과를 바탕으로 리팩토링 계획 수립:
-- 삭제할 내용
-- 분리할 내용 (references/)
-- 병합할 섹션
-- 추가할 내용"
 ```
 
-### 3단계: 리팩토링 실행
+---
+
+### Pattern 5: 부정형 → 긍정형
+
+**절약:** 20-30%
+
+```markdown
+❌ Before (100 토큰):
+Don't use any type
+Don't create unnecessary abstractions
+Don't skip validation
+
+✅ After (70 토큰):
+<required>
+| 분류 | 필수 |
+|------|------|
+| **타입** | 명시적 타입 (unknown) |
+| **구조** | 직접적 코드 |
+| **검증** | inputValidator 사용 |
+</required>
+```
+
+</refactoring_patterns>
 
-메인 에이전트가 계획 기반으로 문서 수정.
+---
 
-## 안티패턴 → 개선 패턴
+<document_type_strategies>
 
-### 길이 문제
+| 문서 유형 | 최우선 작업 | 절약 효과 |
+|----------|------------|----------|
+| **CLAUDE.md** | @imports 분리 → tech_stack 표 형식 → quick_patterns 코드만 | 60-70% |
+| **SKILL.md** | trigger_conditions 표 → workflow 코드 블록 → 설명 제거 | 65-75% |
+| **COMMAND.md** | purpose 1-2문장 → workflow bash 코드 → examples ✅/❌ | 55-65% |
 
-| Before | After |
-|--------|-------|
-| 300줄 CLAUDE.md | 60-200줄 + docs/ 분리 |
-| 800줄 SKILL.md | 500줄 이하 + references/ 분리 |
+**공통 체크리스트:**
+- [ ] XML 태그로 모든 섹션 구분
+- [ ] 표 형식 최대 활용
+- [ ] 코드 예시 중심
+- [ ] 라이브러리 버전 명시
+- [ ] @imports로 중복 제거
 
-**분리 기준:**
-- 모든 세션에 필요 → 메인 파일
-- 특정 작업에만 필요 → 참조 파일
+</document_type_strategies>
 
-### 구조 문제
+---
 
-| Before | After |
-|--------|-------|
-| 긴 서술형 문단 | 불릿 포인트 + 짧은 문장 |
-| 중첩 참조 (A→B→C) | 1단계 깊이 (A→B) |
-| 목차 없는 100줄+ 파일 | 상단에 목차 추가 |
+<token_optimization>
 
-### 내용 문제
+| 기법 | Before → After | 절약 |
+|------|----------------|------|
+| **단어 최적화** | "사용해야 합니다" → "사용" | 80% |
+| **구조 압축** | 리스트 → 표 형식 | 40% |
+| **반복 제거** | 각 파일 반복 → @imports | 70% |
+| **코드 우선** | 설명 + 코드 → 코드만 | 50% |
+| **공백 제거** | 빈 줄 최소화 | 10% |
+| **예시 통합** | 개별 예시 → 통합 코드 블록 | 60% |
 
-| Before | After |
-|--------|-------|
-| 코드 스타일 가이드 | 삭제 (Biome/ESLint 사용) |
-| Claude가 아는 설명 | 삭제 |
-| 시간 의존 정보 | "old patterns" 섹션으로 이동 |
-| 너무 많은 옵션 | 기본값 + 대안 1개 |
+**체크리스트:**
+- [ ] "~해야 합니다" → 필수
+- [ ] "~하지 마세요" → 금지
+- [ ] 반복 표현 → 표
+- [ ] 설명 + 코드 → 코드만
+- [ ] @imports 중복 제거
 
-**삭제 예시:**
+</token_optimization>
+
+---
+
+<workflow>
+
+<step number="1">
+<action>문서 분석</action>
+<checklist>
+- [ ] 전체 읽기 (Read)
+- [ ] 토큰 수 추정 (`wc -w`)
+- [ ] 문서 유형 확인
+- [ ] 중복 내용 표시
+</checklist>
+</step>
+
+<step number="2">
+<action>리팩토링 계획</action>
+<priority>
+1. 중복 → @imports 분리
+2. XML 태그 구조화
+3. 표 형식 변환
+4. 코드 중심 전환
+5. 긍정형 변환
+</priority>
+</step>
+
+<step number="3">
+<action>리팩토링 실행</action>
+<guidelines>
+- Pattern 1-5 적용
+- 문서 유형별 전략 사용
+- 토큰 최적화 기법 적용
+</guidelines>
+</step>
+
+<step number="4">
+<action>검증</action>
+<validation>
+- [ ] 토큰 50% 감소 확인
+- [ ] 핵심 정보 보존 확인
+- [ ] XML 태그 중첩 확인
+- [ ] 코드 블록 짝수 확인
+- [ ] 부정형 5개 미만
+</validation>
+</step>
+
+</workflow>
+
+---
+
+<examples>
+
+### CLAUDE.md 리팩토링 (TanStack Start)
+
+**Before (650 토큰):**
 ```markdown
-# Before - 불필요한 설명
-PDF (Portable Document Format)는 Adobe에서 개발한
-문서 형식으로, 텍스트와 이미지를 포함할 수 있습니다...
+# Project Guidelines
+
+이 프로젝트에서는 TanStack Start를 사용합니다...
+Server Function을 만들 때는 createServerFn을 사용해야 합니다...
+절대로 any 타입을 사용하지 마세요...
 
-# After - 핵심만
-PDF 텍스트 추출: `pdfplumber.open("file.pdf")`
+Git 커밋 시에는 반드시 다음 규칙을 따라야 합니다:
+- 한 줄 커밋 메시지만 사용
+- 이모지 사용 금지...
+
+TypeScript는 5.x 버전을 사용하고...
 ```
 
-### Description 문제
+**After (280 토큰):**
+```markdown
+# CLAUDE.md - TanStack Start Project
+
+<instructions>
+@.claude/instructions/git-rules.md
+@docs/library/tanstack-start/index.md
+@docs/library/prisma/index.md
+@docs/library/zod/index.md
+</instructions>
 
-| Before | After |
-|--------|-------|
-| `description: 문서 처리` | `description: PDF 텍스트/표 추출. PDF 작업 시 사용.` |
-| 1인칭/2인칭 | 3인칭 작성 |
-| 트리거 없음 | 구체적 트리거 포함 |
+---
 
-## 분리 전략
+<forbidden>
+| 분류 | 금지 |
+|------|------|
+| **Server Function** | handler 내부 수동 검증/인증 |
+| **타입** | any (unknown 사용) |
+</forbidden>
 
-### 참조 파일로 분리할 내용
+---
 
-| 내용 | 분리 위치 |
-|------|----------|
-| API 상세 문서 | `references/api.md` |
-| 스키마 정의 | `references/schema.md` |
-| 예시 모음 | `references/examples.md` |
-| 도메인별 가이드 | `references/{domain}.md` |
+<required>
+| 분류 | 필수 |
+|------|------|
+| **Server Function** | POST/PUT → inputValidator + middleware |
+| **타입** | 명시적 return type |
+</required>
 
-### 분리 후 메인 파일 참조
+---
 
-```markdown
-## API 사용
+<tech_stack>
+| 기술 | 버전 | 주의 |
+|------|------|------|
+| TanStack Start | 최신 | File-based routing |
+| Prisma | 7.x | prisma-client, output 필수 |
+| Zod | 4.x | z.email(), z.url() |
+</tech_stack>
 
-기본 호출: `api.call(params)`
+---
 
-**상세 API 문서**: [references/api.md](references/api.md)
+<quick_patterns>
+```typescript
+// Server Function
+export const createUser = createServerFn({ method: 'POST' })
+  .middleware([authMiddleware])
+  .inputValidator(schema)
+  .handler(async ({ data }) => ...)
+
+// Zod v4
+const schema = z.object({
+  email: z.email(),
+  website: z.url().optional(),
+})
 ```
+</quick_patterns>
+```
+
+**개선 효과:** 650 → 280 토큰 (57% 감소)
+
+</examples>
 
-## Subagent 활용
+---
+
+<common_mistakes>
 
-| 단계 | Agent | 작업 |
-|------|-------|------|
-| 분석 | Explore | 현황 파악, 문제점 식별 |
-| 계획 | Plan | 리팩토링 전략 수립 |
-| 검증 | Explore | 개선 결과 확인 |
+### 실수 1: 핵심 정보 손실
 
-### 검증 프롬프트
+```markdown
+❌ After (정보 손실):
+Prisma 사용
 
+✅ After (정보 보존):
+| 기술 | 버전 | 필수 설정 |
+|------|------|----------|
+| Prisma | 7.x | prisma-client, output |
 ```
-Explore agent에게:
-"리팩토링된 문서 검증:
-- 줄 수 목표 달성?
-- 지침 개수 150개 이하?
-- 중첩 참조 1단계?
-- 필수 정보 누락 없음?"
+
+---
+
+### 실수 2: XML 태그 불일치
+
+```markdown
+❌ 불일치:
+<forbidden>
+...
+</required>  ← 잘못됨
+
+✅ 일치:
+<forbidden>
+...
+</forbidden>
+```
+
+---
+
+### 실수 3: 버전 정보 누락
+
+```markdown
+❌ 버전 없음:
+Zod, Prisma 사용
+
+✅ 버전 명시:
+| 기술 | 버전 |
+|------|------|
+| Zod | 4.x |
+| Prisma | 7.x |
 ```
 
+</common_mistakes>
+
+---
+
+<validation>
+
+## 검증 방법
+
+| 항목 | 기준 | 명령어 |
+|------|------|--------|
+| **토큰 효율** | 50% 감소 | `wc -w file.md` |
+| **XML 태그** | 올바른 중첩 | `grep -o '<[^>]*>' file.md` |
+| **코드 블록** | 짝수 개 | `grep -c '\`\`\`' file.md` |
+| **부정형** | < 5개 | `grep -c "Don't\|Never" file.md` |
+
 ## 체크리스트
 
-### 분석 단계
+**구조:**
+- [ ] 모든 섹션 XML 태그
+- [ ] forbidden/required 분리
 
-- [ ] Subagent로 현황 분석 완료
-- [ ] 문제점 목록 작성
-- [ ] 개선 우선순위 결정
+**내용:**
+- [ ] 토큰 50% 감소
+- [ ] 핵심 정보 보존
+- [ ] 버전 명시
 
-### 리팩토링 단계
+**예시:**
+- [ ] 코드 블록 짝수
+- [ ] ✅/❌ 마커
+- [ ] 실행 가능한 코드
 
-- [ ] 불필요한 설명 삭제
-- [ ] 코드 스타일 지침 삭제
-- [ ] 긴 내용 참조 파일로 분리
-- [ ] 중첩 참조 1단계로 평탄화
-- [ ] 100줄+ 파일에 목차 추가
-- [ ] Description 개선 (3인칭, 트리거)
+**표현:**
+- [ ] 부정형 < 5
+- [ ] 긍정형 지시
 
-### 검증 단계
+**최적화:**
+- [ ] @imports 중복 제거
+- [ ] 표 형식 압축
+- [ ] 코드 중심
 
-- [ ] CLAUDE.md 60-200줄
-- [ ] SKILL.md 500줄 이하
-- [ ] 지침 개수 150개 이하
-- [ ] 참조 1단계 깊이
-- [ ] 필수 정보 유지 확인
-- [ ] 테스트 완료
+</validation>
 
-## 참조
+---
+
+<best_practices>
+
+| 원칙 | 방법 | 효과 |
+|------|------|------|
+| **정보 보존 우선** | 토큰보다 정보 | 신뢰성 |
+| **코드 중심** | 설명 → 예시 | 명확성 |
+| **점진적 개선** | 한 번에 하나씩 | 안정성 |
+| **측정 기반** | Before/After | 객관성 |
+
+**문서별 팁:**
+
+| 문서 | 핵심 작업 |
+|------|----------|
+| **CLAUDE.md** | @imports 최대 활용, quick_patterns 코드만 |
+| **SKILL.md** | trigger_conditions 명확, 설명 제거 |
+| **COMMAND.md** | workflow 실행 가능 코드, examples ✅/❌ |
 
-- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
-- [Using CLAUDE.MD files](https://claude.com/blog/using-claude-md-files)
-- [Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+</best_practices>