@kood/claude-code 0.1.10 → 0.1.12

package/dist/index.js

@@ -372,7 +372,7 @@ var init = async (options) => {
 
 // src/index.ts
 var program = new Command();
-program.name("claude-code").description("Claude Code documentation installer for projects").version("0.1.10");
+program.name("claude-code").description("Claude Code documentation installer for projects").version("0.1.12");
 program.option(
   "-t, --template <names>",
   "template names (comma-separated: tanstack-start,hono)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kood/claude-code",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Claude Code documentation installer for projects",
   "type": "module",
   "bin": "./dist/index.js",

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

@@ -0,0 +1,239 @@
+---
+description: Claude Code 문서 작성 가이드. CLAUDE.md, SKILL.md 등 효과적인 문서 작성 시 사용.
+---
+
+# Docs Creator
+
+Claude Code 문서 작성 베스트 프랙티스 가이드.
+
+## 핵심 원칙
+
+| 원칙 | 설명 |
+|------|------|
+| **간결함** | 컨텍스트 윈도우는 공공재. 모든 토큰이 비용 |
+| **점진적 공개** | 핵심만 메인 파일에, 상세는 참조 파일로 분리 |
+| **보편적 적용** | 모든 세션에 필요한 정보만 포함 |
+
+## 문서 유형별 가이드
+
+| 문서 | 권장 길이 | 용도 |
+|------|----------|------|
+| CLAUDE.md | 60-200줄 | 프로젝트 전역 설정, 컨벤션 |
+| SKILL.md | 500줄 이하 | 특화 워크플로우, 도구 사용법 |
+| references/ | 무제한 | 상세 API 문서, 스키마 등 |
+
+**지침 개수 한계**: 150-200개 (Claude Code 자체 ~50개 사용)
+
+## 구조 템플릿
+
+### CLAUDE.md
+
+```markdown
+# 프로젝트명
+
+## 개요
+프로젝트 목적 (1-2문장)
+
+## 기술 스택
+- 프레임워크: X
+- 언어: Y
+- DB: Z
+
+## 명령어
+| 명령 | 설명 |
+|------|------|
+| `yarn dev` | 개발 서버 |
+| `yarn test` | 테스트 실행 |
+
+## 컨벤션
+- 파일명: kebab-case
+- 함수: const 화살표 함수
+- 타입: interface (객체), type (유니온)
+
+## 워크플로우
+기능 추가 → 테스트 → 린트 → 커밋
+```
+
+### SKILL.md
+
+```markdown
+---
+name: skill-name
+description: 무엇을 하는지 + 언제 사용하는지. (scope)
+---
+
+# Skill Name
+
+스킬 목적 (2-3문장)
+
+## 사용 시점
+- 조건 1
+- 조건 2
+
+## 사용 방법
+
+### 기본 워크플로우
+1. 단계 1
+2. 단계 2
+
+### 참조
+- 상세 API: [references/api.md](references/api.md)
+- 스키마: [references/schema.md](references/schema.md)
+```
+
+## Progressive Disclosure
+
+```
+project/
+├── CLAUDE.md           # 핵심만 (60-200줄)
+├── docs/
+│   ├── api.md          # API 상세
+│   └── architecture.md # 아키텍처
+└── .claude/skills/
+    └── my-skill/
+        ├── SKILL.md        # 개요 (<500줄)
+        └── references/     # 상세 정보
+```
+
+**토큰 로드 단계:**
+
+| 단계 | 내용 | 크기 |
+|------|------|------|
+| 1. 메타데이터 | name + description | 30-50 토큰 |
+| 2. 활성화 | SKILL.md 본문 | <5k 단어 |
+| 3. 참조 | 번들 리소스 | 필요 시만 |
+
+## 작성 규칙
+
+### DO
+
+- 불릿 포인트 + 짧은 문장
+- 코드 예시 중심
+- 표로 정보 구조화
+- 강조: `IMPORTANT:`, `YOU MUST:`
+- 1단계 깊이 참조 (A→B ✅, A→B→C ❌)
+
+### DON'T
+
+- 긴 서술형 문단
+- Claude가 아는 것 설명
+- 린터 역할 강요 (도구 사용)
+- 시간 의존적 정보
+- /init 자동 생성 의존
+
+## Description 작성
+
+SKILL.md의 description은 스킬 발견에 핵심.
+
+```yaml
+# Good - 구체적 + 트리거 포함
+description: PDF에서 텍스트/표 추출, 폼 작성. PDF 작업 시 사용.
+
+# Bad - 모호함
+description: 문서 처리
+```
+
+**규칙:**
+- 3인칭 작성 (시스템 프롬프트에 주입됨)
+- 무엇을 하는지 + 언제 사용하는지
+- 구체적 키워드 포함
+
+## Context 관리
+
+| 명령어 | 용도 | 시점 |
+|--------|------|------|
+| `/compact` | 컨텍스트 요약 | 70% 도달 |
+| `/clear` | 세션 초기화 | 새 기능 시작 |
+| `/resume` | 세션 복원 | 작업 재개 |
+
+**주의:** 마지막 20%는 복잡한 작업 피할 것
+
+## Subagent 활용
+
+문서 작성 시 subagent를 적극 활용하여 메인 컨텍스트 보호.
+
+### Subagent 종류
+
+| 타입 | 용도 | 문서 작성 활용 |
+|------|------|---------------|
+| `Explore` | 코드베이스 탐색 | 프로젝트 구조 파악, 패턴 분석 |
+| `Plan` | 구현 계획 수립 | 문서 구조 설계, 섹션 계획 |
+| `general-purpose` | 범용 조사 | 베스트 프랙티스 조사, 예시 수집 |
+
+### 활용 시점
+
+**CLAUDE.md 작성 시:**
+```
+1. Explore agent → 프로젝트 구조/기술 스택 파악
+2. Explore agent → 기존 컨벤션/패턴 분석
+3. 메인 에이전트 → 요약 기반 문서 작성
+```
+
+**SKILL.md 작성 시:**
+```
+1. Explore agent → 관련 코드/워크플로우 분석
+2. Plan agent → 스킬 구조 설계
+3. 메인 에이전트 → 설계 기반 작성
+```
+
+### 효과
+
+| 방식 | 컨텍스트 사용 |
+|------|--------------|
+| 직접 탐색 | 전체 파일 내용 로드 |
+| Subagent | 요약만 반환 → 90%+ 절약 |
+
+### 프롬프트 예시
+
+```
+Explore agent에게:
+"프로젝트 구조와 기술 스택을 분석하고,
+CLAUDE.md에 포함할 핵심 정보만 요약해줘.
+- 디렉토리 구조
+- 주요 의존성
+- 빌드/테스트 명령어
+- 코드 컨벤션"
+```
+
+```
+Plan agent에게:
+"이 스킬의 SKILL.md 구조를 설계해줘.
+- 스킬 목적
+- 주요 섹션
+- 참조 파일 분리 계획
+- 워크플로우 단계"
+```
+
+## 체크리스트
+
+### CLAUDE.md
+
+- [ ] 60-200줄 이내
+- [ ] 기술 스택 명시
+- [ ] 주요 명령어 포함
+- [ ] 컨벤션 정리
+- [ ] 민감 정보 제외
+
+### SKILL.md
+
+- [ ] 500줄 이하
+- [ ] description 구체적 (무엇 + 언제)
+- [ ] 3인칭 작성
+- [ ] 참조 1단계 깊이
+- [ ] 100줄+ 파일은 목차 포함
+- [ ] 워크플로우에 체크리스트
+
+### 공통
+
+- [ ] 간결한 작성
+- [ ] 코드 예시 포함
+- [ ] 표로 구조화
+- [ ] 시간 의존 정보 없음
+- [ ] Subagent로 사전 조사 완료
+- [ ] 테스트 완료
+
+## 참조
+
+- [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)

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

@@ -0,0 +1,168 @@
+---
+description: Claude Code 문서 리팩토링 가이드. 기존 CLAUDE.md, SKILL.md 개선 시 사용.
+---
+
+# Docs Refactor
+
+기존 Claude Code 문서를 베스트 프랙티스에 맞게 개선하는 가이드.
+
+## 리팩토링 필요 신호
+
+| 신호 | 문제 | 우선순위 |
+|------|------|---------|
+| 200줄+ CLAUDE.md | 컨텍스트 과부하 | 높음 |
+| 500줄+ SKILL.md | 로딩 지연, 품질 저하 | 높음 |
+| Claude가 지침 무시 | 과도한 지침 (150+개) | 높음 |
+| 중첩 참조 (A→B→C) | 불완전한 파일 읽기 | 중간 |
+| 코드 스타일 지침 | 린터 역할 강요 | 중간 |
+| 시간 의존 정보 | 오래된 지침 | 낮음 |
+
+## 분석 워크플로우
+
+### 1단계: Subagent로 현황 분석
+
+```
+Explore agent에게:
+"현재 CLAUDE.md/SKILL.md를 분석하고 보고해줘:
+- 총 줄 수
+- 섹션별 줄 수
+- 지침 개수 (명령형 문장)
+- 중첩 참조 깊이
+- 린터 역할 지침 여부
+- 시간 의존 정보 여부"
+```
+
+### 2단계: 개선 계획 수립
+
+```
+Plan agent에게:
+"분석 결과를 바탕으로 리팩토링 계획 수립:
+- 삭제할 내용
+- 분리할 내용 (references/)
+- 병합할 섹션
+- 추가할 내용"
+```
+
+### 3단계: 리팩토링 실행
+
+메인 에이전트가 계획 기반으로 문서 수정.
+
+## 안티패턴 → 개선 패턴
+
+### 길이 문제
+
+| Before | After |
+|--------|-------|
+| 300줄 CLAUDE.md | 60-200줄 + docs/ 분리 |
+| 800줄 SKILL.md | 500줄 이하 + references/ 분리 |
+
+**분리 기준:**
+- 모든 세션에 필요 → 메인 파일
+- 특정 작업에만 필요 → 참조 파일
+
+### 구조 문제
+
+| Before | After |
+|--------|-------|
+| 긴 서술형 문단 | 불릿 포인트 + 짧은 문장 |
+| 중첩 참조 (A→B→C) | 1단계 깊이 (A→B) |
+| 목차 없는 100줄+ 파일 | 상단에 목차 추가 |
+
+### 내용 문제
+
+| Before | After |
+|--------|-------|
+| 코드 스타일 가이드 | 삭제 (Biome/ESLint 사용) |
+| Claude가 아는 설명 | 삭제 |
+| 시간 의존 정보 | "old patterns" 섹션으로 이동 |
+| 너무 많은 옵션 | 기본값 + 대안 1개 |
+
+**삭제 예시:**
+```markdown
+# Before - 불필요한 설명
+PDF (Portable Document Format)는 Adobe에서 개발한
+문서 형식으로, 텍스트와 이미지를 포함할 수 있습니다...
+
+# After - 핵심만
+PDF 텍스트 추출: `pdfplumber.open("file.pdf")`
+```
+
+### Description 문제
+
+| Before | After |
+|--------|-------|
+| `description: 문서 처리` | `description: PDF 텍스트/표 추출. PDF 작업 시 사용.` |
+| 1인칭/2인칭 | 3인칭 작성 |
+| 트리거 없음 | 구체적 트리거 포함 |
+
+## 분리 전략
+
+### 참조 파일로 분리할 내용
+
+| 내용 | 분리 위치 |
+|------|----------|
+| API 상세 문서 | `references/api.md` |
+| 스키마 정의 | `references/schema.md` |
+| 예시 모음 | `references/examples.md` |
+| 도메인별 가이드 | `references/{domain}.md` |
+
+### 분리 후 메인 파일 참조
+
+```markdown
+## API 사용
+
+기본 호출: `api.call(params)`
+
+**상세 API 문서**: [references/api.md](references/api.md)
+```
+
+## Subagent 활용
+
+| 단계 | Agent | 작업 |
+|------|-------|------|
+| 분석 | Explore | 현황 파악, 문제점 식별 |
+| 계획 | Plan | 리팩토링 전략 수립 |
+| 검증 | Explore | 개선 결과 확인 |
+
+### 검증 프롬프트
+
+```
+Explore agent에게:
+"리팩토링된 문서 검증:
+- 줄 수 목표 달성?
+- 지침 개수 150개 이하?
+- 중첩 참조 1단계?
+- 필수 정보 누락 없음?"
+```
+
+## 체크리스트
+
+### 분석 단계
+
+- [ ] Subagent로 현황 분석 완료
+- [ ] 문제점 목록 작성
+- [ ] 개선 우선순위 결정
+
+### 리팩토링 단계
+
+- [ ] 불필요한 설명 삭제
+- [ ] 코드 스타일 지침 삭제
+- [ ] 긴 내용 참조 파일로 분리
+- [ ] 중첩 참조 1단계로 평탄화
+- [ ] 100줄+ 파일에 목차 추가
+- [ ] Description 개선 (3인칭, 트리거)
+
+### 검증 단계
+
+- [ ] CLAUDE.md 60-200줄
+- [ ] SKILL.md 500줄 이하
+- [ ] 지침 개수 150개 이하
+- [ ] 참조 1단계 깊이
+- [ ] 필수 정보 유지 확인
+- [ ] 테스트 완료
+
+## 참조
+
+- [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)

package/templates/hono/docs/commands/git-all.md

@@ -0,0 +1,83 @@
+---
+description: 모든 변경사항 커밋 후 푸시
+allowed-tools: Bash(git:*)
+---
+
+모든 변경사항을 논리적 단위로 분리하여 전부 커밋 후 푸시.
+
+## 실행 흐름
+
+```
+1. git status + git diff (병렬 실행)
+2. 논리적 단위로 분리하여 git add + git commit (반복)
+3. git status (완료 확인 - 남은 변경 없어야 함)
+4. git push
+```
+
+## 병렬 실행
+
+**초기 분석 단계에서 병렬 실행 필수:**
+
+```bash
+# 동시에 실행 (두 Bash 호출을 하나의 응답에서)
+git status
+git diff
+```
+
+## CRITICAL: 절대 금지
+
+| 금지 항목 |
+|----------|
+| "Generated with Claude Code" 포함 |
+| "🤖" 또는 AI 관련 이모지 |
+| "Co-Authored-By:" 헤더 |
+| AI/봇 작성 표시 일체 |
+| 여러 줄 커밋 메시지 |
+| 커밋 메시지에 마침표(.) |
+| 여러 작업 하나로 퉁치기 |
+| 변경사항 남겨두기 |
+
+## 커밋 규칙
+
+**형식**: `<prefix>: <설명>` (한 줄, 본문/푸터 없음)
+
+**핵심 원칙**: 하나의 커밋 = 하나의 논리적 변경
+
+### Prefix
+
+| Prefix | 용도 |
+|--------|------|
+| feat | 새 기능 |
+| fix | 버그 수정 |
+| refactor | 리팩토링 |
+| style | 코드 스타일 |
+| docs | 문서 수정 |
+| test | 테스트 |
+| chore | 빌드/설정 |
+| perf | 성능 개선 |
+| ci | CI/CD |
+
+### 분리 기준
+
+| 분리 필요 | 묶어도 됨 |
+|----------|----------|
+| 서로 다른 기능 | 동일 기능의 관련 파일들 |
+| 버그 수정 + 새 기능 | 동일 기능의 타입 + 구현 |
+| 코드 변경 + 문서 변경 | |
+| 리팩토링 + 기능 추가 | |
+
+## 예시
+
+```bash
+# ✅ 올바른
+feat: 사용자 로그인 기능 추가
+fix: 세션 만료 오류 수정
+refactor: 서비스 클래스 구조 개선
+
+# ❌ 잘못된
+사용자 인증 기능 추가함     # prefix 없음
+feat: 사용자 인증 추가.     # 마침표
+FEAT: 사용자 인증 추가      # 대문자
+feat(auth): 인증 추가       # scope 불필요
+feat: 로그인, 회원가입, 프로필  # 여러 작업 퉁침
+```

package/templates/hono/docs/commands/git-session.md

@@ -0,0 +1,91 @@
+---
+description: 현재 세션에서 수정한 파일만 커밋 후 푸시
+allowed-tools: Bash(git:*)
+---
+
+이 세션에서 수정한 파일만 논리적 단위로 분리하여 커밋 후 푸시.
+
+## 실행 흐름
+
+```
+1. git status + git diff (병렬 실행)
+2. 대화 맥락에서 이 세션에 수정한 파일 목록 파악
+3. 해당 파일만 논리적 단위로 git add + git commit (반복)
+4. git status (완료 확인)
+5. git push
+```
+
+## 세션 파일 판별
+
+**대화 맥락에서 Edit/Write 도구로 수정한 파일만 대상**
+
+- 이 세션에서 직접 수정하지 않은 파일은 절대 stage하지 않음
+- 다른 변경사항은 unstaged 상태로 유지
+
+## 병렬 실행
+
+**초기 분석 단계에서 병렬 실행 필수:**
+
+```bash
+# 동시에 실행 (두 Bash 호출을 하나의 응답에서)
+git status
+git diff
+```
+
+## CRITICAL: 절대 금지
+
+| 금지 항목 |
+|----------|
+| "Generated with Claude Code" 포함 |
+| "🤖" 또는 AI 관련 이모지 |
+| "Co-Authored-By:" 헤더 |
+| AI/봇 작성 표시 일체 |
+| 여러 줄 커밋 메시지 |
+| 커밋 메시지에 마침표(.) |
+| 여러 작업 하나로 퉁치기 |
+| 세션에서 수정하지 않은 파일 커밋 |
+
+## 커밋 규칙
+
+**형식**: `<prefix>: <설명>` (한 줄, 본문/푸터 없음)
+
+**핵심 원칙**: 하나의 커밋 = 하나의 논리적 변경
+
+### Prefix
+
+| Prefix | 용도 |
+|--------|------|
+| feat | 새 기능 |
+| fix | 버그 수정 |
+| refactor | 리팩토링 |
+| style | 코드 스타일 |
+| docs | 문서 수정 |
+| test | 테스트 |
+| chore | 빌드/설정 |
+| perf | 성능 개선 |
+| ci | CI/CD |
+
+### 분리 기준
+
+| 분리 필요 | 묶어도 됨 |
+|----------|----------|
+| 서로 다른 기능 | 동일 기능의 관련 파일들 |
+| 버그 수정 + 새 기능 | 동일 기능의 타입 + 구현 |
+| 코드 변경 + 문서 변경 | |
+| 리팩토링 + 기능 추가 | |
+
+## 예시
+
+```bash
+# ✅ 올바른
+feat: 사용자 로그인 기능 추가
+fix: 세션 만료 오류 수정
+refactor: 서비스 클래스 구조 개선
+
+# ❌ 잘못된
+사용자 인증 기능 추가함     # prefix 없음
+feat: 사용자 인증 추가.     # 마침표
+FEAT: 사용자 인증 추가      # 대문자
+feat(auth): 인증 추가       # scope 불필요
+feat: 로그인, 회원가입, 프로필  # 여러 작업 퉁침
+```

package/templates/hono/docs/commands/git.md

@@ -0,0 +1,86 @@
+---
+description: Git 상태 확인 및 커밋 작업
+allowed-tools: Bash(git:*)
+argument-hint: [push|pull|커밋 지시사항...]
+---
+
+Git 상태 확인 후 아래 규칙에 따라 작업 진행.
+
+**지시사항**: $ARGUMENTS
+
+## 실행 흐름
+
+```
+$ARGUMENTS 있음 → 해당 지시 우선 수행
+$ARGUMENTS 없음 → 기본 동작:
+  1. git status + git diff (병렬 실행)
+  2. 논리적 단위로 분리하여 git add + git commit
+  3. git status (완료 확인)
+```
+
+## 병렬 실행
+
+**초기 분석 단계에서 병렬 실행 필수:**
+
+```bash
+# 동시에 실행 (두 Bash 호출을 하나의 응답에서)
+git status
+git diff
+```
+
+## CRITICAL: 절대 금지
+
+| 금지 항목 |
+|----------|
+| "Generated with Claude Code" 포함 |
+| "🤖" 또는 AI 관련 이모지 |
+| "Co-Authored-By:" 헤더 |
+| AI/봇 작성 표시 일체 |
+| 여러 줄 커밋 메시지 |
+| 커밋 메시지에 마침표(.) |
+| 여러 작업 하나로 퉁치기 |
+
+## 커밋 규칙
+
+**형식**: `<prefix>: <설명>` (한 줄, 본문/푸터 없음)
+
+**핵심 원칙**: 하나의 커밋 = 하나의 논리적 변경
+
+### Prefix
+
+| Prefix | 용도 |
+|--------|------|
+| feat | 새 기능 |
+| fix | 버그 수정 |
+| refactor | 리팩토링 |
+| style | 코드 스타일 |
+| docs | 문서 수정 |
+| test | 테스트 |
+| chore | 빌드/설정 |
+| perf | 성능 개선 |
+| ci | CI/CD |
+
+### 분리 기준
+
+| 분리 필요 | 묶어도 됨 |
+|----------|----------|
+| 서로 다른 기능 | 동일 기능의 관련 파일들 |
+| 버그 수정 + 새 기능 | 동일 기능의 타입 + 구현 |
+| 코드 변경 + 문서 변경 | |
+| 리팩토링 + 기능 추가 | |
+
+## 예시
+
+```bash
+# ✅ 올바른
+feat: 사용자 로그인 기능 추가
+fix: 세션 만료 오류 수정
+refactor: 서비스 클래스 구조 개선
+
+# ❌ 잘못된
+사용자 인증 기능 추가함     # prefix 없음
+feat: 사용자 인증 추가.     # 마침표
+FEAT: 사용자 인증 추가      # 대문자
+feat(auth): 인증 추가       # scope 불필요
+feat: 로그인, 회원가입, 프로필  # 여러 작업 퉁침
+```