@kood/claude-code 0.1.9 → 0.1.11

package/dist/index.js

@@ -281,8 +281,31 @@ var init = async (options) => {
   }
   logger.blank();
   logger.success(`Total: ${totalFiles} files, ${totalDirectories} directories`);
-  if (options.skills || options.commands) {
-    const { hasSkills, hasCommands } = await checkSkillsAndCommandsExist(templates);
+  const { hasSkills, hasCommands } = await checkSkillsAndCommandsExist(templates);
+  let installSkills = options.skills ?? false;
+  let installCommands = options.commands ?? false;
+  if (!options.skills && !options.commands && (hasSkills || hasCommands)) {
+    logger.blank();
+    if (hasSkills) {
+      const skillsResponse = await prompts({
+        type: "confirm",
+        name: "install",
+        message: "Install skills to .claude/skills/?",
+        initial: true
+      });
+      installSkills = skillsResponse.install ?? false;
+    }
+    if (hasCommands) {
+      const commandsResponse = await prompts({
+        type: "confirm",
+        name: "install",
+        message: "Install commands to .claude/commands/?",
+        initial: true
+      });
+      installCommands = commandsResponse.install ?? false;
+    }
+  }
+  if (installSkills || installCommands) {
     const existingClaudeFiles = await checkExistingClaudeFiles(targetDir);
     if (existingClaudeFiles.length > 0 && !options.force) {
       logger.warn("The following .claude files/folders already exist:");
@@ -296,37 +319,33 @@ var init = async (options) => {
       });
       if (!response.overwrite) {
         logger.info("Skipping skills/commands installation.");
-      } else {
-        await installSkillsAndCommands();
+        installSkills = false;
+        installCommands = false;
       }
-    } else {
-      await installSkillsAndCommands();
     }
-    async function installSkillsAndCommands() {
-      if (options.skills && hasSkills) {
-        logger.blank();
-        logger.info("Installing skills...");
-        const skillsResult = await copySkills(templates, targetDir);
-        totalFiles += skillsResult.files;
-        totalDirectories += skillsResult.directories;
-        logger.success(
-          `Skills: ${skillsResult.files} files, ${skillsResult.directories} directories`
-        );
-      } else if (options.skills && !hasSkills) {
-        logger.warn("No skills found in selected templates.");
-      }
-      if (options.commands && hasCommands) {
-        logger.blank();
-        logger.info("Installing commands...");
-        const commandsResult = await copyCommands(templates, targetDir);
-        totalFiles += commandsResult.files;
-        totalDirectories += commandsResult.directories;
-        logger.success(
-          `Commands: ${commandsResult.files} files, ${commandsResult.directories} directories`
-        );
-      } else if (options.commands && !hasCommands) {
-        logger.warn("No commands found in selected templates.");
-      }
+    if (installSkills && hasSkills) {
+      logger.blank();
+      logger.info("Installing skills...");
+      const skillsResult = await copySkills(templates, targetDir);
+      totalFiles += skillsResult.files;
+      totalDirectories += skillsResult.directories;
+      logger.success(
+        `Skills: ${skillsResult.files} files, ${skillsResult.directories} directories`
+      );
+    } else if (installSkills && !hasSkills) {
+      logger.warn("No skills found in selected templates.");
+    }
+    if (installCommands && hasCommands) {
+      logger.blank();
+      logger.info("Installing commands...");
+      const commandsResult = await copyCommands(templates, targetDir);
+      totalFiles += commandsResult.files;
+      totalDirectories += commandsResult.directories;
+      logger.success(
+        `Commands: ${commandsResult.files} files, ${commandsResult.directories} directories`
+      );
+    } else if (installCommands && !hasCommands) {
+      logger.warn("No commands found in selected templates.");
     }
   }
   logger.blank();
@@ -334,13 +353,13 @@ var init = async (options) => {
   logger.blank();
   logger.info("Installed templates:");
   templates.forEach((t) => logger.step(t));
-  if (options.skills || options.commands) {
+  if (installSkills || installCommands) {
     logger.blank();
     logger.info("Installed extras:");
-    if (options.skills) {
+    if (installSkills) {
       logger.step("Skills \u2192 .claude/skills/");
     }
-    if (options.commands) {
+    if (installCommands) {
       logger.step("Commands \u2192 .claude/commands/");
     }
   }
@@ -353,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.9");
+program.name("claude-code").description("Claude Code documentation installer for projects").version("0.1.11");
 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.9",
+  "version": "0.1.11",
   "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: 로그인, 회원가입, 프로필  # 여러 작업 퉁침
+```