jun-claude-code 0.6.2 → 0.6.4

package/templates/global/skills/Planning/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: Planning
+description: 개발 계획 문서(plan.md, context.md, checklist.md) 작성 템플릿. DB/API/FE 설계와 의사결정 근거 포함.
+keywords: [plan, 계획, DB설계, API구성, FE플로우, 의사결정, 차선책, planning, 마이그레이션]
+user-invocable: true
+context: fork
+agent: task-planner
+---
+
+# 개발 계획 문서 작성 스킬
+
+> `.claude/plan/` 폴더에 작성하는 3개 문서의 템플릿과 작성 규칙을 정의한다.
+
+## Plan 문서 개요
+
+| 문서 | 역할 | 핵심 내용 |
+|------|------|----------|
+| `plan.md` | 전체 설계 문서 | 목적, DB/API/FE 설계, 설계 결정, TaskList |
+| `context.md` | 맥락 기록 | 사용자 요청 원문, 비즈니스/기술 배경, 탐색한 코드 |
+| `checklist.md` | 실행 추적 | Phase별 체크리스트, Task별 세부 작업 |
+
+### 문서 생명주기
+
+```
+draft → confirmed → in-progress → done
+```
+
+| 상태 | 의미 | 전환 시점 |
+|------|------|----------|
+| `draft` | 초안 작성 중 | 문서 생성 시 |
+| `confirmed` | 사용자 승인 완료 | 사용자 Confirm 후 |
+| `in-progress` | 구현 진행 중 | Phase 3 시작 시 |
+| `done` | 작업 완료 | 모든 Task 완료 시 |
+
+> Stop Hook에서 `plan.md`와 `checklist.md`를 참조하여 진행 상황을 추적한다.
+
+---
+
+<instructions>
+
+## plan.md 템플릿
+
+> 전체 설계를 담는 핵심 문서. 목적, 설계 결정, TaskList를 한 곳에 정리한다.
+
+### Frontmatter
+
+```yaml
+---
+name: [작업명]-plan
+description: [작업명] 개발 계획
+created: YYYY-MM-DD
+status: draft  # draft | confirmed | in-progress | done
+---
+```
+
+### 전체 구조
+
+```markdown
+# [작업명] Plan
+
+## 목적 (Why)
+- 목적: [이 작업을 왜 하는가]
+- 문제: [어떤 문제를 해결하는가]
+- 방법: [어떻게 해결할 것인가]
+
+## DB 수정 계획
+### 테이블 변경
+| 테이블 | 변경 유형 | 컬럼 | 타입 | 설명 |
+|--------|----------|------|------|------|
+| users  | ADD      | role | varchar(20) | 사용자 역할 |
+
+### 마이그레이션 순서
+1. [첫 번째 마이그레이션]
+2. [두 번째 마이그레이션]
+
+### 설계 결정
+- **선택:** [채택한 방안]
+- **이유:** [왜 이 방안을 선택했는지]
+- **차선책:** [고려했지만 선택하지 않은 방안]
+- **차선책 미채택 이유:** [왜 차선책을 선택하지 않았는지]
+
+## API 구성
+### 엔드포인트 목록
+| Method | Path | 설명 | Request | Response |
+|--------|------|------|---------|----------|
+| POST   | /api/users | 사용자 생성 | CreateUserDto | UserResponse |
+
+### 각 API 상세
+#### POST /api/users
+- Request Body: ...
+- Response: ...
+- 에러 케이스: ...
+
+### 설계 결정
+- **선택:** [채택한 방안]
+- **이유:** [왜 이 방안을 선택했는지]
+- **차선책:** [고려했지만 선택하지 않은 방안]
+- **차선책 미채택 이유:** [왜 차선책을 선택하지 않았는지]
+
+## FE 페이지 Flow
+### 화면 목록
+| 페이지 | 경로 | 설명 |
+|--------|------|------|
+| 사용자 목록 | /users | 사용자 리스트 조회 |
+
+### 페이지 흐름도
+[목록] -> [상세] -> [수정]
+          ↓
+        [삭제 확인 모달]
+
+### 컴포넌트 구조
+UserListPage
+├── UserTable
+│   └── UserRow
+├── UserSearchBar
+└── Pagination
+
+### 설계 결정
+- **선택:** [채택한 방안]
+- **이유:** [왜 이 방안을 선택했는지]
+- **차선책:** [고려했지만 선택하지 않은 방안]
+- **차선책 미채택 이유:** [왜 차선책을 선택하지 않았는지]
+
+## 설계 결정 요약
+| 영역 | 결정 | 이유 | 차선책 |
+|------|------|------|--------|
+
+## TaskList 요약
+| Task | 설명 | 의존성 |
+|------|------|--------|
+```
+
+</instructions>
+
+---
+
+<instructions>
+
+## context.md 템플릿
+
+> 작업의 맥락을 기록하여 구현 중 목적 희석을 방지한다.
+
+### Frontmatter
+
+```yaml
+---
+name: [작업명]-context
+description: [작업명] 작업 맥락
+created: YYYY-MM-DD
+---
+```
+
+### 전체 구조
+
+```markdown
+# [작업명] Context
+
+## 사용자 요청 원문
+> (원문 그대로 인용)
+
+## 비즈니스 배경
+- 왜 이 작업이 필요한가
+- 비즈니스 제약 조건
+
+## 기술적 배경
+- 현재 아키텍처 상태
+- 관련 기존 코드/모듈
+
+## 탐색한 코드
+| 파일 | 관련 내용 |
+|------|----------|
+
+## 결정 사항
+| 결정 | 근거 | 일시 |
+|------|------|------|
+```
+
+</instructions>
+
+---
+
+<instructions>
+
+## checklist.md 템플릿
+
+> Phase별 진행 상황을 추적하고, Task별 세부 작업을 관리한다.
+
+### Frontmatter
+
+```yaml
+---
+name: [작업명]-checklist
+description: [작업명] 실행 체크리스트
+created: YYYY-MM-DD
+---
+```
+
+### 전체 구조
+
+```markdown
+# [작업명] Checklist
+
+## Phase 1: 계획
+- [x] 목적 확인
+- [x] Context 수집
+- [x] Plan 문서 작성
+
+## Phase 2: 검증
+- [ ] Code Flow 분석
+- [ ] UserFlow 분석
+- [ ] Breaking Change 확인
+
+## Phase 3: 구현
+### Task 1: [제목]
+- [ ] 세부 작업 1
+- [ ] 세부 작업 2
+- [ ] 커밋
+
+### Task 2: [제목]
+- [ ] 세부 작업 1
+- [ ] 세부 작업 2
+- [ ] 커밋
+
+## Phase 4: 리뷰
+- [ ] 전체 요구사항 충족 확인
+- [ ] 엣지케이스 점검
+```
+
+</instructions>
+
+---
+
+<rules>
+
+## 설계 결정(Decision) 작성 규칙
+
+> 모든 설계 결정에는 "왜 이것을 선택했고, 왜 다른 것을 선택하지 않았는가"를 명시한다.
+
+### 필수 항목
+
+| 항목 | 설명 | 필수 |
+|------|------|------|
+| 선택 (What) | 무엇을 채택했는가 | 필수 |
+| 이유 (Why) | 왜 이것을 선택했는가 | 필수 |
+| 차선책 (Alternative) | 어떤 대안을 검토했는가 | 필수 |
+| 차선책 미채택 이유 (Why Not) | 왜 차선책을 선택하지 않았는가 | 필수 |
+| 트레이드오프 (Tradeoff) | 현재 선택의 단점은 무엇인가 | 선택 |
+
+### 작성 형식
+
+```markdown
+- **선택:** JSON 컬럼 대신 별도 테이블로 분리
+- **이유:** 검색/인덱싱 성능과 스키마 변경 유연성 확보
+- **차선책:** JSON 컬럼으로 저장
+- **차선책 미채택 이유:** 복잡한 쿼리 시 성능 저하, 타입 안정성 부족
+- **트레이드오프:** JOIN 비용 증가 (캐싱으로 완화 가능)
+```
+
+### 적용 범위
+
+> DB, API, FE 모든 영역의 설계 결정에 이 형식을 동일하게 적용한다.
+
+| 영역 | 설계 결정 예시 |
+|------|--------------|
+| DB | 테이블 구조, 인덱스 전략, 정규화 수준 |
+| API | 엔드포인트 설계, 인증 방식, 에러 처리 전략 |
+| FE | 상태 관리 방식, 컴포넌트 구조, 라우팅 전략 |
+
+</rules>
+
+---
+
+<rules>
+
+## 선택적 섹션 규칙
+
+> 모든 프로젝트에 DB/API/FE가 모두 존재하는 것은 아니다. 해당 영역이 있는 섹션만 선택하여 작성한다.
+
+### 최소 필수 섹션
+
+| 섹션 | 필수 여부 | 설명 |
+|------|----------|------|
+| 목적 (Why) | 필수 | 항상 포함 |
+| 설계 결정 요약 | 필수 | 항상 포함 |
+| TaskList 요약 | 필수 | 항상 포함 |
+| DB 수정 계획 | 선택 | DB 변경이 있을 때만 |
+| API 구성 | 선택 | API 변경이 있을 때만 |
+| FE 페이지 Flow | 선택 | FE 변경이 있을 때만 |
+
+### 영역별 선택 기준
+
+```
+DB 변경 있음  → DB 수정 계획 섹션 포함
+API 변경 있음 → API 구성 섹션 포함
+FE 변경 있음  → FE 페이지 Flow 섹션 포함
+해당 없음     → 섹션 생략
+```
+
+</rules>
+
+---
+
+<checklist>
+
+## Plan 문서 작성 시 검증
+
+- [ ] plan.md에 목적(Why) 섹션이 있는가?
+- [ ] 각 설계 결정에 이유와 차선책이 명시되어 있는가?
+- [ ] context.md에 사용자 요청 원문이 인용되어 있는가?
+- [ ] checklist.md에 Task별 세부 작업이 있는가?
+- [ ] status 필드가 올바르게 설정되어 있는가?
+- [ ] 선택적 섹션이 프로젝트에 맞게 포함/생략되어 있는가?
+- [ ] 설계 결정에 트레이드오프가 기록되어 있는가? (선택 사항이지만 권장)
+
+</checklist>
+
+---
+
+<reference>
+
+## 관련 문서
+
+| 문서 | 설명 |
+|------|------|
+| `CLAUDE.md` 워크플로우 | Plan 문서 생성 시점 (Step 1.5.5) |
+| `.claude/skills/Documentation/SKILL.md` | 문서 작성 공통 규칙 |
+| `.claude/skills/PromptStructuring/SKILL.md` | XML 태그 구조화 가이드 |
+
+</reference>

package/templates/global/skills/PromptStructuring/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: PromptStructuring
-description: "Claude Code 프롬프트의 XML 태그 구조화, 긍정 표현 전환, 출력 최적화 가이드"
-keywords: [prompt, xml-tags, positive-phrasing, output-optimization, 프롬프트, 구조화, 긍정표현, XML, 출력최적화]
+description: ".claude/skills/ 또는 .claude/agents/ 하위 파일을 생성·수정할 때 반드시 이 Skill을 읽고 규칙을 적용한다. XML 태그 구조화, 긍정 표현, 출력 최적화, Skills 2.0 frontmatter(context:fork, agent, hooks, skills preload) 스펙 포함."
+keywords: [prompt, xml-tags, positive-phrasing, output-optimization, 프롬프트, 구조화, 긍정표현, XML, 출력최적화, frontmatter, SKILL.md, agent.md, skills-2.0, hooks, context-fork, skills-preload]
 user-invocable: false
 ---
 
 # 프롬프트 구조화 스킬
 
-프롬프트의 형식과 표현 방식은 LLM 출력 품질에 직접적인 영향을 준다.
+> Skill, Agent, Hook 파일 작성/수정 시 이 스킬의 규칙을 적용한다.
 
 ## 핵심 원칙
 
@@ -17,4 +17,14 @@ user-invocable: false
 | 2. 긍정 표현 | "~금지" 대신 "~한다"로 행동 직접 유도 | `positive-phrasing.md` |
 | 3. 흐름 기호 | 단계/변환/위임에 `->` 사용: 계획 -> 구현 -> 검증 | - |
 | 4. 출력 최적화 | 반복 제거, 테이블 > 산문, Hook 출력 150줄 이내 | `output-optimization.md` |
-| 5. Frontmatter | Skill/Agent YAML frontmatter 필드 선택과 작성 기준 | `skills-frontmatter.md` |
+| 5. Skills 2.0 Frontmatter | Skill/Agent YAML frontmatter 필드, context:fork + agent 조합, hooks, skills preload | `skills-frontmatter.md` |
+
+## 적용 시점
+
+| 상황 | 참조할 문서 |
+|------|-----------|
+| Skill SKILL.md 새로 작성 | `skills-frontmatter.md` (frontmatter) + `xml-tags.md` (구조) |
+| Agent .md 새로 작성 | `skills-frontmatter.md` (frontmatter) + `xml-tags.md` (구조) |
+| Hook 스크립트 출력 작성 | `output-optimization.md` (줄 수 제한) |
+| 기존 프롬프트 개선 | `positive-phrasing.md` + `xml-tags.md` |
+| Skill ↔ Agent 연결 설계 | `skills-frontmatter.md` (양방향 연결 패턴) |

package/templates/global/skills/PromptStructuring/skills-frontmatter.md

@@ -17,6 +17,7 @@ SKILL.md와 Agent .md 파일의 YAML frontmatter 필드 가이드.
 |------|------|--------|------|
 | `name` | string | 디렉토리명 | 스킬 이름. `/slash-command`가 됨. 소문자+하이픈, 최대 64자 |
 | `description` | string | 첫 단락 | 용도 및 트리거 조건. Claude가 자동 호출 판단에 사용 |
+| `keywords` | array | - | 검색/매칭용 키워드. 영문+한글 혼용 권장. 예: `[plan, 계획, DB설계]` |
 | `argument-hint` | string | - | 자동완성 시 인자 힌트. 예: `[PR-number]` |
 | `disable-model-invocation` | boolean | `false` | `true` -> Claude 자동 호출 차단. description이 컨텍스트에 로딩되지 않아 토큰 절약 |
 | `user-invocable` | boolean | `true` | `false` -> `/` 메뉴에서 숨김. Claude만 자동 호출 가능 |
@@ -71,6 +72,7 @@ argument-hint: "[PR-number]"
 |------|------|--------|------|
 | `name` | string | **필수** | Agent 이름. 소문자+하이픈 |
 | `description` | string | **필수** | 위임 판단 기준. 언제 이 Agent를 사용하는지 명시 |
+| `keywords` | array | - | 검색/매칭용 키워드. 영문+한글 혼용 권장 |
 | `disallowedTools` | array | - | 명시적 거부 도구 목록 |
 | `model` | string | `inherit` | `sonnet`, `opus`, `haiku`, 모델 ID |
 | `permissionMode` | string | `default` | 권한 모드 |
@@ -108,6 +110,68 @@ skills: [Git]
 
 -> hook으로 "Skill을 먼저 읽으세요"라고 안내하는 간접 방식 대신, frontmatter로 자동 주입.
 
+## Skill ↔ Agent 연결 패턴
+
+> Skill(무엇을 할지) + Agent(어떻게/누가 할지) + Context 격리(어디서 할지)를 조합한다.
+
+### 패턴 1: 참조 Skill (인라인 주입)
+
+Agent가 Skill을 배경 지식으로 preload. 메인 컨텍스트에서 실행.
+
+```yaml
+# Agent frontmatter
+skills: [Coding, Backend]    # Agent 시작 시 Skill 전체 내용 주입
+
+# Skill frontmatter
+user-invocable: false         # 직접 호출 불가, Agent에 의해서만 사용
+```
+
+적용 예: Coding, Backend, React, Reporting
+
+### 패턴 2: 작업 Skill (격리 실행)
+
+Skill 호출 시 fork된 Agent에서 독립 실행. 메인 컨텍스트와 격리.
+
+```yaml
+# Skill frontmatter
+context: fork                 # 격리된 subagent에서 실행
+agent: task-planner           # 사용할 agent 타입 지정
+user-invocable: true          # /slash-command로 호출 가능
+```
+
+적용 예: Planning, pr-review, deploy
+
+### 패턴 3: 양방향 연결
+
+Skill과 Agent가 서로를 참조. 사용자 직접 호출과 Agent preload 모두 지원.
+
+```yaml
+# Planning Skill
+context: fork
+agent: task-planner           # /planning → fork된 task-planner에서 실행
+user-invocable: true
+
+# task-planner Agent
+skills: [Planning, Reporting] # Agent 시작 시 Planning Skill preload
+```
+
+```
+사용자 /planning → fork(task-planner) → Planning 템플릿에 따라 plan 문서 생성
+Main Agent → task-planner 호출 → Planning Skill 자동 preload → 동일 품질 보장
+```
+
+### 패턴 선택 기준
+
+| 기준 | 참조 Skill | 작업 Skill | 양방향 |
+|------|:-:|:-:|:-:|
+| 규칙/가이드 제공 | O | - | O |
+| 독립 실행 필요 | - | O | O |
+| 사용자 직접 호출 | - | O | O |
+| Agent preload | O | - | O |
+| 컨텍스트 격리 | - | O | O |
+
+---
+
 ## Hooks in Skills/Agents
 
 Skill과 Agent의 frontmatter에 `hooks` 필드를 정의하면 해당 컴포넌트가 활성화된 동안에만 실행된다.

package/templates/global/skills/TypeORM/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: TypeORM
+description: TypeORM 사용 시 참조. find > queryBuilder > rawQuery 우선순위, 가독성 기반 선택 기준, Migration 생성 규칙 제공.
+keywords: [TypeORM, find, queryBuilder, rawQuery, Repository, 쿼리, ORM, migration]
+user-invocable: false
+---
+
+# TypeORM 사용 규칙
+
+<rules>
+
+## 쿼리 작성 우선순위
+
+> **가독성을 최우선으로, find > QueryBuilder > Raw Query 순서로 사용한다.**
+
+| 우선순위 | 방식 | 사용 조건 |
+|---------|------|----------|
+| 1 | **find 메서드** | 기본 CRUD, 단순 조건, relations |
+| 2 | **QueryBuilder** | groupBy, 집계, 커스텀 JOIN — 가독성이 유지되는 경우 |
+| 3 | **Raw Query** | QueryBuilder의 서브쿼리 등으로 가독성이 떨어지는 경우 |
+
+### 핵심 판단 기준: 가독성
+
+QueryBuilder가 허용되는 케이스라도, 서브쿼리 중첩 등으로 **코드 가독성이 떨어지면 Raw Query를 사용한다.**
+
+## find 메서드 (우선순위 1)
+
+```typescript
+// ✅ 기본 조회
+const user = await this.userRepository.findOneBy({ id });
+const users = await this.userRepository.find({
+  where: { status: 'active' },
+  relations: ['orders'],
+  order: { createdAt: 'DESC' },
+  take: 10,
+});
+
+// ✅ 조건 조합
+const users = await this.userRepository.find({
+  where: [
+    { status: 'active', role: 'admin' },
+    { status: 'active', role: 'manager' },
+  ],
+});
+```
+
+## QueryBuilder (우선순위 2)
+
+**다음 경우에 QueryBuilder 사용 (가독성이 유지될 때):**
+
+| 케이스 | 예시 |
+|--------|------|
+| **groupBy** | 집계 쿼리 |
+| **getRawMany/getRawOne** | 원시 데이터 필요 |
+| **커스텀 JOIN 조건** | ON 절 커스텀 |
+| **단순 서브쿼리** | 가독성이 유지되는 서브쿼리 |
+
+## Raw Query (우선순위 3)
+
+**QueryBuilder로 작성 시 가독성이 떨어지는 경우 Raw Query 사용:**
+
+| 케이스 | 이유 |
+|--------|------|
+| **복잡한 서브쿼리 중첩** | QueryBuilder 체이닝이 읽기 어려움 |
+| **복잡한 CTE (WITH 절)** | QueryBuilder로 표현 시 과도한 중첩 |
+| **DB 특화 문법** | QueryBuilder가 지원하지 않는 문법 |
+
+</rules>
+
+<examples>
+
+### find vs QueryBuilder
+
+<example type="bad">
+```typescript
+// ❌ 불필요한 QueryBuilder 사용
+const user = await this.userRepository
+  .createQueryBuilder('user')
+  .where('user.id = :id', { id })
+  .getOne();
+```
+</example>
+<example type="good">
+```typescript
+// ✅ find로 대체
+const user = await this.userRepository.findOneBy({ id });
+```
+</example>
+
+### QueryBuilder 허용
+
+<example type="good">
+```typescript
+// ✅ QueryBuilder 허용: groupBy + getRawMany (가독성 유지)
+const stats = await this.orderRepository
+  .createQueryBuilder('order')
+  .select('order.status', 'status')
+  .addSelect('COUNT(*)', 'count')
+  .addSelect('SUM(order.amount)', 'total')
+  .groupBy('order.status')
+  .getRawMany();
+```
+</example>
+
+### QueryBuilder → Raw Query 전환
+
+<example type="bad">
+```typescript
+// ❌ 서브쿼리 중첩으로 가독성 저하
+const result = await this.orderRepository
+  .createQueryBuilder('order')
+  .where((qb) => {
+    const subQuery = qb
+      .subQuery()
+      .select('oi.orderId')
+      .from(OrderItem, 'oi')
+      .where((qb2) => {
+        const subQuery2 = qb2
+          .subQuery()
+          .select('p.id')
+          .from(Product, 'p')
+          .where('p.category = :cat', { cat: 'electronics' })
+          .getQuery();
+        return 'oi.productId IN ' + subQuery2;
+      })
+      .getQuery();
+    return 'order.id IN ' + subQuery;
+  })
+  .getMany();
+```
+</example>
+<example type="good">
+```typescript
+// ✅ Raw Query로 가독성 확보
+const result = await this.orderRepository.query(
+  `SELECT o.*
+   FROM orders o
+   WHERE o.id IN (
+     SELECT oi.order_id
+     FROM order_items oi
+     WHERE oi.product_id IN (
+       SELECT p.id FROM products p WHERE p.category = $1
+     )
+   )`,
+  ['electronics'],
+);
+```
+</example>
+
+</examples>
+
+<rules>
+
+## Migration 생성 규칙
+
+> **Migration 파일은 직접 생성하지 않고, `yarn migration:create` 명령어로 생성한 뒤 수정한다.**
+
+### 이유
+
+직접 파일을 생성하면 타임스탬프 충돌이 발생할 수 있다. CLI 명령어를 통해 생성해야 TypeORM이 타임스탬프를 자동 관리한다.
+
+### 생성 방법
+
+```bash
+# package.json에 migration:create가 정의된 경우
+yarn migration:create src/migrations/MigrationName
+
+# 정의되지 않은 경우 직접 실행
+yarn run typeorm migration:create src/migrations/MigrationName
+```
+
+### 작업 순서
+
+1. `yarn migration:create`로 빈 migration 파일 생성
+2. 생성된 파일의 `up()` / `down()` 메서드 작성
+3. `yarn migration:run`으로 적용 확인
+
+</rules>
+
+<checklist>
+
+## 체크리스트
+
+- [ ] find 메서드를 우선 사용하는가?
+- [ ] QueryBuilder는 find로 불가능한 경우에만 사용하는가?
+- [ ] QueryBuilder 서브쿼리 중첩으로 가독성이 떨어지면 Raw Query로 전환했는가?
+- [ ] Migration 파일을 `yarn migration:create`로 생성했는가? (직접 파일 생성 금지)
+
+</checklist>