@kood/claude-code 0.4.1 → 0.5.0

package/templates/.claude/commands/version-update.md

@@ -4,89 +4,190 @@ allowed-tools: Bash, Read, Edit
 argument-hint: <new-version | +1 | +minor | +major>
 ---
 
-<critical_instruction>
-
-**CRITICAL: 사용자와의 모든 커뮤니케이션은 반드시 한국어로 작성하세요.**
-
-- 내부 사고와 분석은 영어로 해도 됨
-- 설명, 요약, 보고서, 피드백 등 사용자에게 전달하는 모든 내용은 반드시 한국어
-- 사용자가 영어로 말하더라도 답변은 한국어로
-- 진행 상황 업데이트와 상태 보고는 반드시 한국어
-
-이 규칙은 절대적이며 예외가 없습니다.
-
-</critical_instruction>
-
----
-
-
 @../instructions/git-rules.md
 
 # Version Update Command
 
-Update and commit entire project version.
+프로젝트 전체 버전을 업데이트하고 커밋.
 
-**Argument**: $ARGUMENTS
+**인수**: $ARGUMENTS
 
 <version_rules>
 
-| Argument | Action | Example |
-|----------|--------|---------|
+| 인수 | 동작 | 예시 |
+|------|------|------|
 | `+1` | patch +1 | 0.1.13 → 0.1.14 |
 | `+minor` | minor +1 | 0.1.13 → 0.2.0 |
 | `+major` | major +1 | 0.1.13 → 1.0.0 |
-| `x.x.x` | Set directly | 0.1.13 → 2.0.0 |
+| `x.x.x` | 직접 지정 | 0.1.13 → 2.0.0 |
 
 </version_rules>
 
 <workflow>
 
-1. **Check current version** (parallel read)
-   - packages/claude-code/package.json
-   - packages/claude-code/src/index.ts
+1. **버전 파일 탐색**
+   ```bash
+   # package.json 찾기 (root 또는 monorepo packages/)
+   fd -t f 'package.json' -E node_modules
+
+   # 버전 코드 찾기 (.version() 패턴)
+   rg "\.version\(['\"]" --type ts --type js -l
+   ```
+
+2. **현재 버전 확인** (병렬 읽기)
+   - 발견된 package.json 파일들
+   - 버전 코드 포함 파일들
 
-2. **Calculate new version**
+3. **새 버전 계산**
 
-3. **Update all files with Edit**
+4. **모든 파일 Edit로 업데이트**
 
-4. **Stage files**
+5. **스테이징**
    ```bash
-   git add packages/claude-code/package.json packages/claude-code/src/index.ts
+   git add <발견된-버전-파일들>
    ```
 
-5. **Commit**
+6. **커밋**
    ```bash
-   git commit -m "chore: Update version to X.X.X"
+   git commit -m "chore: 버전 X.X.X로 업데이트"
    ```
 
-6. **Verify completion**
+7. **완료 확인**
    ```bash
    git status
    ```
 
 </workflow>
 
+<parallel_agent_execution>
+
+## Recommended Agents
+
+| Agent | Model | 용도 |
+|-------|-------|------|
+| @git-operator | haiku | 버전 커밋 및 태그 |
+| @document-writer | haiku | CHANGELOG 작성 |
+| @code-reviewer | haiku | 변경사항 검토 |
+
+## Parallel Execution Patterns
+
+```typescript
+// ✅ 문서 작성 병렬 (독립적 작업)
+Task({
+  subagent_type: "document-writer",
+  model: "haiku",
+  prompt: "CHANGELOG.md에 버전 X.X.X 변경사항 추가"
+})
+Task({
+  subagent_type: "document-writer",
+  model: "haiku",
+  prompt: "README.md 버전 정보 업데이트"
+})
+
+// ✅ 검토 + 문서 병렬
+Task({
+  subagent_type: "code-reviewer",
+  model: "haiku",
+  prompt: "버전 업데이트 변경사항 검토"
+})
+Task({
+  subagent_type: "document-writer",
+  model: "haiku",
+  prompt: "CHANGELOG 작성"
+})
+
+// ❌ Git 작업은 순차 필수
+// 버전 커밋 → 태그 생성 → 푸시 순서 보장
+git commit → git tag → git push
+```
+
+## Model Routing
+
+| 복잡도 | 버전 유형 | 모델 | 이유 |
+|--------|----------|------|------|
+| **LOW** | patch (+1) | haiku | 단순 숫자 증가 |
+| **MEDIUM** | minor (+minor) | haiku/sonnet | 기능 추가, 문서 업데이트 |
+| **HIGH** | major (+major) | sonnet | Breaking changes, 마이그레이션 가이드 |
+
+## Practical Examples
+
+```typescript
+// 패치 버전 (haiku 병렬)
+Task({ subagent_type: "document-writer", model: "haiku",
+       prompt: "CHANGELOG: 버그 수정 내역 추가" })
+Task({ subagent_type: "git-operator", model: "haiku",
+       prompt: "버전 0.1.14 커밋" })
+
+// 마이너 버전 (haiku/sonnet 병렬)
+Task({ subagent_type: "document-writer", model: "sonnet",
+       prompt: "CHANGELOG: 새 기능 문서화" })
+Task({ subagent_type: "code-reviewer", model: "haiku",
+       prompt: "API 변경사항 검토" })
+
+// 메이저 버전 (sonnet 순차)
+// 1. Breaking changes 분석 (sonnet)
+// 2. 마이그레이션 가이드 작성 (sonnet)
+// 3. 버전 커밋 (git-operator)
+```
+
+## Git 작업 순서 (순차 필수)
+
+```bash
+# ✅ 올바른 순서
+1. git add [files]
+2. git commit -m "chore: 버전 X.X.X로 업데이트"
+3. git tag vX.X.X
+4. git push origin main
+5. git push origin vX.X.X
+
+# ❌ 병렬 실행 금지
+# Git 작업은 상태 의존성이 있어 순차 실행 필수
+```
+
+</parallel_agent_execution>
+
 <update_targets>
 
-| File | Modification location |
-|------|----------------------|
-| `package.json` | `"version": "x.x.x"` |
-| `src/index.ts` | `.version('x.x.x')` |
+| 파일 패턴 | 수정 위치 | 탐색 명령어 |
+|----------|----------|-------------|
+| `package.json` | `"version": "x.x.x"` | `fd -t f package.json -E node_modules` |
+| `*.ts`, `*.js` | `.version('x.x.x')` | `rg "\.version\(['\"]" --type ts --type js -l` |
+
+**참고**: 프로젝트 구조에 따라 버전 파일 위치가 다를 수 있음. 탐색 명령어로 자동 탐지.
 
 </update_targets>
 
 <examples>
 
 ```bash
+# Patch 버전 증가
 /version-update +1
 → 0.1.13 → 0.1.14
-→ chore: Update version to 0.1.14
+→ chore: 버전 0.1.14로 업데이트
 
+# Minor 버전 증가
 /version-update +minor
 → 0.1.13 → 0.2.0
 
+# 직접 지정
 /version-update 2.0.0
-→ Set directly
+→ 모든 버전 파일을 2.0.0으로 업데이트
+```
+
+**워크플로우 예시:**
+```bash
+# 1. 버전 파일 자동 탐색
+fd -t f package.json -E node_modules
+→ ./package.json
+→ ./packages/core/package.json
+
+rg "\.version\(" --type ts -l
+→ ./packages/core/src/index.ts
+
+# 2. 파일 읽기 및 버전 확인
+# 3. 새 버전 계산 및 Edit
+# 4. git add <발견된-모든-버전-파일>
+# 5. git commit
 ```
 
 </examples>

package/templates/.claude/instructions/context-engineering/ANTHROPIC_CONTEXT_ENGINEERING.md

@@ -0,0 +1,178 @@
+# Context Engineering for Claude
+
+Anthropic 공식 가이드 기반 효과적인 Instructions 작성법.
+
+**Sources:** [Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) · [Claude 4.x Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices) · [XML Tags](https://console.anthropic.com/docs/en/build-with-claude/prompt-engineering/use-xml-tags)
+
+---
+
+<forbidden>
+
+| 분류 | 금지 |
+|------|------|
+| **설명** | 장황한 설명, Claude가 아는 것 반복 |
+| **구조** | 중복 정보, 모호한 지시사항 |
+| **표현** | 부정형 ("Don't X"), 과도한 강조 (CRITICAL 남발) |
+| **복잡도** | 복잡한 조건문, 모든 엣지 케이스 나열 |
+
+</forbidden>
+
+---
+
+<required>
+
+| 분류 | 필수 |
+|------|------|
+| **구조** | XML 태그 섹션 구분, 명확한 계층 |
+| **표현** | 표 형식 압축, ✅/❌ 마커 |
+| **예시** | 코드 중심, 복사 가능 패턴 |
+| **로딩** | @imports로 just-in-time 로딩 |
+| **지시** | 긍정형 명시적 지시 |
+
+</required>
+
+---
+
+<core_principles>
+
+| 원칙 | 방법 |
+|------|------|
+| **Right Altitude** | 명확한 원칙 + 예시 (조건문/엣지케이스 나열 ❌) |
+| **Just-in-Time** | 필요 시점에만 정보 제공 (중복 제거) |
+| **Explicit** | "Create X. Include Y and Z." (모호한 지시 ❌) |
+
+**Details:** [references/core-principles.md](references/core-principles.md)
+
+</core_principles>
+
+---
+
+<xml_patterns>
+
+```xml
+<!-- Instructions -->
+<instructions>@path/to/guide.md</instructions>
+
+<!-- Rules -->
+<forbidden>절대 금지</forbidden>
+<required>반드시 필수</required>
+
+<!-- Examples -->
+<examples>
+  <example>
+    <input>Input</input>
+    <output>Output</output>
+  </example>
+</examples>
+
+<!-- Thinking -->
+<thinking>추론 과정</thinking>
+<answer>최종 답변</answer>
+
+<!-- Behavior -->
+<default_to_action>Implement directly</default_to_action>
+```
+
+</xml_patterns>
+
+---
+
+<techniques>
+
+| 기법 | 사용 시점 | 패턴 |
+|------|----------|------|
+| **CoT** | 복잡한 수학, 다단계 분석 | `<thinking>` → `<answer>` |
+| **Extended** | 4D 시각화, 제약 최적화 | "철저히 생각. 여러 접근법 고려" (1024+ 토큰) |
+
+**Details:** [references/techniques.md](references/techniques.md)
+
+</techniques>
+
+---
+
+<claude_4x>
+
+```xml
+<!-- 명시적 지시 -->
+"Create dashboard. Include as many features as possible."
+
+<!-- 행동 제어 -->
+<default_to_action>Implement directly</default_to_action>
+<use_parallel_tool_calls>true</use_parallel_tool_calls>
+```
+
+**Details:** [references/claude-4x.md](references/claude-4x.md)
+
+</claude_4x>
+
+---
+
+<quick_patterns>
+
+```text
+✅ "Create X with Y and Z" (명시적)
+✅ 원하는 패턴 예시 코드
+✅ XML/표로 구조화
+
+❌ "Don't X" → ✅ "Do Y" (긍정형)
+❌ "If X then Y, unless..." → ✅ "[예시] 패턴"
+❌ CRITICAL 남발 → ✅ 일반 지시
+```
+
+</quick_patterns>
+
+---
+
+<document_template>
+
+```xml
+# Title
+
+<instructions>@path/to/guides.md</instructions>
+
+<forbidden>
+[표 형식 금지]
+</forbidden>
+
+<required>
+[표 형식 필수]
+</required>
+
+<patterns>
+[복사 가능 코드]
+</patterns>
+```
+
+| 위치 | 내용 | 크기 |
+|------|------|------|
+| 메인 | 핵심 + 요약 | 300줄 이하 |
+| references/ | 상세 가이드 | 무제한 |
+
+</document_template>
+
+---
+
+<examples>
+
+```xml
+<!-- Coding -->
+<investigation>Read files before edits</investigation>
+<implementation>Only requested changes</implementation>
+
+<!-- Frontend -->
+<aesthetics>Creative, distinctive (avoid generic AI look)</aesthetics>
+```
+
+**More:** [references/examples.md](references/examples.md)
+
+</examples>
+
+---
+
+<sources>
+
+**EN:** [Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) · [Claude 4.x](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices) · [XML Tags](https://console.anthropic.com/docs/en/build-with-claude/prompt-engineering/use-xml-tags)
+
+**KO:** [XML 태그](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/use-xml-tags) · [CoT](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/chain-of-thought) · [Extended Thinking](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/extended-thinking-tips)
+
+</sources>

package/templates/.claude/instructions/context-engineering/references/claude-4x.md

@@ -0,0 +1,215 @@
+# Claude 4.x Specifics
+
+Claude 4.x 모델의 특징과 효과적 사용법.
+
+## 핵심 차이점
+
+### Precise Instruction Following
+
+Claude 4.x는 **문자 그대로** 지시를 따름.
+
+| 상황 | Claude 3.x | Claude 4.x |
+|------|-----------|-----------|
+| "Create dashboard" | 추가 기능 자동 포함 | 최소한만 구현 |
+| "Suggest changes" | 때때로 바로 구현 | 제안만 |
+| "Fix bug" | 주변 코드도 개선 | 버그만 수정 |
+| "Add feature X" | X + 관련 기능들 | X만 |
+
+**결론:** 더 명시적으로 작성 필요.
+
+---
+
+## Action Control
+
+### 적극적 행동 유도
+
+```xml
+<default_to_action>
+Implement changes directly rather than suggesting.
+When you identify an issue, fix it immediately.
+Go beyond the minimum to create comprehensive solutions.
+</default_to_action>
+```
+
+**사용 시점:**
+- 빠른 프로토타이핑
+- 완전한 구현 원할 때
+- 제안보다 실행 선호
+
+### 보수적 행동 유도
+
+```xml
+<do_not_act_before_instructions>
+Wait for explicit user instruction before taking action.
+Only suggest changes, never implement without confirmation.
+Ask for permission before modifying files.
+</do_not_act_before_instructions>
+```
+
+**사용 시점:**
+- 민감한 코드베이스
+- 검토 필요한 변경
+- 탐색적 작업
+
+---
+
+## Parallel Tool Calling
+
+독립적 도구 호출을 병렬로 실행.
+
+```xml
+<use_parallel_tool_calls>
+Call independent tools in parallel for maximum speed.
+If operations don't depend on each other, run them simultaneously.
+</use_parallel_tool_calls>
+```
+
+### 예시
+
+```text
+❌ 순차 실행 (느림)
+1. Read file1.ts
+2. Read file2.ts
+3. Read file3.ts
+
+✅ 병렬 실행 (빠름)
+Read [file1.ts, file2.ts, file3.ts] 동시에
+```
+
+---
+
+## Explicit Instruction Patterns
+
+### 기능 구현
+
+```text
+❌ "Create user profile page"
+✅ "Create comprehensive user profile page:
+   - Avatar upload with preview
+   - Editable fields (name, email, bio)
+   - Password change form
+   - Activity history
+   - Settings panel
+   Include all standard profile features."
+```
+
+### 최적화
+
+```text
+❌ "Optimize this component"
+✅ "Optimize this component. Apply:
+   - useMemo for expensive calculations
+   - useCallback for event handlers
+   - React.memo for child components
+   - Code splitting if bundle > 100kb
+   - Lazy loading for images
+   Maximize performance improvements."
+```
+
+### 리팩토링
+
+```text
+❌ "Refactor this code"
+✅ "Refactor this code to improve:
+   - Extract reusable logic into hooks
+   - Separate concerns into modules
+   - Add TypeScript types
+   - Improve naming clarity
+   - Remove code duplication
+   Follow modern React patterns."
+```
+
+---
+
+## Completeness Control
+
+### 최소 구현 방지
+
+```xml
+<avoid_minimal_implementation>
+Don't create placeholder or minimal implementations.
+Build complete, production-ready solutions.
+Include error handling, loading states, and edge cases.
+</avoid_minimal_implementation>
+```
+
+### 예시
+
+```text
+❌ Minimal (Claude 4.x 기본)
+const Profile = () => {
+  return <div>Profile</div>
+}
+
+✅ Complete (명시 후)
+const Profile = () => {
+  const { data, isLoading, error } = useQuery(...)
+
+  if (isLoading) return <Spinner />
+  if (error) return <ErrorMessage error={error} />
+
+  return (
+    <div>
+      <Avatar src={data.avatar} />
+      <UserInfo user={data} />
+      <ActivityFeed activities={data.activities} />
+    </div>
+  )
+}
+```
+
+---
+
+## Testing & Validation
+
+### 자동 테스트 생성
+
+```text
+❌ "Add tests"
+✅ "Add comprehensive tests:
+   - Unit tests for all functions
+   - Integration tests for API calls
+   - Component tests for UI
+   - Edge cases and error scenarios
+   - Mock external dependencies
+   Aim for 80%+ code coverage."
+```
+
+### 검증 단계 추가
+
+```xml
+<verify_implementation>
+After implementing, verify:
+- All requirements met
+- Edge cases handled
+- Tests passing
+- No TypeScript errors
+- Performance acceptable
+</verify_implementation>
+```
+
+---
+
+## Anti-Patterns
+
+```text
+❌ "Make it better" → 아무것도 안 함 (모호함)
+✅ "Improve by adding X, Y, Z features"
+
+❌ "Fix issues" → 최소한만
+✅ "Fix all issues. Address root causes. Add safeguards."
+
+❌ "Update design" → 최소 변경
+✅ "Update design completely. Modern UI. Smooth animations."
+```
+
+---
+
+## 요약
+
+| 규칙 | 방법 |
+|------|------|
+| **명시성** | "Create X with Y and Z" |
+| **행동 제어** | `<default_to_action>` or `<do_not_act>` |
+| **병렬화** | `<use_parallel_tool_calls>` |
+| **완전성** | "Include all features. Go beyond basics." |