@kood/claude-code 0.1.2 → 0.1.3

package/templates/npx/CLAUDE.md

@@ -0,0 +1,309 @@
+# CLAUDE.md - Claude Code Instructions
+
+> NPX CLI 도구 프로젝트 작업 지침
+
+---
+
+## 🚨 STOP - 작업 전 필수 확인
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  이 프로젝트에서 작업하기 전에 이 문서를 끝까지 읽으세요.  │
+│  특히 ⛔ NEVER DO 섹션의 규칙은 절대 위반하지 마세요.      │
+│                                                             │
+│  📖 작업 유형별 상세 문서: docs/ 폴더 참조                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ⛔ NEVER DO (절대 금지 - 예외 없음)
+
+### Git 커밋 금지 사항
+```
+❌ "Generated with Claude Code" 포함 금지
+❌ "🤖" 또는 AI 관련 이모지 포함 금지
+❌ "Co-Authored-By:" 헤더 포함 금지
+❌ AI/봇이 작성했다는 어떤 표시도 금지
+❌ 커밋 메시지 여러 줄 작성 금지
+❌ 커밋 메시지에 이모지 사용 금지
+```
+
+### CLI 구현 금지 사항
+```
+❌ process.exit() 없이 에러 상황 종료 금지
+❌ console.log 직접 사용 금지 (logger 사용)
+❌ 동기 파일 작업 (fs.readFileSync 등) 금지
+❌ hardcoded 경로 사용 금지 (path.join 사용)
+❌ 사용자 입력 검증 없이 처리 금지
+```
+
+### 코드 검색 금지 사항
+```
+❌ grep, rg 등 기본 검색 도구 사용 금지
+❌ find 명령어로 코드 검색 금지
+✅ 코드베이스 검색 시 sgrep 사용 필수
+```
+
+---
+
+## ✅ ALWAYS DO (필수 실행)
+
+### 1. 작업 전: 관련 문서 읽기
+```
+CLI 작업      → docs/library/commander/ 읽기
+파일 작업     → docs/library/fs-extra/ 읽기
+사용자 입력   → docs/library/prompts/ 읽기
+```
+
+### 2. MCP 도구 적극 활용
+```
+코드베이스 검색     → sgrep 사용 (grep/rg 금지)
+복잡한 분석/디버깅  → Sequential Thinking 사용
+라이브러리 문서     → Context7 사용
+```
+**상세**: `docs/mcp/` 참고
+
+### 3. 작업 완료 후: Git 커밋
+```bash
+git add .
+git commit -m "<prefix>: <설명>"
+```
+
+**커밋 형식**: `<prefix>: <설명>` (한 줄, 본문 없음)
+
+**Prefix**: `feat` | `fix` | `refactor` | `style` | `docs` | `test` | `chore` | `perf` | `ci`
+
+**예시**:
+```bash
+feat: 템플릿 복사 기능 추가
+fix: 경로 처리 오류 수정
+docs: README 업데이트
+```
+
+---
+
+## 📚 문서 참조 테이블
+
+| 작업 | 문서 경로 | 필독 여부 |
+|------|----------|----------|
+| **Git 규칙** | `docs/git/git.md` | 🔴 필수 |
+| **MCP 도구** | `docs/mcp/` | 🔴 필수 |
+| **Commander** | `docs/library/commander/` | 🔴 필수 |
+| **fs-extra** | `docs/library/fs-extra/` | 🔴 필수 |
+| **prompts** | `docs/library/prompts/` | 🔴 필수 |
+
+---
+
+## 🛠 Tech Stack (버전 주의)
+
+| 기술 | 버전 | 주의사항 |
+|------|------|----------|
+| Node.js | >= 18 | ESM 모듈 사용 |
+| TypeScript | 5.x | strict mode |
+| Commander | 12.x | CLI 프레임워크 |
+| fs-extra | 11.x | 파일 시스템 유틸리티 |
+| prompts | 2.x | Interactive CLI prompts |
+| picocolors | 1.x | 터미널 색상 출력 |
+| tsup | 8.x | TypeScript 번들러 |
+
+---
+
+## 📁 Directory Structure
+
+```
+src/
+├── index.ts              # Entry point (CLI 정의)
+├── commands/             # 명령어 모듈
+│   └── init.ts           # init 명령어
+├── utils/                # 유틸리티
+│   ├── copy.ts           # 파일 복사 유틸
+│   └── logger.ts         # 로깅 유틸
+└── types/                # 타입 정의
+    └── index.ts          # 공통 타입
+
+templates/                # 템플릿 파일 (빌드 시 복사)
+scripts/                  # 빌드 스크립트
+dist/                     # 빌드 결과물
+```
+
+---
+
+## 🔧 Code Conventions
+
+### File Naming
+- **kebab-case**: `copy-template.ts`, `file-utils.ts`
+- **index.ts**: 모듈 진입점
+
+### TypeScript
+- `const` 선언 사용 (function 대신)
+- 명시적 return type
+- `interface` (객체) / `type` (유니온)
+- `any` 금지 → `unknown` 사용
+
+### ESM Module
+```typescript
+// ✅ ESM import
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// __dirname 대체
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+```
+
+---
+
+## 📝 Quick Patterns (복사용)
+
+### CLI Entry Point
+```typescript
+#!/usr/bin/env node
+import { Command } from 'commander';
+
+const program = new Command();
+
+program
+  .name('my-cli')
+  .description('CLI description')
+  .version('1.0.0');
+
+program
+  .option('-t, --template <name>', 'template name')
+  .option('-f, --force', 'overwrite existing files')
+  .action(async (options) => {
+    // 명령어 실행
+  });
+
+program.parse();
+```
+
+### Logger 유틸
+```typescript
+import pc from 'picocolors';
+
+export const logger = {
+  info: (msg: string) => console.log(pc.blue('ℹ'), msg),
+  success: (msg: string) => console.log(pc.green('✔'), msg),
+  warn: (msg: string) => console.log(pc.yellow('⚠'), msg),
+  error: (msg: string) => console.log(pc.red('✖'), msg),
+  step: (msg: string) => console.log(pc.gray('  →'), msg),
+  blank: () => console.log(),
+};
+```
+
+### Interactive Prompts
+```typescript
+import prompts from 'prompts';
+
+// Select (단일 선택)
+const { template } = await prompts({
+  type: 'select',
+  name: 'template',
+  message: 'Select a template:',
+  choices: [
+    { title: 'Template A', value: 'a' },
+    { title: 'Template B', value: 'b' },
+  ],
+});
+
+// Multiselect (다중 선택)
+const { templates } = await prompts({
+  type: 'multiselect',
+  name: 'templates',
+  message: 'Select templates:',
+  choices: [
+    { title: 'Template A', value: 'a' },
+    { title: 'Template B', value: 'b' },
+  ],
+  min: 1,
+  hint: '- Space to select. Return to submit',
+});
+
+// Confirm
+const { confirmed } = await prompts({
+  type: 'confirm',
+  name: 'confirmed',
+  message: 'Overwrite existing files?',
+  initial: false,
+});
+```
+
+### File Copy 유틸
+```typescript
+import fs from 'fs-extra';
+import path from 'path';
+
+export const copyRecursive = async (
+  src: string,
+  dest: string,
+): Promise<{ files: number; directories: number }> => {
+  const counter = { files: 0, directories: 0 };
+
+  const copy = async (s: string, d: string): Promise<void> => {
+    const stat = await fs.stat(s);
+
+    if (stat.isDirectory()) {
+      await fs.ensureDir(d);
+      counter.directories++;
+
+      const items = await fs.readdir(s);
+      for (const item of items) {
+        await copy(path.join(s, item), path.join(d, item));
+      }
+    } else {
+      await fs.copy(s, d);
+      counter.files++;
+    }
+  };
+
+  await copy(src, dest);
+  return counter;
+};
+```
+
+### Package.json 설정
+```json
+{
+  "name": "@scope/my-cli",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": "./dist/index.js",
+  "files": ["dist", "templates"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}
+```
+
+### tsup.config.ts
+```typescript
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  target: 'node18',
+  clean: true,
+  dts: true,
+  banner: {
+    js: '#!/usr/bin/env node',
+  },
+});
+```
+
+---
+
+## 🔗 Quick Links
+
+- [Commander 가이드](./docs/library/commander/index.md)
+- [fs-extra 가이드](./docs/library/fs-extra/index.md)
+- [prompts 가이드](./docs/library/prompts/index.md)
+- [Git 규칙](./docs/git/git.md)
+- [MCP 가이드](./docs/mcp/index.md)

package/templates/npx/docs/git/git.md

@@ -0,0 +1,307 @@
+# Git 워크플로우
+
+> NPX CLI 프로젝트 Git 컨벤션
+
+---
+
+## ⛔ NEVER (절대 금지)
+
+```
+❌ 커밋에 "Generated with Claude Code" 포함
+❌ 커밋에 "🤖" 또는 AI 관련 이모지 포함
+❌ 커밋에 "Co-Authored-By:" 헤더 포함
+❌ 커밋에 AI/봇이 작성했다는 어떤 표시도 포함
+❌ 커밋 메시지 여러 줄 작성
+❌ 커밋 메시지에 이모지 사용
+❌ 커밋 메시지에 마침표(.) 사용
+❌ 여러 작업을 하나의 커밋으로 퉁치기
+```
+
+---
+
+## ✅ ALWAYS (필수)
+
+### 작업 완료 후 반드시 실행
+
+```bash
+git add <관련 파일들>
+git commit -m "<prefix>: <설명>"
+```
+
+### ⭐ 커밋 분리 원칙
+
+**하나의 커밋 = 하나의 논리적 변경 단위**
+
+```bash
+# ❌ 잘못된 방식: 모든 작업을 하나로 퉁침
+git add .
+git commit -m "feat: 여러 기능 추가"
+
+# ✅ 올바른 방식: 논리적 단위로 분리
+git add src/commands/init.ts src/utils/copy.ts
+git commit -m "feat: 템플릿 복사 기능 추가"
+
+git add src/commands/list.ts
+git commit -m "feat: 템플릿 목록 조회 기능 추가"
+
+git add docs/
+git commit -m "docs: CLI 사용법 문서 추가"
+```
+
+---
+
+## 📝 커밋 형식
+
+```
+<prefix>: <설명>
+```
+
+**한 줄로 간결하게** 작성합니다. 본문이나 푸터는 작성하지 않습니다.
+
+---
+
+## 🏷 Prefix 목록
+
+| Prefix | 용도 | 예시 |
+|--------|------|------|
+| `feat` | 새로운 기능 | `feat: 템플릿 복사 기능 추가` |
+| `fix` | 버그 수정 | `fix: 경로 처리 오류 수정` |
+| `refactor` | 리팩토링 | `refactor: copy 유틸 분리` |
+| `style` | 코드 스타일 | `style: prettier 적용` |
+| `docs` | 문서 수정 | `docs: README 업데이트` |
+| `test` | 테스트 | `test: copy 유틸 테스트 추가` |
+| `chore` | 빌드/설정 | `chore: 버전 업데이트` |
+| `perf` | 성능 개선 | `perf: 파일 복사 최적화` |
+| `ci` | CI/CD | `ci: GitHub Actions 추가` |
+
+---
+
+## ✅ 올바른 예시
+
+```bash
+feat: CLI 옵션 추가
+fix: 템플릿 경로 오류 수정
+docs: 사용법 문서 추가
+refactor: logger 유틸 분리
+chore: 의존성 업데이트
+```
+
+---
+
+## ❌ 잘못된 예시
+
+```bash
+# prefix 없음
+템플릿 기능 추가함
+
+# 마침표 불필요
+feat: 새 기능 추가.
+
+# 대문자 사용
+FEAT: 새 기능 추가
+
+# scope 불필요
+feat(cli): 옵션 추가
+
+# AI 작성 표시 (절대 금지!)
+feat: 기능 추가
+
+🤖 Generated with Claude Code
+
+# Co-Author 표시 (절대 금지!)
+feat: 기능 추가
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+# 여러 줄 본문 (금지)
+feat: 새 기능 추가
+
+- 옵션 A 추가
+- 옵션 B 추가
+
+# 여러 작업을 하나로 퉁침 (금지)
+feat: init, list, copy 명령어 추가
+```
+
+---
+
+## 🔄 작업 흐름
+
+```bash
+# 1. 작업 전 최신 코드 동기화
+git pull origin main
+
+# 2. 명령어 작업 완료 → 커밋
+git add src/commands/init.ts src/utils/copy.ts
+git commit -m "feat: 템플릿 초기화 명령어 추가"
+
+# 3. 유틸리티 작업 완료 → 커밋
+git add src/utils/logger.ts src/utils/spinner.ts
+git commit -m "feat: 로깅 및 스피너 유틸 추가"
+
+# 4. 문서 작업 완료 → 커밋
+git add docs/
+git commit -m "docs: CLI 사용법 문서 추가"
+
+# 5. 푸시
+git push origin main
+```
+
+---
+
+## 📦 커밋 분리 가이드
+
+### 언제 커밋을 분리해야 하나요?
+
+| 상황 | 커밋 분리 |
+|------|----------|
+| 서로 다른 CLI 명령어 | ✅ 분리 |
+| 버그 수정 + 새 기능 | ✅ 분리 |
+| 코드 변경 + 문서 변경 | ✅ 분리 |
+| 리팩토링 + 기능 추가 | ✅ 분리 |
+| 동일 명령어의 핸들러 + 유틸 | 🔄 묶어도 됨 |
+| 동일 기능의 타입 + 구현 | 🔄 묶어도 됨 |
+
+### 예시: CLI 도구 개발
+
+```bash
+# 1. init 명령어 커밋
+git add src/commands/init.ts src/utils/copy.ts
+git commit -m "feat: 템플릿 초기화 명령어 추가"
+
+# 2. list 명령어 커밋
+git add src/commands/list.ts
+git commit -m "feat: 템플릿 목록 조회 명령어 추가"
+
+# 3. 공통 유틸 커밋
+git add src/utils/logger.ts src/utils/spinner.ts
+git commit -m "feat: CLI 유틸리티 함수 추가"
+
+# 4. 테스트 커밋
+git add tests/
+git commit -m "test: CLI 명령어 테스트 추가"
+
+# 5. 문서 커밋
+git add docs/ README.md
+git commit -m "docs: CLI 사용법 및 README 추가"
+```
+
+---
+
+## 🌿 브랜치 전략
+
+### 간단한 프로젝트
+```
+main ← 모든 작업 직접 커밋
+```
+
+### 팀 프로젝트
+```
+main
+  └── feature/기능명
+  └── fix/버그명
+  └── hotfix/긴급수정
+```
+
+### 브랜치 명명
+```bash
+feature/multi-template
+feature/interactive-mode
+fix/path-resolution
+hotfix/security-patch
+```
+
+---
+
+## 📋 자주 사용하는 명령어
+
+```bash
+# 상태 확인
+git status
+
+# 변경 내용 확인
+git diff
+
+# 최근 커밋 로그
+git log --oneline -10
+
+# 커밋 취소 (작업 내용 유지)
+git reset --soft HEAD~1
+
+# 스테이징 취소
+git restore --staged .
+
+# 변경사항 임시 저장
+git stash
+git stash pop
+
+# 특정 파일만 스테이징
+git add <파일경로>
+
+# 대화형 스테이징 (부분 커밋용)
+git add -p
+```
+
+---
+
+## 🏷 버전 관리
+
+### 버전 업데이트
+
+```bash
+# 패치 버전 (0.1.0 → 0.1.1)
+npm version patch
+
+# 마이너 버전 (0.1.0 → 0.2.0)
+npm version minor
+
+# 메이저 버전 (0.1.0 → 1.0.0)
+npm version major
+```
+
+### 배포 전 체크리스트
+
+```
+□ 버전 업데이트 완료
+□ CHANGELOG 작성 완료
+□ 테스트 통과 확인
+□ 빌드 성공 확인
+```
+
+---
+
+## 📚 .gitignore
+
+```gitignore
+# Dependencies
+node_modules/
+
+# Build
+dist/
+lib/
+
+# Environment
+.env
+.env.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+
+# Logs
+*.log
+npm-debug.log*
+
+# Cache
+.cache/
+```
+
+---
+
+## 🔗 관련 문서
+
+- [CLAUDE.md](../../CLAUDE.md)