@kood/claude-code 0.4.0 → 0.5.0

package/templates/.claude/instructions/context-engineering/references/core-principles.md

@@ -0,0 +1,137 @@
+# Core Principles - 상세 가이드
+
+## 1. Find the Right Altitude
+
+적절한 추상화 수준 찾기.
+
+### 수준별 비교
+
+| ❌ Too Low | ✅ Right Altitude | ❌ Too High |
+|-----------|------------------|-------------|
+| 복잡한 조건문 | 명확한 원칙 + 예시 | 모호한 지시 |
+| 모든 엣지 케이스 나열 | 핵심 패턴 제공 | 구체성 부족 |
+| "If X then Y, unless Z..." | "Follow pattern: [코드]" | "잘 만들어줘" |
+
+### 예시: API 에러 처리
+
+```text
+❌ Too Low:
+"If status === 400, check error.code. If code === 'INVALID_INPUT',
+show field-specific errors. If code === 'VALIDATION_ERROR',
+check error.fields array. For each field..."
+
+✅ Right Altitude:
+"Handle API errors with appropriate user messages.
+Example:
+  400 → Show field errors
+  401 → Redirect to login
+  500 → Show generic error"
+
+❌ Too High:
+"적절히 에러 처리해줘"
+```
+
+---
+
+## 2. Context as Finite Resource
+
+컨텍스트는 제한된 자원.
+
+### Just-in-Time Loading
+
+| 전략 | 방법 | 효과 |
+|------|------|------|
+| **@imports** | 필요한 시점에만 로드 | 90%+ 절약 |
+| **references/** | 상세 문서 분리 | 메인 파일 간결 |
+| **Subagent** | 조사 작업 위임 | 요약만 반환 |
+
+### Minimal Start
+
+```text
+1차 시도: 최소 프롬프트
+  ↓ 실패
+2차 시도: 예시 1개 추가
+  ↓ 실패
+3차 시도: 제약사항 명시
+```
+
+**Bad:** 처음부터 모든 조건 나열
+
+### Token Minimization
+
+```text
+❌ "Use TypeScript for type safety and better development experience"
+✅ "TypeScript"
+
+❌ "Create a new file called utils.ts and add helper functions"
+✅ "utils.ts: helper functions"
+
+❌ 중복 설명
+✅ 표 형식 압축
+```
+
+---
+
+## 3. Explicit > Implicit (Claude 4.x)
+
+명시적 지시가 핵심.
+
+### Claude 4.x 특징
+
+| 상황 | Claude 3.x | Claude 4.x |
+|------|-----------|-----------|
+| "Create dashboard" | 추가 기능 자동 포함 | 최소한만 구현 |
+| "Suggest changes" | 때때로 바로 구현 | 제안만 |
+| "Fix bug" | 주변 코드도 개선 | 버그만 수정 |
+
+### 명시적 지시 패턴
+
+```text
+❌ "Create dashboard"
+✅ "Create dashboard. Include:
+   - User stats cards
+   - Activity timeline
+   - Quick actions
+   - Recent notifications
+   Go beyond basics to create fully-featured UI."
+
+❌ "Optimize this"
+✅ "Optimize this. Consider:
+   - Memoization for expensive calculations
+   - Lazy loading for off-screen content
+   - Code splitting for large bundles
+   Apply all applicable optimizations."
+
+❌ "Add tests"
+✅ "Add comprehensive tests:
+   - Unit tests for each function
+   - Integration tests for API calls
+   - Edge cases and error scenarios
+   Aim for 80%+ coverage."
+```
+
+### Behavior Control
+
+```xml
+<!-- 적극적 행동 -->
+<default_to_action>
+Implement changes directly rather than suggesting.
+When you see an opportunity for improvement, apply it.
+</default_to_action>
+
+<!-- 보수적 행동 -->
+<do_not_act_before_instructions>
+Wait for explicit user instruction before taking action.
+Only suggest, never implement without confirmation.
+</do_not_act_before_instructions>
+```
+
+---
+
+## 요약
+
+| 원칙 | 핵심 |
+|------|------|
+| Right Altitude | 패턴 + 예시 (조건문 ❌) |
+| Finite Resource | Just-in-Time, 최소화 |
+| Explicit | "Create X with Y and Z" (모호함 ❌) |

package/templates/.claude/instructions/context-engineering/references/examples.md

@@ -0,0 +1,351 @@
+# Examples - 실전 패턴
+
+## Agentic Coding
+
+```xml
+<coding_guidelines>
+
+<investigation>
+ALWAYS read files before proposing edits.
+Use Explore agent for codebase discovery.
+Do not speculate about code structure.
+</investigation>
+
+<implementation>
+Avoid over-engineering.
+Only make directly requested changes.
+Don't add features unless asked.
+Keep solutions simple and focused.
+</implementation>
+
+<testing>
+Run tests after changes.
+Verify no regressions.
+Add new tests for new features.
+</testing>
+
+</coding_guidelines>
+```
+
+---
+
+## Frontend Design
+
+```xml
+<frontend_aesthetics>
+
+Avoid generic "AI slop" aesthetic.
+Make creative, distinctive frontends that stand out.
+
+<focus>
+
+**Typography**
+- Unique font combinations
+- Avoid overused fonts (Inter, Roboto)
+- Consider: Geist, Cal Sans, Untitled Sans
+
+**Color**
+- Cohesive theme with sharp accents
+- Use color psychology
+- Dark mode by default (better aesthetics)
+
+**Motion**
+- High-impact animations (Framer Motion, GSAP)
+- Smooth transitions
+- Micro-interactions
+
+**Backgrounds**
+- Depth and atmosphere
+- Gradients, meshes, noise
+- Avoid flat single colors
+
+</focus>
+
+<frameworks>
+- TailwindCSS for utility-first
+- shadcn/ui for components
+- Framer Motion for animations
+</frameworks>
+
+</frontend_aesthetics>
+```
+
+---
+
+## API Design
+
+```xml
+<api_guidelines>
+
+<rest_patterns>
+
+**Naming**
+- Resource-oriented: `/users/:id/posts`
+- Kebab-case: `/user-profiles`
+- Versioning: `/api/v1/...`
+
+**Methods**
+- GET: Read (safe, idempotent)
+- POST: Create
+- PUT: Full update (idempotent)
+- PATCH: Partial update
+- DELETE: Remove (idempotent)
+
+**Responses**
+200 OK: Success
+201 Created: Resource created
+400 Bad Request: Invalid input
+401 Unauthorized: Auth required
+404 Not Found: Resource missing
+500 Internal Error: Server error
+
+</rest_patterns>
+
+<validation>
+- Validate at boundary (input validators)
+- Use Zod/Yup schemas
+- Return detailed error messages
+- Never trust client input
+</validation>
+
+</api_guidelines>
+```
+
+---
+
+## Database Schema
+
+```xml
+<schema_design>
+
+<naming>
+- Tables: plural (`users`, `posts`)
+- Columns: snake_case (`created_at`)
+- Foreign keys: `{table}_id` (`user_id`)
+- Indexes: `idx_{table}_{column}`
+</naming>
+
+<relationships>
+- One-to-Many: Foreign key on "many" side
+- Many-to-Many: Junction table
+- Cascade deletes: Be explicit
+</relationships>
+
+<best_practices>
+- Always use timestamps (`created_at`, `updated_at`)
+- Soft deletes: `deleted_at` (optional)
+- UUID vs Auto-increment: Consider scale
+- Index frequently queried columns
+</best_practices>
+
+</schema_design>
+```
+
+---
+
+## Error Handling
+
+```xml
+<error_patterns>
+
+**Client-Side (React)**
+```typescript
+try {
+  const data = await api.fetch()
+  return data
+} catch (error) {
+  if (error.status === 401) {
+    redirect('/login')
+  }
+  toast.error(error.message)
+  throw error // Re-throw for React Query
+}
+```
+
+**Server-Side (API)**
+```typescript
+try {
+  const result = await db.query()
+  return result
+} catch (error) {
+  logger.error(error)
+  if (error instanceof ValidationError) {
+    throw new HttpError(400, error.message)
+  }
+  throw new HttpError(500, 'Internal error')
+}
+```
+
+**User-Facing Messages**
+- Technical: "DatabaseConnectionError"
+- User: "서비스 일시 중단. 잠시 후 다시 시도해주세요."
+
+</error_patterns>
+```
+
+---
+
+## Testing Patterns
+
+```xml
+<test_guidelines>
+
+**Unit Tests**
+```typescript
+describe('calculateTotal', () => {
+  it('sums item prices', () => {
+    expect(calculateTotal([10, 20])).toBe(30)
+  })
+
+  it('handles empty array', () => {
+    expect(calculateTotal([])).toBe(0)
+  })
+})
+```
+
+**Integration Tests**
+```typescript
+describe('POST /api/users', () => {
+  it('creates user', async () => {
+    const res = await request(app)
+      .post('/api/users')
+      .send({ name: 'John' })
+
+    expect(res.status).toBe(201)
+    expect(res.body.name).toBe('John')
+  })
+})
+```
+
+**Component Tests**
+```typescript
+test('renders user profile', () => {
+  render(<Profile user={mockUser} />)
+  expect(screen.getByText('John')).toBeInTheDocument()
+})
+```
+
+</test_guidelines>
+```
+
+---
+
+## Git Commit Messages
+
+```xml
+<commit_style>
+
+**Format**
+```
+<type>: <subject>
+
+[optional body]
+```
+
+**Types**
+- feat: New feature
+- fix: Bug fix
+- refactor: Code restructure
+- style: Formatting
+- docs: Documentation
+- test: Tests
+- chore: Maintenance
+
+**Examples**
+```
+feat: add user authentication
+fix: resolve login redirect loop
+refactor: extract auth logic to hook
+docs: update API documentation
+```
+
+**Rules**
+- Subject: 50 chars max
+- Imperative mood ("add" not "added")
+- No period at end
+- One logical change per commit
+
+</commit_style>
+```
+
+---
+
+## Security Patterns
+
+```xml
+<security>
+
+**Input Validation**
+- Sanitize all user input
+- Use parameterized queries (prevent SQL injection)
+- Validate file uploads (type, size)
+- Escape HTML output (prevent XSS)
+
+**Authentication**
+- Hash passwords (bcrypt, argon2)
+- Use secure session tokens
+- Implement rate limiting
+- Add CSRF protection
+
+**API Security**
+- API keys in env vars
+- HTTPS only
+- CORS configuration
+- Input size limits
+
+**Never**
+- Store passwords in plain text
+- Trust client-side validation
+- Expose sensitive data in errors
+- Use deprecated crypto
+
+</security>
+```
+
+---
+
+## Performance Optimization
+
+```xml
+<performance>
+
+**React**
+```typescript
+// Memoization
+const expensiveValue = useMemo(() =>
+  heavyCalculation(data), [data]
+)
+
+// Callback stability
+const handleClick = useCallback(() => {
+  doSomething(id)
+}, [id])
+
+// Component memoization
+export default React.memo(ExpensiveComponent)
+```
+
+**Code Splitting**
+```typescript
+const Heavy = lazy(() => import('./Heavy'))
+
+<Suspense fallback={<Spinner />}>
+  <Heavy />
+</Suspense>
+```
+
+**API**
+- Pagination: Limit results
+- Caching: Redis, CDN
+- N+1 queries: Use JOIN or DataLoader
+- Compression: gzip, brotli
+
+</performance>
+```
+
+---
+
+## 요약
+
+모든 예시는 **복사 가능**하도록 작성.
+패턴을 그대로 적용하고, 프로젝트에 맞게 조정.

package/templates/.claude/instructions/context-engineering/references/techniques.md

@@ -0,0 +1,162 @@
+# Techniques - Chain of Thought & Extended Thinking
+
+## Chain of Thought (CoT)
+
+단계별 사고 유도 → 정확성 향상.
+
+### 3단계 수준
+
+| Level | Method | When | Example |
+|-------|--------|------|---------|
+| **Basic** | "단계별로 생각하세요" | 간단한 작업 | 단순 계산 |
+| **Guided** | 구체적 단계 제공 | 중간 복잡도 | 데이터 분석 |
+| **Structured** | `<thinking>` 태그 | 복잡한 작업 | 아키텍처 설계 |
+
+### Structured Pattern (권장)
+
+```xml
+<thinking>
+1. 문제 분석
+   - 현재 상태 파악
+   - 요구사항 정리
+
+2. 접근 방법
+   - 가능한 옵션들
+   - 장단점 비교
+
+3. 단계별 추론
+   - 선택한 방법
+   - 구현 단계
+
+4. 검증
+   - 예상 결과
+   - 잠재적 문제
+</thinking>
+
+<answer>
+최종 답변
+</answer>
+```
+
+### 언제 사용?
+
+```text
+✅ 사용하면 좋음
+- 복잡한 수학 문제
+- 다단계 분석
+- 의사결정 (여러 옵션 비교)
+- 디버깅 (원인 추적)
+- 아키텍처 설계
+
+❌ 사용 안 함
+- 단순 검색
+- 단순 변환 (JSON → CSV)
+- 지연 시간 중요 (실시간)
+- 사실 확인
+```
+
+### 예시: 디버깅
+
+```xml
+<thinking>
+1. 문제 증상
+   - 로그인 후 리다이렉트 안 됨
+   - 콘솔 에러 없음
+
+2. 가능한 원인
+   A. 라우터 설정 문제
+   B. 인증 상태 미반영
+   C. 비동기 타이밍 이슈
+
+3. 검증
+   - A: 라우터 설정 정상 (routes.ts 확인)
+   - B: useAuth() 훅 체크 → 상태 업데이트 안 됨!
+   - C: 패스
+
+4. 결론
+   - 로그인 성공 후 auth store 업데이트 누락
+</thinking>
+
+<answer>
+`login.ts`의 `handleLogin` 함수에서
+`authStore.setUser(user)` 호출 추가 필요.
+</answer>
+```
+
+---
+
+## Extended Thinking
+
+긴 추론 시간으로 복잡한 문제 해결.
+
+### 특징
+
+- 최소 1024 토큰 사고 예산
+- 모델이 스스로 탐색
+- 고도로 복잡한 문제에 적합
+
+### Best Practices
+
+```text
+❌ 단계별 지시 (제한적)
+"1. 변수 식별
+ 2. 방정식 세우기
+ 3. 풀이
+ 4. 검증"
+
+✅ 일반적 지시 (자유로움)
+"철저히 생각하세요.
+ 여러 접근법을 고려하고,
+ 각각의 장단점을 평가하세요."
+
+⚠️ 최소 토큰: 1024
+⚠️ 32K+ 예산: Batch Processing 권장
+```
+
+### 사용 시점
+
+| Use Case | Example | 왜 Extended? |
+|----------|---------|-------------|
+| **복잡한 STEM** | 4D 시각화, 고급 물리 문제 | 다단계 추상화 |
+| **제약 최적화** | 다중 제약 여행 계획 | 조합 탐색 |
+| **사고 프레임워크** | Porter's 5 Forces + 시나리오 분석 | 구조적 사고 |
+| **창의적 문제해결** | 새로운 알고리즘 설계 | 탐색적 사고 |
+
+### 예시: 최적화 문제
+
+```text
+Prompt:
+"3일 일정으로 유럽 5개 도시 방문 계획.
+ 제약:
+ - 예산: $2000
+ - 비행 시간 최소화
+ - 주요 관광지 3곳씩
+ - 비자 불필요 국가
+
+ 철저히 생각하세요. 여러 경로를 고려하고,
+ 비용/시간/경험 측면에서 최적 조합을 찾으세요."
+
+→ Extended Thinking이 여러 조합 탐색 후 최적안 제시
+```
+
+---
+
+## CoT vs Extended
+
+| 측면 | CoT | Extended |
+|------|-----|----------|
+| **복잡도** | 중간 (3-5 단계) | 매우 높음 (10+ 단계) |
+| **토큰** | 100-500 | 1024+ |
+| **제어** | 구조화된 단계 | 자유로운 탐색 |
+| **속도** | 빠름 | 느림 |
+| **사용** | 일반적 문제 | 극도로 복잡한 문제 |
+
+---
+
+## 요약
+
+```text
+간단 → 직접 답변
+중간 → CoT (<thinking>)
+복잡 → Extended Thinking (1024+)
+```