jun-claude-code 0.0.12 → 0.0.13

package/templates/global/skills/PromptStructuring/xml-tags.md

@@ -0,0 +1,330 @@
+---
+name: "XML Tags Guide"
+description: "Claude Code 프롬프트용 XML 태그 표준 및 사용 가이드"
+keywords: [xml, tags, structuring, prompt-format, XML태그, 프롬프트형식]
+estimated_tokens: 2500
+---
+
+# XML 태그 가이드
+
+## 표준 태그 목록
+
+| 태그 | 용도 | 대상 파일 |
+|------|------|----------|
+| `<role>` | Agent 정체성/책임 정의 | Agent |
+| `<instructions>` | 절차/단계 가이드 | Agent, Skill |
+| `<rules>` | 필수 준수 규칙 | 전체 |
+| `<constraints>` | 경계/제약 (긍정 표현) | Agent, CLAUDE.md |
+| `<output_format>` | 출력 구조 정의 | Agent |
+| `<examples>` / `<example type="good/bad">` | 예시 | Skill |
+| `<checklist>` | 검증 항목 | 전체 |
+| `<workflow>` | 다단계 프로세스 | CLAUDE.md, Hook |
+| `<phase name="...">` | 워크플로우 단계 | Hook |
+| `<delegation_rules>` | Subagent 위임 규칙 | CLAUDE.md, Hook |
+| `<reference>` | 문서 상호참조 | 전체 |
+
+---
+
+## 파일 유형별 권장 태그 조합
+
+### Agent 파일
+
+```
+필수: <role>, <instructions>, <constraints>, <output_format>
+선택: <rules>, <examples>, <reference>
+```
+
+Agent는 **정체성 -> 절차 -> 제약 -> 출력** 순서로 구성한다.
+
+### Skill 파일
+
+```
+필수: <instructions>, <rules>, <checklist>
+선택: <examples>, <constraints>, <reference>
+```
+
+Skill은 **절차 -> 규칙 -> 예시 -> 검증** 순서로 구성한다.
+
+### CLAUDE.md
+
+```
+필수: <workflow>, <delegation_rules>, <constraints>
+선택: <rules>, <reference>
+```
+
+CLAUDE.md는 **워크플로우 -> 위임 규칙 -> 제약** 순서로 구성한다.
+
+### Hook 파일
+
+```
+필수: <phase name="...">, <checklist>
+선택: <delegation_rules>, <rules>, <reference>
+```
+
+Hook은 **Phase별 단계 -> 검증 체크리스트** 순서로 구성한다.
+
+---
+
+## Before/After 예시
+
+### 예시 1: Agent - 역할 설명
+
+**Before** (마크다운만 사용):
+
+```markdown
+# Code Writer Agent
+
+## 역할
+
+코드를 작성하는 전문 Agent입니다.
+
+## 해야 할 일
+
+1. task-planner의 계획에 따라 코드 작성
+2. 프로젝트 규칙 준수
+3. 작은 단위로 구현
+
+## 출력
+
+작성한 파일 목록과 변경 내용을 정리하여 출력합니다.
+```
+
+**After** (XML 태그로 의미 구분):
+
+```markdown
+# Code Writer Agent
+
+<role>
+task-planner의 계획에 따라 실제 코드를 작성하는 전문 Agent
+</role>
+
+<instructions>
+1. task-planner의 계획에 따라 코드 작성
+2. 프로젝트 규칙 준수
+3. 작은 단위로 구현하여 빌드 가능 상태 유지
+</instructions>
+
+<output_format>
+## 작성한 파일
+
+### 1. [파일 경로]
+- 변경 유형: 신규 생성 / 수정
+- 주요 내용: ...
+</output_format>
+```
+
+**개선 포인트**: `<role>`로 정체성, `<instructions>`로 절차, `<output_format>`으로 출력 구조를 명확히 분리
+
+---
+
+### 예시 2: Skill - 규칙 목록
+
+**Before** (마크다운만 사용):
+
+```markdown
+# 코딩 규칙
+
+## 규칙
+
+- 하나의 모듈은 하나의 책임만 가진다
+- 순환 의존을 만들지 않는다
+- Promise 처리 시 then-catch 패턴을 사용한다
+
+## 확인
+
+- 이 파일의 책임은 하나인가?
+- 순환 의존이 없는가?
+```
+
+**After** (XML 태그로 의미 구분):
+
+```markdown
+# 코딩 규칙
+
+<rules>
+- 하나의 모듈은 하나의 책임만 가진다 (SRP)
+- 모듈 간 의존 방향은 단방향으로 유지한다
+- Promise 처리 시 then-catch 패턴을 사용한다
+</rules>
+
+<checklist>
+- [ ] 이 파일의 책임은 하나인가?
+- [ ] 의존 방향이 단방향인가?
+- [ ] then-catch 패턴을 사용했는가?
+</checklist>
+```
+
+**개선 포인트**: `<rules>`와 `<checklist>`를 분리하여 "따라야 할 것"과 "검증할 것"을 명확히 구분
+
+---
+
+### 예시 3: Hook - Phase 구분
+
+**Before** (마크다운만 사용):
+
+```markdown
+# Pre-commit Hook
+
+## 단계 1: 계획 확인
+
+계획이 있는지 확인합니다. 계획이 없으면 중단합니다.
+
+## 단계 2: 코드 검증
+
+lint와 type check를 실행합니다.
+
+## 단계 3: 커밋
+
+변경사항을 커밋합니다.
+```
+
+**After** (XML 태그로 Phase 구분):
+
+```markdown
+# Pre-commit Hook
+
+<workflow>
+
+<phase name="계획 확인">
+계획이 존재하는지 확인한다. 계획이 있을 때만 다음 Phase로 진행한다.
+</phase>
+
+<phase name="코드 검증">
+lint와 type check를 실행한다. 모든 검증을 통과할 때만 다음 Phase로 진행한다.
+</phase>
+
+<phase name="커밋">
+변경사항을 커밋한다.
+</phase>
+
+</workflow>
+```
+
+**개선 포인트**: `<workflow>` > `<phase>` 구조로 단계 간 경계와 진행 조건을 명확히 표현
+
+---
+
+## `->` 기호 사용 가이드
+
+`->` 기호는 **방향성이 있는 흐름**을 간결하게 표현할 때 사용한다.
+
+### 단계 표현
+
+순서가 있는 프로세스를 나타낸다.
+
+```
+계획 -> 구현 -> 검증 -> 리뷰
+Context 수집 -> TaskList 생성 -> 코드 수정 계획
+```
+
+### 변환 표현
+
+입력이 출력으로 바뀌는 과정을 나타낸다.
+
+```
+부정 표현 -> 긍정 표현
+마크다운 제목 -> XML 태그
+"~금지" -> "~전담/전용"
+```
+
+### 위임 표현
+
+작업이 특정 Agent로 전달됨을 나타낸다.
+
+```
+코드 수정 -> code-writer Agent
+Git 작업 -> git-manager Agent
+코드베이스 탐색 -> explore Agent
+```
+
+### 테이블에서 사용
+
+변환 관계를 테이블로 정리할 때도 `->` 를 활용한다.
+
+```markdown
+| Before | -> | After |
+|--------|-----|-------|
+| "~금지" | -> | "~전담" |
+| `## 역할` | -> | `<role>` |
+```
+
+---
+
+## 주의사항
+
+### XML 태그는 마크다운을 보완한다
+
+XML 태그는 마크다운을 대체하는 것이 아니라 **의미 계층을 추가**하는 것이다.
+
+```markdown
+<rules>
+## 네이밍 규칙
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 변수 | camelCase | `userName` |
+| 상수 | UPPER_SNAKE | `MAX_COUNT` |
+
+## 구조 규칙
+
+- 한 파일에 한 컴포넌트만 정의한다
+- index.ts를 통해 export한다
+</rules>
+```
+
+태그 내부에서 `##`, 테이블, 코드블록을 정상적으로 사용한다.
+
+### 태그 중첩은 2단계까지
+
+```markdown
+<!-- 허용: 2단계 -->
+<workflow>
+  <phase name="계획">...</phase>
+</workflow>
+
+<!-- 지양: 3단계 이상 -->
+<workflow>
+  <phase name="계획">
+    <sub-step>...</sub-step>    <!-- 과도한 중첩 -->
+  </phase>
+</workflow>
+```
+
+3단계 이상 중첩이 필요하면 마크다운 제목(`###`)이나 리스트로 대체한다.
+
+### 닫는 태그를 반드시 포함한다
+
+```markdown
+<!-- 올바름 -->
+<role>
+Agent의 역할 설명
+</role>
+
+<!-- 오류 -->
+<role>
+Agent의 역할 설명
+```
+
+모든 XML 태그는 여는 태그와 닫는 태그를 쌍으로 작성한다.
+
+### 태그 이름은 표준 목록에서 선택한다
+
+이 가이드의 **표준 태그 목록**에 정의된 태그만 사용한다. 커스텀 태그가 필요한 경우 기존 태그로 대체할 수 있는지 먼저 검토한다.
+
+---
+
+## 체크리스트
+
+<checklist>
+- [ ] 파일 유형(Agent/Skill/CLAUDE.md/Hook)에 맞는 태그 조합을 사용했는가?
+- [ ] 태그 내부에서 마크다운 문법(제목, 테이블, 코드블록)을 정상 활용하는가?
+- [ ] 태그 중첩이 2단계 이하인가?
+- [ ] 모든 태그에 닫는 태그가 포함되어 있는가?
+- [ ] 표준 태그 목록에 정의된 태그만 사용했는가?
+- [ ] `->` 기호를 단계/변환/위임 표현에 활용했는가?
+</checklist>
+
+<reference>
+- `SKILL.md` - 프롬프트 구조화 개요 및 핵심 원칙
+- `positive-phrasing.md` - 부정 -> 긍정 전환 패턴
+</reference>

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

@@ -43,6 +43,8 @@ src/
 | Layout | 페이지 레이아웃 구조 | Header, Sidebar, Footer |
 | Page | 라우트에 매핑되는 페이지 | HomePage, LoginPage |
 
+<rules>
+
 ## 필수 준수 사항
 
 ### 컴포넌트 작성
@@ -58,20 +60,22 @@ src/
 
 | 규칙 | 설명 |
 |------|------|
-| 상태 최소화 | 파생 가능한 값은 상태로 두지 않음 |
+| 상태 최소화 | 파생 가능한 값은 계산으로 처리 |
 | 상태 위치 | 필요한 가장 가까운 공통 조상에 배치 |
-| 불변성 유지 | 상태 직접 수정 금지, 새 객체/배열 생성 |
+| 불변성 유지 | 상태 업데이트 시 새 객체/배열을 생성 |
 | 복잡한 상태 | useReducer 또는 상태 관리 라이브러리 사용 |
 
 ### Hooks 규칙
 
 | 규칙 | 설명 |
 |------|------|
-| 최상위에서만 호출 | 조건문, 반복문 내부에서 호출 금지 |
-| 의존성 배열 정확히 | useEffect, useMemo, useCallback의 deps 누락 금지 |
+| 최상위에서만 호출 | 조건문, 반복문 바깥의 최상위 레벨에서 호출 |
+| 의존성 배열 정확히 | useEffect, useMemo, useCallback의 deps를 빠짐없이 명시 |
 | 커스텀 훅 추출 | 재사용 가능한 로직은 커스텀 훅으로 분리 |
 | 훅 네이밍 | `use` 접두사 필수 (예: `useAuth`, `useFetch`) |
 
+</rules>
+
 ## 성능 최적화
 
 ### 메모이제이션
@@ -87,6 +91,8 @@ const expensiveValue = useMemo(() => computeExpensive(a, b), [a, b]);
 const handleClick = useCallback(() => doSomething(id), [id]);
 ```
 
+<rules>
+
 ### 최적화 적용 기준
 
 | 상황 | 적용 |
@@ -96,10 +102,16 @@ const handleClick = useCallback(() => doSomething(id), [id]);
 | 비용이 큰 계산 | `useMemo` 사용 |
 | 자식에게 전달하는 콜백 | `useCallback` 사용 |
 
-### 불필요한 최적화 금지
+<constraints>
+
+### 최적화 시 주의사항
+
+- memo는 측정 결과 리렌더링이 잦은 컴포넌트에만 적용 (React DevTools Profiler 사용)
+- 성능 측정 후 필요한 곳에만 최적화 적용
 
-- 모든 컴포넌트에 무조건 memo 적용 금지
-- 측정 없이 최적화하지 않음 (React DevTools Profiler 사용)
+</constraints>
+
+</rules>
 
 ## useEffect 패턴
 
@@ -128,6 +140,8 @@ useEffect(() => {
 | 렌더링 중 상태 업데이트 | 조건부 렌더링 또는 useMemo |
 | 불필요한 Effect | 이벤트 핸들러로 처리 |
 
+<checklist>
+
 ## 체크리스트
 
 ### 컴포넌트 작성 시
@@ -147,9 +161,13 @@ useEffect(() => {
 
 ### 성능
 - [ ] 리스트에 적절한 key가 사용되었는가?
-- [ ] 불필요한 리렌더링이 없는가?
+- [ ] 불필요한 리렌더링이 있는가? (있다면 memo 검토)
 - [ ] 메모이제이션이 적절히 사용되었는가?
 
+</checklist>
+
+<reference>
+
 ## 관련 문서
 
 | 문서 | 설명 |
@@ -157,3 +175,5 @@ useEffect(() => {
 | `tanstack-router.md` | TanStack Router 파일 기반 라우팅 패턴 |
 | `react-hook-form.md` | React Hook Form + Zod 폼 검증 패턴 |
 | `tailwind-styled.md` | tailwind-styled-components DOM depth 최소화 |
+
+</reference>

package/templates/global/skills/React/react-hook-form.md

@@ -26,6 +26,8 @@ src/features/auth/
     └── useLoginMutation.ts  # TRPC mutation 훅
 ```
 
+<rules>
+
 ## 필수 준수 사항
 
 | 규칙 | 올바른 예 | 잘못된 예 |
@@ -35,6 +37,8 @@ src/features/auth/
 | 에러 표시 | `formState.errors` 사용 | 커스텀 에러 상태 |
 | 로딩 상태 | `mutation.isPending` 사용 | 별도 loading 상태 |
 
+</rules>
+
 ## 스키마 정의 패턴
 
 ```typescript
@@ -199,24 +203,28 @@ const formValues = watch()
 {watchedEmail && <p>입력된 이메일: {watchedEmail}</p>}
 ```
 
+<checklist>
+
 ## 체크리스트
 
 ### 스키마 설정
-- [ ] 스키마를 별도 파일(*FormSchema.ts)로 분리
-- [ ] z.infer로 타입 추론
-- [ ] 에러 메시지 한글화
+- [ ] 스키마를 별도 파일(*FormSchema.ts)로 분리했는가?
+- [ ] z.infer로 타입 추론을 사용하는가?
+- [ ] 에러 메시지를 한글화했는가?
 
 ### 폼 구현
-- [ ] zodResolver 사용
-- [ ] defaultValues 설정
-- [ ] register로 필드 등록
+- [ ] zodResolver를 사용하는가?
+- [ ] defaultValues를 설정했는가?
+- [ ] register로 필드를 등록했는가?
 
 ### 에러 처리
-- [ ] formState.errors로 에러 표시
-- [ ] 서버 에러는 setError로 처리
-- [ ] 필드별 에러 메시지 표시
+- [ ] formState.errors로 에러를 표시하는가?
+- [ ] 서버 에러는 setError로 처리하는가?
+- [ ] 필드별 에러 메시지를 표시하는가?
 
 ### TRPC 연동
-- [ ] useMutation 사용
-- [ ] isPending으로 로딩 상태 표시
-- [ ] onSuccess/onError 핸들러 구현
+- [ ] useMutation을 사용하는가?
+- [ ] isPending으로 로딩 상태를 표시하는가?
+- [ ] onSuccess/onError 핸들러를 구현했는가?
+
+</checklist>

package/templates/global/skills/React/tailwind-styled.md

@@ -7,11 +7,13 @@ estimated_tokens: ~350
 
 # tailwind-styled-components 스킬
 
+<rules>
+
 ## 핵심 원칙
 
 **DOM depth를 최소화하라.**
-- 불필요한 wrapper div 제거
-- 스타일만을 위한 중첩 요소 금지
+- 불필요한 wrapper div를 제거
+- 단일 수준 구조를 유지 (스타일 전용 중첩 대신)
 - 하나의 Styled Component가 하나의 DOM 요소
 
 ## 필수 준수 사항
@@ -23,8 +25,13 @@ estimated_tokens: ~350
 | `<Wrapper><Inner><Content>...</Content></Inner></Wrapper>` | `<Container>...</Container>` |
 | `<div><div className="...">...</div></div>` | `<StyledDiv>...</StyledDiv>` |
 
+</rules>
+
+<examples>
+
 ### 예제: 불필요한 중첩 제거
 
+<example type="bad">
 ```typescript
 // ❌ Bad - 불필요한 DOM depth
 const Card = () => (
@@ -38,7 +45,10 @@ const Card = () => (
     </div>
   </div>
 );
-
+```
+</example>
+<example type="good">
+```typescript
 // ✅ Good - 최소한의 DOM depth
 const CardContainer = tw.div`
   p-4
@@ -56,9 +66,11 @@ const Card = () => (
   </CardContainer>
 );
 ```
+</example>
 
 ### 예제: Tailwind 디자인 변환
 
+<example type="bad">
 ```typescript
 // 원본 Tailwind (depth: 3)
 <div className="p-5">
@@ -68,7 +80,10 @@ const Card = () => (
     </div>
   </div>
 </div>
-
+```
+</example>
+<example type="good">
+```typescript
 // ✅ 변환 후 (depth: 1)
 const StepContent = tw.div`
   p-5
@@ -83,6 +98,9 @@ const StepContent = tw.div`
   <Title>Title</Title>
 </StepContent>
 ```
+</example>
+
+</examples>
 
 ## Styled Component 네이밍
 
@@ -152,14 +170,18 @@ const Input = tw.input`
 `;
 ```
 
+<checklist>
+
 ## 체크리스트
 
 ### DOM 구조
-- [ ] 스타일만을 위한 wrapper div가 있는가? → 제거
-- [ ] 중첩된 div를 하나로 합칠 수 있는가? → 합치기
-- [ ] depth가 3 이상인가? → 리팩토링 고려
+- [ ] 스타일 전용 wrapper div가 있는가? (있다면 제거)
+- [ ] 중첩된 div를 하나로 합칠 수 있는가? (합치기)
+- [ ] depth가 3 이상인가? (리팩토링 고려)
 
 ### Styled Component
 - [ ] 의미 있는 이름인가?
 - [ ] transient props($prefix)를 사용하는가?
 - [ ] 재사용 가능한 컴포넌트인가?
+
+</checklist>

package/templates/global/skills/React/tanstack-router.md

@@ -32,6 +32,8 @@ src/routes/
     └── register.tsx     # /auth/register
 ```
 
+<rules>
+
 ## 필수 준수 사항
 
 | 규칙 | 올바른 예 | 잘못된 예 |
@@ -41,6 +43,10 @@ src/routes/
 | 루트 라우트 | `__root.tsx` (더블 언더스코어) | `root.tsx` |
 | 네비게이션 훅 | `Route.useNavigate()` | `useNavigate()` 직접 import |
 
+</rules>
+
+<instructions>
+
 ## 라우트 정의 패턴
 
 ### 기본 라우트
@@ -166,19 +172,25 @@ export const Route = createFileRoute('/_admin')({
 })
 ```
 
+</instructions>
+
+<checklist>
+
 ## 체크리스트
 
 ### 라우트 설정 시
-- [ ] 동적 파라미터에 `$` 프리픽스 사용
-- [ ] 레이아웃 라우트에 `_` 프리픽스 사용
-- [ ] 루트 레이아웃은 `__root.tsx`
+- [ ] 동적 파라미터에 `$` 프리픽스를 사용하는가?
+- [ ] 레이아웃 라우트에 `_` 프리픽스를 사용하는가?
+- [ ] 루트 레이아웃은 `__root.tsx`인가?
 
 ### 네비게이션
-- [ ] `Route.useNavigate()` 사용
-- [ ] 타입 안전한 params 전달
-- [ ] 동적 파라미터는 params 객체로 전달
+- [ ] `Route.useNavigate()`를 사용하는가?
+- [ ] 타입 안전한 params를 전달하는가?
+- [ ] 동적 파라미터는 params 객체로 전달하는가?
 
 ### 인증
-- [ ] beforeLoad에서 인증 체크
-- [ ] redirect로 리다이렉트 처리
-- [ ] 원래 경로 저장 (redirect search param)
+- [ ] beforeLoad에서 인증을 체크하는가?
+- [ ] redirect로 리다이렉트를 처리하는가?
+- [ ] 원래 경로를 저장하는가? (redirect search param)
+
+</checklist>

package/templates/project/agents/project-task-manager.md

@@ -10,13 +10,15 @@ color: green
 
 GitHub Project 태스크를 관리하는 Agent입니다.
 
-## 역할
+<role>
 
 1. **태스크 조회**: 프로젝트 보드의 태스크 목록 조회
 2. **태스크 생성**: 새 이슈 생성 및 프로젝트에 추가
 3. **상태 변경**: 태스크 상태 업데이트 (Backlog/In progress/Done)
 4. **태스크 검색**: 키워드/상태별 필터링
 
+</role>
+
 ## 프로젝트 설정
 
 이 Agent는 `.claude/project.env` 파일에서 프로젝트 정보를 읽습니다.
@@ -52,16 +54,20 @@ source .claude/project.env
 - "이슈 #123을 프로젝트에 추가해줘"
 ```
 
-### 부적합한 경우
+<constraints>
 
-```
-- 코드 작업 (code-writer 사용)
-- PR 생성/관리 (git-manager 사용)
-- 코드 리뷰 (code-reviewer 사용)
-```
+### 다른 Agent 전담 영역
+
+- 코드 작업은 code-writer가 전담한다
+- PR 생성/관리는 git-manager가 전담한다
+- 코드 리뷰는 code-reviewer가 전담한다
+
+</constraints>
 
 ---
 
+<instructions>
+
 ## 명령어 패턴
 
 ### 태스크 목록 조회
@@ -110,8 +116,12 @@ gh project item-edit --project-id <PROJECT_ID> --id <ITEM_ID> --field-id <FIELD_
 gh issue close <issue-number> --repo "$GITHUB_PROJECT_REPO"
 ```
 
+</instructions>
+
 ---
 
+<output_format>
+
 ## 출력 형식
 
 ```markdown
@@ -134,6 +144,8 @@ gh issue close <issue-number> --repo "$GITHUB_PROJECT_REPO"
 - #49 S3 URL 대신 CDN URL로 응답하도록 수정
 ```
 
+</output_format>
+
 ---
 
 ## 권한 요구사항