@kood/claude-code 0.2.4 → 0.3.0

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

@@ -1,239 +1,480 @@
 ---
-description: Claude Code 문서 작성 가이드. CLAUDE.md, SKILL.md 등 효과적인 문서 작성 시 사용.
+description: Claude Code 문서 작성 가이드
+allowed-tools: Read, Write, Glob, Grep
+argument-hint: <문서 유형: CLAUDE.md | SKILL.md | COMMAND.md>
 ---
 
-# Docs Creator
+# Docs Creator Command
 
-Claude Code 문서 작성 베스트 프랙티스 가이드.
+> Claude Code 문서 (CLAUDE.md, SKILL.md, COMMAND.md)를 Anthropic 가이드라인에 따라 효과적으로 작성
 
-## 핵심 원칙
+<purpose>
 
-| 원칙 | 설명 |
-|------|------|
-| **간결함** | 컨텍스트 윈도우는 공공재. 모든 토큰이 비용 |
-| **점진적 공개** | 핵심만 메인 파일에, 상세는 참조 파일로 분리 |
-| **보편적 적용** | 모든 세션에 필요한 정보만 포함 |
+**목표:** 고밀도, 실행 가능한, 유지보수 가능한 문서 작성
+
+</purpose>
+
+---
+
+<trigger_conditions>
+
+| 상황 | 작성 필요 |
+|------|----------|
+| **새 프로젝트** | CLAUDE.md 생성 |
+| **새 스킬** | SKILL.md 생성 |
+| **새 커맨드** | COMMAND.md 생성 |
+| **문서 부재** | 프로젝트 규칙 문서화 |
+| **지식 공유** | 팀 온보딩 가이드 |
+
+</trigger_conditions>
 
-## 문서 유형별 가이드
+---
+
+<forbidden>
 
-| 문서 | 권장 길이 | 용도 |
-|------|----------|------|
-| CLAUDE.md | 60-200줄 | 프로젝트 전역 설정, 컨벤션 |
-| SKILL.md | 500줄 이하 | 특화 워크플로우, 도구 사용법 |
-| references/ | 무제한 | 상세 API 문서, 스키마 등 |
+| 분류 | 금지 사항 |
+|------|----------|
+| **설명** | 장황한 설명, 불필요한 텍스트, 중복 정보 |
+| **구조** | XML 태그 없는 복잡 구조, 모호한 지시 |
+| **표현** | 부정형 지시 (Don't X → Do Y) |
+| **복잡도** | 복잡한 조건문, 모든 엣지 케이스 |
+| **강조** | 과도한 강조 (CRITICAL, MUST 남발) |
 
-**지침 개수 한계**: 150-200개 (Claude Code 자체 ~50개 사용)
+</forbidden>
+
+---
 
-## 구조 템플릿
+<required>
 
-### CLAUDE.md
+| 분류 | 필수 사항 |
+|------|----------|
+| **구조** | XML 태그 섹션 구분, 명확한 계층 |
+| **표현** | 표 형식 압축, ✅/❌ 마커 |
+| **예시** | 코드/예시 중심, 복사 가능 패턴 |
+| **로딩** | @imports로 just-in-time |
+| **지시** | 명시적 지시, 긍정형 표현 |
+| **버전** | 라이브러리 버전 명시 |
+
+</required>
+
+---
 
+<document_types>
+
+## CLAUDE.md - 프로젝트 규칙
+
+**용도:** 프로젝트별 코딩 규칙, 금지/필수 사항, 빠른 참조
+
+**구조:**
 ```markdown
-# 프로젝트명
+# CLAUDE.md - [프로젝트명]
 
-## 개요
-프로젝트 목적 (1-2문장)
+<instructions>
+@path/to/common-rules.md
+@docs/library/[라이브러리]/index.md
+</instructions>
 
-## 기술 스택
-- 프레임워크: X
-- 언어: Y
-- DB: Z
+---
 
-## 명령어
-| 명령 | 설명 |
+<forbidden>
+| 분류 | 금지 |
 |------|------|
-| `yarn dev` | 개발 서버 |
-| `yarn test` | 테스트 실행 |
+| **Git** | AI 표시, 이모지, 여러 줄 |
+</forbidden>
 
-## 컨벤션
-- 파일명: kebab-case
-- 함수: const 화살표 함수
-- 타입: interface (객체), type (유니온)
+---
+
+<required>
+| 분류 | 필수 |
+|------|------|
+| **타입** | 명시적 return type |
+</required>
+
+---
+
+<tech_stack>
+| 기술 | 버전 | 주의 |
+|------|------|------|
+| TypeScript | 5.x | strict |
+</tech_stack>
+
+---
 
-## 워크플로우
-기능 추가 → 테스트 → 린트 → 커밋
+<quick_patterns>
+```typescript
+// 복사 가능한 패턴
+const example = () => { ... }
 ```
+</quick_patterns>
+```
+
+---
+
+## SKILL.md - 재사용 작업
 
-### SKILL.md
+**용도:** 특정 작업 자동화 스킬 정의
 
+**구조:**
 ```markdown
 ---
 name: skill-name
-description: 무엇을 하는지 + 언제 사용하는지. (scope)
+description: 짧은 설명 (1줄)
 ---
 
-# Skill Name
+<trigger_conditions>
+| 키워드/상황 | 반응 |
+|-----------|------|
+| "키워드" | 즉시 실행 |
+</trigger_conditions>
 
-스킬 목적 (2-3문장)
-
-## 사용 시점
-- 조건 1
-- 조건 2
+---
 
-## 사용 방법
+<workflow>
+<step number="1">
+<action>액션 설명</action>
+<tools>Tool1, Tool2</tools>
+</step>
+</workflow>
 
-### 기본 워크플로우
-1. 단계 1
-2. 단계 2
+---
 
-### 참조
-- 상세 API: [references/api.md](references/api.md)
-- 스키마: [references/schema.md](references/schema.md)
+<examples>
+```typescript
+// 실제 코드
 ```
+</examples>
+```
+
+---
 
-## Progressive Disclosure
+## COMMAND.md - CLI 커맨드
 
-```
-project/
-├── CLAUDE.md           # 핵심만 (60-200줄)
-├── docs/
-│   ├── api.md          # API 상세
-│   └── architecture.md # 아키텍처
-└── .claude/skills/
-    └── my-skill/
-        ├── SKILL.md        # 개요 (<500줄)
-        └── references/     # 상세 정보
+**용도:** 슬래시 커맨드 정의 (/commit, /review)
+
+**구조:**
+```markdown
+---
+description: 커맨드 설명
+allowed-tools: Read, Edit, Bash
+argument-hint: <인자 설명>
+---
+
+<purpose>
+구체적 목표
+</purpose>
+
+---
+
+<workflow>
+실행 단계
+</workflow>
+
+---
+
+<examples>
+✅/❌ 비교 예시
+</examples>
 ```
 
-**토큰 로드 단계:**
+</document_types>
 
-| 단계 | 내용 | 크기 |
-|------|------|------|
-| 1. 메타데이터 | name + description | 30-50 토큰 |
-| 2. 활성화 | SKILL.md 본문 | <5k 단어 |
-| 3. 참조 | 번들 리소스 | 필요 시만 |
+---
 
-## 작성 규칙
+<templates>
 
-### DO
+## Template 1: CLAUDE.md
 
-- 불릿 포인트 + 짧은 문장
-- 코드 예시 중심
-- 표로 정보 구조화
-- 강조: `IMPORTANT:`, `YOU MUST:`
-- 1단계 깊이 참조 (A→B ✅, A→B→C ❌)
+```markdown
+# CLAUDE.md - [프로젝트명]
+
+<instructions>
+@.claude/instructions/git-rules.md
+@docs/library/react/index.md
+</instructions>
 
-### DON'T
+---
 
-- 긴 서술형 문단
-- Claude가 아는 것 설명
-- 린터 역할 강요 (도구 사용)
-- 시간 의존적 정보
-- /init 자동 생성 의존
+<forbidden>
+| 분류 | 금지 |
+|------|------|
+| **Git** | AI 표시, 이모지 |
+| **타입** | any (unknown 사용) |
+</forbidden>
 
-## Description 작성
+---
 
-SKILL.md의 description은 스킬 발견에 핵심.
+<required>
+| 분류 | 필수 |
+|------|------|
+| **함수** | const 선언, 명시적 return type |
+| **Import** | 절대 경로 (@/) |
+</required>
 
-```yaml
-# Good - 구체적 + 트리거 포함
-description: PDF에서 텍스트/표 추출, 폼 작성. PDF 작업 시 사용.
+---
+
+<quick_patterns>
+```typescript
+// ✅ 올바른 패턴
+const fetchUser = async (id: string): Promise<User> => {
+  return await prisma.user.findUnique({ where: { id } })
+}
 
-# Bad - 모호함
-description: 문서 처리
+// ❌ 잘못된 패턴
+function fetchUser(id) { ... }
+```
+</quick_patterns>
 ```
 
-**규칙:**
-- 3인칭 작성 (시스템 프롬프트에 주입됨)
-- 무엇을 하는지 + 언제 사용하는지
-- 구체적 키워드 포함
+---
 
-## Context 관리
+## Template 2: SKILL.md
 
-| 명령어 | 용도 | 시점 |
-|--------|------|------|
-| `/compact` | 컨텍스트 요약 | 70% 도달 |
-| `/clear` | 세션 초기화 | 새 기능 시작 |
-| `/resume` | 세션 복원 | 작업 재개 |
+```markdown
+---
+name: test-runner
+description: 테스트 실행 및 실패 수정
+---
 
-**주의:** 마지막 20%는 복잡한 작업 피할 것
+<trigger_conditions>
+| 트리거 | 반응 |
+|--------|------|
+| 코드 수정 완료 | 자동 실행 |
+| "테스트 실행" | 즉시 실행 |
+</trigger_conditions>
 
-## Subagent 활용
+---
 
-문서 작성 시 subagent를 적극 활용하여 메인 컨텍스트 보호.
+<forbidden>
+| 금지 |
+|------|
+| 테스트 삭제로 통과, 테스트 없이 완료 |
+</forbidden>
 
-### Subagent 종류
+---
 
-| 타입 | 용도 | 문서 작성 활용 |
-|------|------|---------------|
-| `Explore` | 코드베이스 탐색 | 프로젝트 구조 파악, 패턴 분석 |
-| `Plan` | 구현 계획 수립 | 문서 구조 설계, 섹션 계획 |
-| `general-purpose` | 범용 조사 | 베스트 프랙티스 조사, 예시 수집 |
+<required>
+| 필수 |
+|------|
+| 모든 테스트 통과, 실패 원인 설명 |
+</required>
 
-### 활용 시점
+---
 
-**CLAUDE.md 작성 시:**
-```
-1. Explore agent → 프로젝트 구조/기술 스택 파악
-2. Explore agent → 기존 컨벤션/패턴 분석
-3. 메인 에이전트 → 요약 기반 문서 작성
-```
+<workflow>
+<step number="1">
+<action>테스트 실행</action>
+<tools>Bash</tools>
+<command>npm test</command>
+</step>
+
+<step number="2">
+<action>실패 분석</action>
+<tools>Read</tools>
+</step>
+
+<step number="3">
+<action>코드 수정</action>
+<tools>Edit</tools>
+</step>
+
+<step number="4">
+<action>재실행</action>
+<criteria>모든 테스트 통과</criteria>
+</step>
+</workflow>
+
+---
 
-**SKILL.md 작성 시:**
+<examples>
+```typescript
+// ❌ 버그
+const sum = (a: number, b: number) => a - b
+
+// ✅ 수정
+const sum = (a: number, b: number) => a + b
 ```
-1. Explore agent → 관련 코드/워크플로우 분석
-2. Plan agent → 스킬 구조 설계
-3. 메인 에이전트 → 설계 기반 작성
+</examples>
 ```
 
-### 효과
+</templates>
 
-| 방식 | 컨텍스트 사용 |
-|------|--------------|
-| 직접 탐색 | 전체 파일 내용 로드 |
-| Subagent | 요약만 반환 → 90%+ 절약 |
+---
 
-### 프롬프트 예시
+<workflow>
+
+<step number="1">
+<action>문서 유형 결정 및 프로젝트 분석</action>
+<output>
+- CLAUDE.md | SKILL.md | COMMAND.md 선택
+- 프로젝트 구조 파악 (Glob, Read)
+- 기존 패턴 식별 (Grep)
+- 라이브러리 버전 확인
+</output>
+</step>
+
+<step number="2">
+<action>핵심 규칙 추출</action>
+<priority>
+1. 절대 금지 사항 (forbidden)
+2. 필수 사항 (required)
+3. 일반적 패턴 (patterns)
+</priority>
+</step>
+
+<step number="3">
+<action>템플릿 선택 및 작성</action>
+<guidelines>
+- XML 태그로 섹션 구분
+- 표 형식으로 정보 압축
+- 코드 예시 중심
+- @imports로 공통 규칙 분리
+- 버전 명시
+</guidelines>
+</step>
+
+<step number="4">
+<action>품질 검증</action>
+<checklist>
+- [ ] 토큰 효율 (500줄 이하)
+- [ ] XML 태그 올바른 중첩
+- [ ] 코드 예시 실행 가능
+- [ ] 긍정형 지시 (Don't → Do)
+- [ ] 버전 명시
+- [ ] ✅/❌ 마커 사용
+</checklist>
+</step>
+
+</workflow>
 
-```
-Explore agent에게:
-"프로젝트 구조와 기술 스택을 분석하고,
-CLAUDE.md에 포함할 핵심 정보만 요약해줘.
-- 디렉토리 구조
-- 주요 의존성
-- 빌드/테스트 명령어
-- 코드 컨벤션"
-```
+---
+
+<examples>
+
+### Example 1: TanStack Start CLAUDE.md
+
+**상황:** 새 TanStack Start 프로젝트, Prisma + Zod 사용
 
+**작성 결과:**
+```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>
+
+---
+
+<forbidden>
+| 분류 | 금지 |
+|------|------|
+| **API** | `/api` 라우터 (명시 요청 제외) |
+| **Server Function** | handler 내부 수동 검증/인증 |
+| **타입** | any (unknown 사용) |
+</forbidden>
+
+---
+
+<required>
+| 분류 | 필수 |
+|------|------|
+| **Server Function** | POST/PUT → inputValidator + middleware |
+| **클라이언트** | Server Function → TanStack Query |
+| **타입** | 명시적 return type |
+</required>
+
+---
+
+<tech_stack>
+| 기술 | 버전 | 주의 |
+|------|------|------|
+| TanStack Start | 최신 | File-based routing |
+| Prisma | 7.x | prisma-client, output 필수 |
+| Zod | 4.x | z.email(), z.url() |
+</tech_stack>
+
+---
+
+<quick_patterns>
+```typescript
+// Server Function (POST + Validation + Auth)
+export const createUser = createServerFn({ method: 'POST' })
+  .middleware([authMiddleware])
+  .inputValidator(createUserSchema)
+  .handler(async ({ data }) => prisma.user.create({ data }))
+
+// Zod v4
+const schema = z.object({
+  email: z.email(),
+  website: z.url().optional(),
+})
+
+// TanStack Query
+const mutation = useMutation({
+  mutationFn: createUser,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+})
 ```
-Plan agent에게:
-"이 스킬의 SKILL.md 구조를 설계해줘.
-- 스킬 목적
-- 주요 섹션
-- 참조 파일 분리 계획
-- 워크플로우 단계"
+</quick_patterns>
 ```
 
-## 체크리스트
 
-### CLAUDE.md
+</examples>
 
-- [ ] 60-200줄 이내
-- [ ] 기술 스택 명시
-- [ ] 주요 명령어 포함
-- [ ] 컨벤션 정리
-- [ ] 민감 정보 제외
+---
 
-### SKILL.md
+<validation>
 
-- [ ] 500줄 이하
-- [ ] description 구체적 (무엇 + 언제)
-- [ ] 3인칭 작성
-- [ ] 참조 1단계 깊이
-- [ ] 100줄+ 파일은 목차 포함
-- [ ] 워크플로우에 체크리스트
+| 항목 | 기준 | 검증 |
+|------|------|------|
+| **토큰 효율** | 500줄 이하 | `wc -l` |
+| **XML 태그** | 올바른 중첩 | `grep -o '<[^>]*>'` |
+| **예시 품질** | 실행 가능 | 테스트 |
+| **긍정형** | Don't < 5 | `grep -c "Don't"` |
+
+**체크리스트:**
+- [ ] XML 태그 섹션 구분
+- [ ] 표 형식 압축
+- [ ] 코드 예시 실행 가능
+- [ ] ✅/❌ 마커
+- [ ] @imports 중복 제거
+- [ ] 버전 명시
+- [ ] 긍정형 지시
+
+</validation>
+
+---
 
-### 공통
+<best_practices>
 
-- [ ] 간결한 작성
-- [ ] 코드 예시 포함
-- [ ] 표로 구조화
-- [ ] 시간 의존 정보 없음
-- [ ] Subagent로 사전 조사 완료
-- [ ] 테스트 완료
+## 작성 원칙
 
-## 참조
+| 원칙 | 방법 |
+|------|------|
+| **Show, Don't Tell** | 설명보다 코드 예시 |
+| **High Density** | 1줄당 최대 정보 압축 |
+| **Copy-Paste Ready** | 바로 사용 가능한 패턴 |
+| **Version Explicit** | 라이브러리 버전 명시 |
+| **Positive Language** | "Do X" > "Don't Y" |
+
+## 일반적 실수
+
+| 실수 | 올바른 방법 |
+|------|------------|
+| 장황한 설명 | 표 형식 + 코드 예시 |
+| XML 태그 없음 | 모든 섹션 태그 구분 |
+| 추상적 예시 | 실행 가능한 코드 |
+| 중복 정보 | @imports 분리 |
+| 버전 누락 | 모든 라이브러리 버전 명시 |
+
+## 문서별 팁
+
+| 문서 | 핵심 |
+|------|------|
+| **CLAUDE.md** | @imports 최대 활용, tech_stack 표준화 |
+| **SKILL.md** | trigger_conditions 명확, workflow 코드 중심 |
+| **COMMAND.md** | purpose 간결, workflow 실행 가능 코드 |
 
-- [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>