jun-claude-code 0.0.14 → 0.0.16

package/README.md

@@ -21,7 +21,7 @@ Claude Code 설정 템플릿 CLI. 미리 정의된 Agents, Skills, Hooks, Workfl
 | `architect` | 아키텍처 설계 |
 | `designer` | UI/UX 스타일링 |
 | `director` | 작업 총괄 디렉터 |
-| `context-collector` | Context 수집 |
+| `context-collector` | 소스 코드 기반 Context 수집 |
 | `context-manager` | Context 문서 관리 |
 
 ### Skills (`templates/global/skills/`)
@@ -50,6 +50,7 @@ Claude Code 설정 템플릿 CLI. 미리 정의된 Agents, Skills, Hooks, Workfl
 |-------|------|
 | `project-task-manager` | GitHub Project 태스크 관리 |
 | `context-generator` | Context 자동 생성 |
+| `project-context-collector` | .claude/context/ 문서 기반 프로젝트 배경 수집 |
 
 ### Project Skills (`templates/project/skills/`)
 
@@ -73,6 +74,14 @@ npm install -g jun-claude-code
 
 ## 사용법
 
+### 명령어 미리보기
+
+| 명령어 | 설명 | 활성화되는 기능 |
+|--------|------|----------------|
+| `jun-claude-code` | 전역 설정 (`~/.claude/`) 설치 | Agents 13종, Skills 6종, Hooks 2종, Workflow |
+| `jun-claude-code init-project` | GitHub Project 연동 | 세션 시작 시 태스크 자동 로드, 태스크 관리 Agent |
+| `jun-claude-code init-context` | Context 자동 생성 설정 | PR 기반 Context 자동 생성, Codebase/Business 문서화, 별도 브랜치 PR |
+
 ### 기본 명령어: 설정 복사
 
 `templates/global` 설정 파일을 `~/.claude`로 복사합니다.
@@ -99,6 +108,13 @@ jun-claude-code init-project
 - Project Number
 - Repository (owner/repo 형식)
 
+**활성화되는 기능:**
+
+| 기능 | 설명 |
+|------|------|
+| 세션 시작 시 태스크 자동 로드 | Claude Code 시작 시 `task-loader.sh`가 GitHub Project에서 할당된 태스크를 조회 |
+| 태스크 관리 Agent | `project-task-manager` Agent를 통해 태스크 상태 변경, 코멘트 추가 가능 |
+
 설정 후 생성되는 파일:
 
 ```
@@ -121,6 +137,15 @@ GitHub Actions를 통한 Context 문서 자동 생성을 설정합니다.
 jun-claude-code init-context
 ```
 
+**활성화되는 기능:**
+
+| 기능 | 설명 |
+|------|------|
+| PR 기반 Context 자동 생성 | PR이 생성/업데이트되면 GitHub Actions가 코드 변경을 분석하여 Context 문서 생성 |
+| Codebase Context | 모듈별 파일 경로, 함수명, 의존 관계를 `.claude/context/codebase/`에 정리 |
+| Business Context | 기술 변경을 비즈니스 관점으로 변환하여 `.claude/context/business/`에 정리 |
+| 별도 브랜치 PR 방식 | 생성된 Context를 `{브랜치명}-generated-context` 브랜치로 분리하여 선택적 머지 가능 |
+
 설정 후 생성되는 파일:
 
 ```

package/dist/init-context.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.initContext = initContext;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
 const chalk_1 = __importDefault(require("chalk"));
 /**
  * Get the templates/project directory path (from package installation)
@@ -46,6 +47,22 @@ const chalk_1 = __importDefault(require("chalk"));
 function getTemplatesDir() {
     return path.resolve(__dirname, '..', 'templates', 'project');
 }
+/**
+ * Prompt user for confirmation using readline
+ */
+function askConfirmation(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            const normalized = answer.toLowerCase().trim();
+            resolve(normalized === 'y' || normalized === 'yes');
+        });
+    });
+}
 /**
  * Initialize context auto-generation with GitHub Actions
  */
@@ -57,7 +74,14 @@ async function initContext() {
     const workflowDest = path.join(cwd, '.github', 'workflows', 'context-gen.yml');
     fs.mkdirSync(path.dirname(workflowDest), { recursive: true });
     if (fs.existsSync(workflowDest)) {
-        console.log(chalk_1.default.yellow('  ⚠ .github/workflows/context-gen.yml already exists, skipping'));
+        const shouldOverwrite = await askConfirmation(chalk_1.default.yellow('  ⚠ .github/workflows/context-gen.yml already exists. Overwrite? (y/N): '));
+        if (shouldOverwrite) {
+            fs.copyFileSync(templateSrc, workflowDest);
+            console.log(chalk_1.default.green('  ✓ Replaced .github/workflows/context-gen.yml'));
+        }
+        else {
+            console.log(chalk_1.default.gray('  Skipped: .github/workflows/context-gen.yml'));
+        }
     }
     else {
         fs.copyFileSync(templateSrc, workflowDest);
@@ -68,7 +92,14 @@ async function initContext() {
     const agentDest = path.join(cwd, '.claude', 'agents', 'context-generator.md');
     fs.mkdirSync(path.dirname(agentDest), { recursive: true });
     if (fs.existsSync(agentDest)) {
-        console.log(chalk_1.default.yellow('  ⚠ .claude/agents/context-generator.md already exists, skipping'));
+        const shouldOverwrite = await askConfirmation(chalk_1.default.yellow('  ⚠ .claude/agents/context-generator.md already exists. Overwrite? (y/N): '));
+        if (shouldOverwrite) {
+            fs.copyFileSync(agentSrc, agentDest);
+            console.log(chalk_1.default.green('  ✓ Replaced .claude/agents/context-generator.md'));
+        }
+        else {
+            console.log(chalk_1.default.gray('  Skipped: .claude/agents/context-generator.md'));
+        }
     }
     else {
         fs.copyFileSync(agentSrc, agentDest);
@@ -79,7 +110,14 @@ async function initContext() {
     const skillDest = path.join(cwd, '.claude', 'skills', 'ContextGeneration', 'SKILL.md');
     fs.mkdirSync(path.dirname(skillDest), { recursive: true });
     if (fs.existsSync(skillDest)) {
-        console.log(chalk_1.default.yellow('  ⚠ .claude/skills/ContextGeneration/SKILL.md already exists, skipping'));
+        const shouldOverwrite = await askConfirmation(chalk_1.default.yellow('  ⚠ .claude/skills/ContextGeneration/SKILL.md already exists. Overwrite? (y/N): '));
+        if (shouldOverwrite) {
+            fs.copyFileSync(skillSrc, skillDest);
+            console.log(chalk_1.default.green('  ✓ Replaced .claude/skills/ContextGeneration/SKILL.md'));
+        }
+        else {
+            console.log(chalk_1.default.gray('  Skipped: .claude/skills/ContextGeneration/SKILL.md'));
+        }
     }
     else {
         fs.copyFileSync(skillSrc, skillDest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jun-claude-code",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Claude Code configuration template - copy .claude settings to your project",
   "main": "dist/index.js",
   "bin": "dist/cli.js",

package/templates/global/CLAUDE.md

@@ -13,7 +13,8 @@ Main Agent의 Context Window는 제한적입니다.
 |------|-------|------|
 | 코드베이스 탐색/검색 | `explore` | 파일 내용이 Main Context에 쌓이지 않음 |
 | 여러 파일 읽기 | `explore`, `context-collector` | 탐색 결과만 요약해서 받음 |
-| 패턴/구조 파악 | `context-collector` | 분석 결과만 받음 |
+| .claude/context/ 문서 수집 | `project-context-collector` | 프로젝트 배경 정보만 요약해서 받음 |
+| 코드 패턴/구조 파악 | `context-collector` | 분석 결과만 받음 |
 | 복잡한 계획 수립 | `task-planner` | 계획 결과만 받음 |
 | 영향 분석 | `impact-analyzer` | 분석 결과만 받음 |
 | 코드 리뷰 | `code-reviewer` | 리뷰 결과만 받음 |
@@ -30,6 +31,8 @@ Main Agent의 Context Window는 제한적입니다.
 | 작업 | 전담 Agent |
 |------|-----------|
 | 파일 탐색 (Glob/Grep) | explore Agent가 전담 |
+| .claude/context/ 문서 탐색 | project-context-collector가 전담 |
+| 소스 코드 패턴/구조 파악 | context-collector가 전담 |
 | 2개 이상 파일 읽기 | explore/context-collector가 전담 |
 | 복잡한 분석/계획 | task-planner에 위임 |
 | 파일 수정 | code-writer가 전담 |

package/templates/global/agents/context-collector.md

@@ -1,8 +1,8 @@
 ---
 name: context-collector
-description: 복잡한 작업 시작 전 배경 정보 수집 시 호출. .claude 문서 탐색, 관련 Skill 식별, 기존 코드 패턴/도메인 지식 요약 제공.
-keywords: [Context수집, 문서확인, 패턴파악, Skill식별, 도메인지식, 코드탐색, 아키텍처분석]
-model: sonnet
+description: 실제 소스 코드에서 패턴/구현 방식/도메인 지식을 수집. Skill/Agent 식별, 코드 DEEP 탐색 전문.
+keywords: [코드탐색, 패턴파악, Skill식별, 도메인지식, 아키텍처분석, DEEP탐색, 소스코드]
+model: opus
 color: blue
 ---
 
@@ -10,10 +10,10 @@ color: blue
 
 <role>
 
-작업 시작 전 필요한 모든 Context를 수집하는 전문 Agent입니다.
+소스 코드에서 패턴, 구현 방식, 도메인 지식을 수집하는 전문 Agent입니다.
 
-1. **Context 문서 수집**: `.claude/context/` 에서 관련 문서 식별 및 읽기
-2. **Skill 식별**: `.claude/skills/` 에서 필요한 Skill 확인
+1. **Skill 식별**: `.claude/skills/` 에서 필요한 Skill 확인
+2. **Agent 식별**: `.claude/agents/` 에서 관련 Agent 확인
 3. **코드 패턴 파악**: 기존 코드에서 유사한 구현 패턴 탐색
 4. **도메인 지식 수집**: 관련 Entity, Service, Flow 파악
 
@@ -23,55 +23,54 @@ color: blue
 
 ## 수집 프로세스
 
-### Step 1: 요청 분석
+### Step 1: 요청 분석 및 탐색 전략 결정
+
+요청을 분석하여 코드 탐색 전략을 결정합니다.
+
+- 요청의 핵심 키워드와 도메인 영역을 식별
+- 탐색 대상: Skill/Agent 문서 → 소스 코드 순서로 진행
+- 탐색 범위를 판단하여 효율적으로 수집
+
+### Step 2: Skill 및 Agent 탐색
 
 ```
-- 백엔드 작업인가? → backend 관련 context/skill 확인
-- 프론트엔드 작업인가? → frontend 관련 context/skill 확인
-- DB 변경이 필요한가? → database context 확인
-- 도메인 로직인가? → domain context 확인
+- .claude/skills/ 에서 작업에 필요한 Skill 확인
+- .claude/agents/ 에서 관련 Agent 확인
 ```
 
-### Step 2: 관련 코드 탐색
+### Step 3: 소스 코드 DEEP 탐색
+
+실제 소스 코드를 직접 탐색하여 패턴과 구현 방식을 파악합니다.
 
 ```
 - 유사한 기존 구현 찾기 (Grep, Glob 활용)
 - Entity 구조 파악
 - Service 패턴 확인
 - Controller 구조 확인
+- 함수명, 클래스명으로 사용처 검색
+- import/export 관계 추적
 ```
 
-### Step 3: Context 요약 출력
-
-```markdown
-## 수집된 Context
-
-### 관련 문서
-- [ ] `.claude/context/xxx.md` - 관련 이유
-
-### 활성화할 Skill
-- [ ] `skill-name` - 필요 이유
+### Step 4: Context 요약 출력
 
-### 참고할 기존 코드
-- `path/to/file.ts` - 유사 패턴 설명
-
-### 도메인 지식
-- 관련 Entity: ...
-- 비즈니스 로직: ...
-```
+수집한 모든 정보를 output_format에 맞춰 정리합니다.
 
 </instructions>
 
 <output_format>
 
-반드시 아래 형식으로 Context 수집 결과를 출력합니다:
+아래 형식으로 Context 수집 결과를 출력합니다:
 
 ```markdown
 # Context 수집 결과
 
-## 1. 관련 Context 문서
-| 문서 | 관련성 | 핵심 내용 |
-|------|--------|----------|
+## 탐색 전략
+- **탐색 범위**: (어떤 영역을 탐색했는지)
+- **판단 근거**: (왜 이 범위를 탐색했는지)
+
+## 1. 소스 코드 탐색 결과
+| 파일 | 확인 내용 | 핵심 발견 |
+|------|----------|----------|
 | ... | ... | ... |
 
 ## 2. 필요한 Skill
@@ -79,7 +78,7 @@ color: blue
 |-------|------|
 | ... | ... |
 
-## 3. 참고 코드
+## 3. 참고 코드 패턴
 | 파일 | 패턴 | 참고 이유 |
 |------|------|----------|
 | ... | ... | ... |
@@ -89,6 +88,16 @@ color: blue
 
 ## 5. 다음 단계 권장사항
 - task-planner Agent로 TaskList 생성 권장
+- 프로젝트 배경 정보가 필요하면 project-context-collector Agent 사용을 권장합니다.
 ```
 
 </output_format>
+
+<constraints>
+
+## 제약사항
+
+- `.claude/context/` 문서는 탐색하지 않습니다. 프로젝트 배경 정보가 필요하면 project-context-collector Agent를 안내합니다.
+- 실제 소스 코드와 `.claude/skills/`, `.claude/agents/` 문서만 탐색합니다.
+
+</constraints>

package/templates/global/agents/explore.md

@@ -39,13 +39,21 @@ color: gray
 - "~패턴의 파일들 목록"
 ```
 
-### context-collector가 적합한 경우
+### 다른 Agent가 적합한 경우
 
+**project-context-collector** (프로젝트 배경 정보):
+```
+- .claude/context/ 문서에서 배경 정보 수집
+- 비즈니스 규칙/도메인 용어 확인
+- 모듈 구조/아키텍처 개요 파악
+```
+
+**context-collector** (소스 코드 DEEP 탐색):
 ```
 - 깊은 코드 분석 필요
-- 비즈니스 로직 이해 필요
 - 여러 파일 간 관계 파악
-- Context 문서 기반 작업
+- Skill/Agent 식별
+- 코드 패턴/구현 방식 분석
 ```
 
 ---
@@ -124,12 +132,13 @@ Glob: "src/module/*/index.ts"
 
 ---
 
-## context-collector와의 차이
+## 관련 Agent 비교
 
-| 항목 | explore | context-collector |
-|------|---------|-------------------|
-| 모델 | Haiku | Sonnet |
-| 속도 | 빠름 | 보통 |
-| 깊이 | 얕음 (위치만) | 깊음 (분석 포함) |
-| 비용 | 낮음 | 보통 |
-| 용도 | "어디 있지?" | "어떻게 동작하지?" |
+| 항목 | explore | project-context-collector | context-collector |
+|------|---------|--------------------------|-------------------|
+| 모델 | Haiku | Sonnet | Opus |
+| 속도 | 빠름 | 보통 | 느림 |
+| 깊이 | 얕음 (위치만) | 중간 (문서 분석) | 깊음 (코드 분석) |
+| 비용 | 낮음 | 보통 | 높음 |
+| 대상 | 소스 코드 | .claude/context/ 문서 | 소스 코드 + Skill/Agent |
+| 용도 | "어디 있지?" | "프로젝트 배경이 뭐지?" | "어떻게 동작하지?" |

package/templates/global/hooks/skill-forced-subagent.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+
+# .claude/hooks/skill-forced-subagent.sh
+# Subagent용 Skill 평가 프로토콜 - SubagentStart hook
+# Subagent가 작업 시작 전 관련 Skills를 평가하고 활성화하도록 유도
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLAUDE_DIR="$(dirname "$SCRIPT_DIR")"
+GLOBAL_CLAUDE_DIR="$HOME/.claude"
+PROJECT_CLAUDE_DIR="$(pwd)/.claude"
+
+echo "✅ [Hook] Subagent Skill 평가 프로토콜 실행됨"
+
+cat << 'EOF'
+MANDATORY SKILL EVALUATION PROTOCOL (Subagent)
+
+작업을 시작하기 전에 아래 단계를 완료하세요:
+
+<phase name="Skill 평가">
+
+## Skill 평가
+
+Step 1 - Skill 평가: 각 Skill에 대해 다음을 명시하세요:
+  - Skill 이름
+  - YES 또는 NO (이 작업에 해당 Skill이 필요한가?)
+  - 한 줄 이유
+
+Step 2 - Skill 활성화: YES로 표시된 모든 Skill의 SKILL.md를 읽으세요.
+
+---
+
+### 사용 가능한 Skills (자동 탐색됨)
+
+</phase>
+EOF
+
+# skills 폴더에서 SKILL.md 파일들의 frontmatter 자동 탐색
+# 프로젝트 .claude/ 와 ~/.claude/ 양쪽에서 탐색 (프로젝트 우선, 중복 제거)
+SEEN_SKILLS=""
+for search_dir in "$PROJECT_CLAUDE_DIR" "$GLOBAL_CLAUDE_DIR"; do
+  if [ -d "$search_dir/skills" ]; then
+    for skill_dir in "$search_dir/skills"/*/; do
+      if [ -d "$skill_dir" ]; then
+        skill_name=$(basename "$skill_dir")
+        skill_file="$skill_dir/SKILL.md"
+
+        # 이미 탐색된 Skill은 건너뜀
+        case "$SEEN_SKILLS" in
+          *"|${skill_name}|"*) continue ;;
+        esac
+        SEEN_SKILLS="${SEEN_SKILLS}|${skill_name}|"
+
+        if [ -f "$skill_file" ]; then
+          # 출처 표시
+          if [ "$search_dir" = "$PROJECT_CLAUDE_DIR" ]; then
+            display_path=".claude/skills/$skill_name/SKILL.md"
+          else
+            display_path="~/.claude/skills/$skill_name/SKILL.md"
+          fi
+          echo "**[$skill_name]** \`$display_path\`"
+          echo '```yaml'
+          head -6 "$skill_file"
+          echo '```'
+          echo ""
+        fi
+      fi
+    done
+  fi
+done
+
+cat << 'EOF'
+
+<phase name="구현">
+
+## 구현
+
+Step 3 - 구현: 관련 Skill을 확인한 후 작업을 시작하세요.
+
+Skill의 규칙과 체크리스트를 준수하며 작업을 수행하세요.
+
+</phase>
+EOF

package/templates/global/hooks/skill-forced.sh

@@ -33,6 +33,8 @@ Main Agent의 Context Window는 제한적입니다.
 | 작업 | 전담 Agent |
 |------|-----------|
 | 파일 탐색 (Glob/Grep) | explore Agent가 전담 |
+| .claude/context/ 문서 탐색 | project-context-collector가 전담 |
+| 소스 코드 패턴/구조 파악 | context-collector가 전담 |
 | 2개 이상 파일 읽기 | explore/context-collector가 전담 |
 | 복잡한 분석/계획 | task-planner에 위임 |
 | 파일 수정 (3개 이상) | code-writer가 전담 |
@@ -126,14 +128,73 @@ cat << 'EOF'
 
 <phase name="Context 확인">
 
-## PART 1.5: CONTEXT 확인 (Subagent 위임 권장)
+## PART 1.5: PROJECT CONTEXT (프로젝트 배경 정보)
 
-**권장:** Context 확인은 `context-collector` Agent에 위임하세요.
-여러 파일을 직접 읽는 대신, Subagent가 요약하여 전달합니다.
+아래는 이 프로젝트의 배경 정보입니다. 작업 판단 시 참고하세요.
+상세 분석이 필요하면 아래 Agent에 위임하세요.
 
-```
-Task(subagent_type="context-collector", prompt="[작업 설명]에 필요한 Context를 수집하고 요약해줘")
-```
+| 필요한 정보 | Agent | 호출 예시 |
+|------------|-------|----------|
+| 프로젝트 배경/도메인 지식 | project-context-collector | \`Task(subagent_type="project-context-collector", prompt="[작업]에 필요한 프로젝트 배경 정보를 수집해줘")\` |
+| 소스 코드 패턴/구현 방식 | context-collector | \`Task(subagent_type="context-collector", prompt="[작업]에 필요한 코드 패턴을 수집해줘")\` |
+
+두 Agent를 순차적으로 사용하면 가장 포괄적인 Context를 수집할 수 있습니다:
+\`\`\`
+1. project-context-collector → 프로젝트 배경 수집
+2. context-collector → 소스 코드 패턴 수집
+\`\`\`
+
+EOF
+
+# context 디렉토리에서 business/codebase context 동적 탐색
+# 프로젝트 .claude/context/ 만 탐색 (글로벌 ~/.claude/context/는 탐색하지 않음)
+CONTEXT_BASE_DIR="$PROJECT_CLAUDE_DIR/context"
+HAS_CONTEXT=false
+
+for context_type in "business" "codebase"; do
+  context_dir="$CONTEXT_BASE_DIR/$context_type"
+  if [ -d "$context_dir" ]; then
+    HAS_CONTEXT=true
+
+    # 헤더 출력
+    if [ "$context_type" = "business" ]; then
+      echo "---"
+      echo ""
+      echo "### Business Context"
+      echo ""
+    else
+      echo "---"
+      echo ""
+      echo "### Codebase Context"
+      echo ""
+    fi
+
+    # INDEX.md가 있으면 내용 출력
+    if [ -f "$context_dir/INDEX.md" ]; then
+      cat "$context_dir/INDEX.md"
+      echo ""
+    fi
+
+    # INDEX.md 외의 .md 파일 목록을 상세 문서로 표시
+    has_detail_docs=false
+    for md_file in "$context_dir"/*.md; do
+      if [ -f "$md_file" ] && [ "$(basename "$md_file")" != "INDEX.md" ]; then
+        if [ "$has_detail_docs" = false ]; then
+          has_detail_docs=true
+        fi
+        echo "상세 문서: \`$(basename "$md_file")\`"
+      fi
+    done
+    echo ""
+  fi
+done
+
+if [ "$HAS_CONTEXT" = false ]; then
+  echo "프로젝트 context가 없습니다. (.claude/context/business/ 또는 .claude/context/codebase/ 디렉토리가 없음)"
+  echo ""
+fi
+
+cat << 'EOF'
 
 </phase>
 

package/templates/global/settings.json

@@ -13,6 +13,16 @@
           }
         ]
       }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/skill-forced-subagent.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/templates/project/agents/context-generator.md

@@ -2,7 +2,7 @@
 name: context-generator
 description: GitHub Action에서 PR diff 기반으로 .claude/context/ 문서를 자동 생성/업데이트 (CI 전용)
 keywords: [context, PR, diff, codebase, business, 문서생성]
-model: sonnet
+model: opus
 color: green
 ---
 
@@ -52,12 +52,11 @@ git diff HEAD~1 --name-only
 - 도메인별 `.md` 파일 생성/업데이트
 - `business/INDEX.md` 업데이트
 
-### 6. 커밋
+### 6. 반영
 
-```bash
-git add .claude/context/
-git commit -m "docs: update context for PR changes"
-```
+- 생성된 context 문서는 `{브랜치명}-generated-context` 브랜치에 push됩니다.
+- 원본 PR 브랜치로 별도 PR이 생성되어 선택적으로 머지할 수 있습니다.
+- PR이 re-sync되면 context 브랜치가 force push로 업데이트됩니다.
 
 ## 제약사항
 

package/templates/project/agents/project-context-collector.md

@@ -0,0 +1,146 @@
+---
+name: project-context-collector
+description: 프로젝트 배경 정보 수집 시 호출. .claude/context/의 business/codebase 문서에서 도메인 지식, 아키텍처 정보를 수집하여 요약 제공.
+keywords: [프로젝트배경, 문서탐색, business-context, codebase-context, 도메인지식, INDEX]
+model: sonnet
+color: blue
+---
+
+# Project Context Collector Agent
+
+<role>
+
+프로젝트의 `.claude/context/` 문서에서 배경 정보를 수집하는 전문 Agent입니다.
+
+1. **Business Context 탐색**: `.claude/context/business/` 에서 도메인 규칙, 비즈니스 로직 파악
+2. **Codebase Context 탐색**: `.claude/context/codebase/` 에서 모듈 구조, 아키텍처 파악
+3. **INDEX 기반 탐색**: INDEX.md를 기점으로 관련 상세 문서를 단계적으로 확인
+4. **요약 제공**: 수집한 배경 정보를 구조화하여 반환
+
+</role>
+
+## 특징
+
+- **Sonnet 모델**: 문서 이해와 요약에 적합
+- **문서 전용**: `.claude/context/` 디렉토리만 탐색, 소스 코드 탐색은 수행하지 않음
+- **빠른 배경 파악**: INDEX.md 기반으로 필요한 문서만 선택적으로 확인
+
+---
+
+## 사용 시점
+
+### 적합한 경우
+
+```
+- 프로젝트 배경 이해가 필요한 경우
+- 도메인 규칙/비즈니스 로직 확인
+- 모듈 구조/아키텍처 개요 파악
+- 작업 시작 전 프로젝트 컨텍스트 수집
+```
+
+### context-collector가 적합한 경우
+
+```
+- 실제 소스 코드 확인이 필요한 경우
+- 코드 패턴/구현 방식 분석
+- Skill/Agent 문서 식별
+- 파일 간 의존성/호출 관계 추적
+```
+
+---
+
+<instructions>
+
+## 수집 프로세스
+
+### Step 1: 요청 분석 및 탐색 카테고리 결정
+
+요청을 분석하여 **탐색 카테고리**와 **탐색 깊이**를 결정합니다.
+
+**탐색 카테고리 판단:**
+
+| 요청 유형 | 우선 탐색 대상 | 예시 |
+|----------|--------------|------|
+| 도메인/비즈니스 규칙 관련 | `business/` | 결제 로직, 사용자 권한, 정책 |
+| 코드 구조/기술 관련 | `codebase/` | 모듈 구조, API 설계, DB 스키마 |
+| 기능 구현 (양쪽 모두 필요) | `business/` → `codebase/` | 새 기능 개발, 리팩토링 |
+
+**탐색 깊이 판단:**
+
+| 깊이 | 조건 | 설명 |
+|------|------|------|
+| Quick | 전체 개요만 필요 | INDEX.md만 확인 (빠른 오버뷰) |
+| Standard | 특정 도메인/모듈 이해 필요 | INDEX.md → 관련 상세 문서 확인 |
+
+### Step 2: INDEX.md 확인
+
+`.claude/context/` 디렉토리가 존재하면 INDEX.md부터 확인합니다.
+디렉토리가 존재하지 않으면 "프로젝트 Context 문서가 없습니다"를 반환합니다.
+
+```
+.claude/context/business/INDEX.md  → 프로젝트 개요, 도메인 목록, 비즈니스 규칙 요약
+.claude/context/codebase/INDEX.md  → 모듈 구조, 기술 스택, 아키텍처 요약
+```
+
+- INDEX.md에서 요청과 관련된 섹션/키워드를 식별
+- 관련 상세 문서 경로를 추출
+- Quick 깊이면 여기서 종료
+
+### Step 3: 상세 문서 확인 (Standard 깊이)
+
+INDEX.md에서 식별한 관련 문서를 읽습니다.
+
+```
+.claude/context/business/*.md  → 비즈니스 규칙, 사용자 흐름, 도메인 용어
+.claude/context/codebase/*.md  → 모듈 관계, 핵심 워크플로우, API 명세
+```
+
+- 상세 문서에서 핵심 정보 추출
+- 요청과 관련도가 높은 내용 우선 수집
+
+### Step 4: Context 요약 출력
+
+수집한 모든 정보를 output_format에 맞춰 정리합니다.
+
+</instructions>
+
+<output_format>
+
+아래 형식으로 Context 수집 결과를 출력합니다:
+
+```markdown
+# Project Context 수집 결과
+
+## 탐색 전략
+- **카테고리**: business / codebase / 양쪽 모두
+- **탐색 깊이**: Quick / Standard
+- **판단 근거**: (왜 이 깊이까지 탐색했는지)
+
+## 1. Business Context (해당시)
+| 문서 | 관련성 | 핵심 내용 |
+|------|--------|----------|
+| ... | ... | ... |
+
+## 2. Codebase Context (해당시)
+| 문서 | 관련성 | 핵심 내용 |
+|------|--------|----------|
+| ... | ... | ... |
+
+## 3. 핵심 요약
+- ...
+
+## 4. 다음 단계 권장사항
+- 실제 코드 확인이 필요하면 context-collector Agent 사용을 권장합니다.
+```
+
+</output_format>
+
+<constraints>
+
+## 제약사항
+
+- `.claude/context/` 디렉토리의 문서만 탐색합니다.
+- 실제 소스 코드(`src/`, `lib/` 등)는 탐색하지 않습니다. 소스 코드 확인이 필요하면 context-collector Agent를 안내합니다.
+- `.claude/skills/`나 `.claude/agents/` 문서는 탐색하지 않습니다. Skill/Agent 식별이 필요하면 context-collector Agent를 안내합니다.
+
+</constraints>

package/templates/project/workflows/context-gen.yml

@@ -40,7 +40,7 @@ jobs:
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           show_full_output: true
-          claude_args: '--allowedTools "Bash(git:*),Bash(ls:*),Bash(mkdir:*),Read,Write,Edit,Glob,Grep"'
+          claude_args: '--model opus --allowedTools "Bash(git:*),Bash(ls:*),Bash(mkdir:*),Read,Write,Edit,Glob,Grep"'
           prompt: |
             # 에이전트 정의
             ${{ steps.read-skills.outputs.agent_def }}
@@ -63,13 +63,40 @@ jobs:
             - 위 스킬 가이드에 명시된 정확한 형식 따르기
             - 커밋하지 마세요. 파일 생성/수정만 하세요.
 
-      - name: Push context changes
+      - name: Push context to separate branch and create PR
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git"
+
           git add .claude/context/
-          git diff --staged --quiet || git commit -m "docs: context 문서 자동 업데이트"
-          git push origin HEAD:refs/heads/${{ github.head_ref }}
+          if git diff --staged --quiet; then
+            echo "No context changes detected"
+            exit 0
+          fi
+
+          CONTEXT_BRANCH="${{ github.head_ref }}-generated-context"
+          git commit -m "docs: context 문서 자동 업데이트"
+          git push --force origin HEAD:refs/heads/${CONTEXT_BRANCH}
+
+          # 기존 PR이 있으면 스킵, 없으면 생성
+          EXISTING_PR=$(gh pr list --head "${CONTEXT_BRANCH}" --base "${{ github.head_ref }}" --json number --jq '.[0].number')
+          if [ -z "$EXISTING_PR" ]; then
+            gh pr create \
+              --head "${CONTEXT_BRANCH}" \
+              --base "${{ github.head_ref }}" \
+              --title "docs: context 문서 자동 업데이트" \
+              --body "$(cat <<'PREOF'
+          ## Auto-generated Context
+
+          PR의 코드 변경을 분석하여 자동 생성된 context 문서입니다.
+          선택적으로 머지하여 반영할 수 있습니다.
+
+          > 이 PR은 re-sync 시 force push로 업데이트됩니다.
+          PREOF
+          )"
+          else
+            echo "PR #${EXISTING_PR} already exists, force-pushed updates"
+          fi
         env:
           GITHUB_TOKEN: ${{ github.token }}