oh-my-customcode 0.140.0 → 0.142.0

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-49 agents. 118 skills. 23 rules. One command.
+49 agents. 121 skills. 23 rules. One command.
 
 ```bash
 npm install -g oh-my-customcode && cd your-project && omcustom init
@@ -132,7 +132,7 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (118)
+### Skills (121)
 
 | Category | Count | Includes |
 |----------|-------|----------|
@@ -222,7 +222,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (54)
+### Guides (57)
 
 Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
 
@@ -272,14 +272,14 @@ your-project/
 ├── CLAUDE.md                   # Entry point
 ├── .claude/
 │   ├── agents/                 # 49 agent definitions
-│   ├── skills/                 # 118 skill modules
+│   ├── skills/                 # 121 skill modules
 │   ├── rules/                  # 22 governance rules (R000-R021)
 │   ├── hooks/                  # 15 lifecycle hook scripts
 │   ├── schemas/                # Tool input validation schemas
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
-└── guides/                     # 54 reference documents
+└── guides/                     # 57 reference documents
 ```
 
 ---

package/dist/cli/index.js

@@ -2334,7 +2334,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.140.0",
+    version: "0.142.0",
     description: "Batteries-included agent harness for Claude Code",
     type: "module",
     bin: {

package/dist/index.js

@@ -2014,7 +2014,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.140.0",
+  version: "0.142.0",
   description: "Batteries-included agent harness for Claude Code",
   type: "module",
   bin: {

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.140.0",
+  "version": "0.142.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/skills/instinct-extractor/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: instinct-extractor
+description: 다중 세션 transcript에서 반복 실패 패턴(instinct)을 자동 채굴하여 신규 skill candidate 생성
+scope: core
+user-invocable: true
+argument-hint: "[--days <n>] [--min-repeat <n>] [--dry-run]"
+version: 0.1.0
+effort: medium
+---
+
+# Instinct Extractor
+
+세션 transcript 시계열에서 _instinct_ (실패 학습 + 대응 본능) 패턴을 자동 채굴하여 신규 skill candidate를 생성한다.
+R016 연속 개선 루프의 자동화 단계로, 사람이 명시적으로 호출하거나 R016 Skill Promotion 트리거(동일 패턴 3회 이상 반복)에 의해 자동 실행된다.
+
+## skill-extractor와의 차별점
+
+| 자산 | trigger | input | output |
+|------|---------|-------|--------|
+| `skill-extractor` | 명시 호출 (`--mode success` / `--mode failure`) | 단일 세션 task trajectory + feedback memory | SKILL.md candidate |
+| `instinct-extractor` | 자동/스케줄 (R016 3회 반복 트리거) | 다중 세션 transcript 시계열 (N일 범위) | failure pattern + 대응 본능 클러스터 → SKILL.md candidate |
+
+**보완 관계**: `skill-extractor --mode failure`는 현재 세션의 feedback memory를 분석한다.
+`instinct-extractor`는 여러 세션을 가로질러 시계열 패턴을 채굴한다.
+두 스킬은 경쟁하지 않으며, instinct-extractor가 발견한 후보를 skill-extractor의 결과물과 교차 검증하는 것을 권장한다.
+
+## Usage
+
+```
+/instinct-extractor                    # 최근 14일 transcript 분석
+/instinct-extractor --days 30          # 분석 범위 확장
+/instinct-extractor --min-repeat 2     # 반복 임계값 낮춤 (기본: 3)
+/instinct-extractor --dry-run          # 제안만 출력, 파일 미생성
+```
+
+## Options
+
+```
+--days, -d         분석할 transcript 범위 (일 단위, 기본: 14)
+--min-repeat, -r   instinct 후보 최소 반복 횟수 (기본: 3)
+--dry-run          후보 목록만 stdout 출력, mgr-creator 위임 없음
+--cluster-only     클러스터링 결과만 출력, SKILL.md 제안 없음
+```
+
+## 입력
+
+```
+~/.claude/projects/*/session-*.jsonl   # Claude Code 세션 transcript
+.claude/agent-memory*/feedback_*.md   # 누적 feedback memory (보조)
+```
+
+transcript 파일이 없을 경우: `"분석 가능한 transcript 없음 (--days 범위 내)"` 보고 후 종료.
+
+## 워크플로우
+
+### Phase 1: Transcript 스캔
+
+```bash
+# 분석 대상 수집
+find ~/.claude/projects -name "session-*.jsonl" \
+  -newer $(date -v-${DAYS}d +%Y-%m-%dT00:00:00) 2>/dev/null
+```
+
+각 transcript에서 다음 이벤트 추출:
+- `type: "error"` — 오류 발생 기록
+- `type: "correction"` — 사용자 수정 지시
+- `type: "feedback"` — 부정 피드백 (`"no"`, `"wrong"`, `"don't"` 키워드 포함)
+- `type: "retry"` — 동일 작업 재시도
+
+### Phase 2: 패턴 클러스터링
+
+추출된 이벤트를 `(domain, action_verb, error_class)` 튜플로 그룹화:
+
+```
+Cluster: (agent-design, write, missing-frontmatter)
+  → sessions: [s1, s3, s7], count: 4
+  → first_seen: 2026-05-01, last_seen: 2026-05-15
+  → example_corrections: ["bypassPermissions 누락", "name 필드 없음"]
+```
+
+필터링 기준:
+- `count >= --min-repeat` (기본: 3)
+- `last_seen` >= 7일 이내 (오래된 패턴 제외)
+- 기존 skill과 80% 이상 키워드 겹침 → 새 skill 대신 기존 skill 업데이트 제안
+
+### Phase 3: Instinct 후보 생성
+
+각 클러스터를 "instinct 후보"로 명명:
+
+```
+instinct: prevent-missing-bypassPermissions
+  근거: 4회 반복 (2주), agent spawn 시 mode 누락
+  대응 패턴: spawn 전 bypassPermissions 자가 체크
+  제안 자산: 기존 R010 강화 OR 신규 guard skill
+```
+
+**분류 기준**:
+
+| 패턴 성격 | 권장 자산 |
+|-----------|----------|
+| 동일 실수 반복 (행동 교정) | feedback memory 강화 |
+| 워크플로우 절차 누락 | 기존 skill 섹션 추가 |
+| 명확한 재사용 루틴 | 신규 SKILL.md 제안 |
+| 규칙 미준수 (R007~R022) | 해당 rule 자가 체크 섹션 강화 제안 |
+
+context fork cap (12개) 확인: 신규 skill이 `context: fork` 필요 시 현재 사용량 체크.
+현재 cap: 10/12 (secretary/dev-lead/de-lead/qa-lead-routing, dag-orchestration, task-decomposition, worker-reviewer-pipeline, deep-plan, professor-triage, roundtable-debate).
+
+### Phase 4: 사용자 제시
+
+```
+[instinct-extractor] {N}개 instinct 후보 발견 (최근 {DAYS}일, {M}개 세션)
+
+  1. [high] prevent-missing-bypassPermissions
+     반복: 4회 | 마지막: 2026-05-15 | 도메인: agent-design
+     대응 본능: spawn 전 mode 체크 → skill 후보: bypassPermissions-guard
+
+  2. [medium] transcript-scan-format-mismatch
+     반복: 3회 | 마지막: 2026-05-10 | 도메인: memory
+     대응 본능: JSONL 파싱 전 format 버전 체크
+
+생성할 항목 선택 [1-N], "all", 또는 "skip":
+```
+
+### Phase 5: Skill Candidate 생성 (승인 시)
+
+mgr-creator에 위임:
+- 후보 이름 및 설명
+- 클러스터 데이터 (반복 횟수, 예시 수정 사항)
+- 분류 결과 (신규 skill / 기존 확장 / rule 강화)
+- 기존 skill과의 겹침 경고
+
+## 아티팩트 출력
+
+```
+.claude/outputs/sessions/{YYYY-MM-DD}/instinct-extractor-{HHmmss}.md
+```
+
+CC v2.1.121+ 환경에서 `.claude/outputs/` 직접 Write 가능 (`bypassPermissions` 모드).
+CC < v2.1.121 환경: `/tmp/instinct-extractor-{ts}.md` 경유 후 이동.
+
+## R016 자동화 연동
+
+R016 Defect Response Matrix의 "Skill Promotion" 조건:
+> feedback memory가 동일 패턴으로 3회 이상 반복 → skill-extractor `--mode failure` 실행 권장
+
+`instinct-extractor`는 이 조건을 **cross-session 범위로 확장**한다:
+- 단일 세션의 feedback memory 분석 → `skill-extractor --mode failure`
+- 다중 세션 시계열 채굴 → `instinct-extractor`
+
+R016 트리거 감지 시 오케스트레이터는 두 스킬을 순차 실행하여 결과를 교차 검증할 수 있다.
+
+## 통합
+
+| 시스템 | 연동 방식 |
+|--------|----------|
+| `skill-extractor --mode failure` | 보완 관계 — 결과 교차 검증 권장 |
+| R016 (continuous-improvement) | 3회 반복 트리거 → 자동 실행 후보 |
+| mgr-creator | 승인된 후보 SKILL.md 생성 위임 |
+| sys-memory-keeper | 채굴 결과를 project memory로 보존 |
+| feedback-collector | feedback 이벤트 소스 공유 |
+| R011 (memory) | User Model의 Override Decisions 반영 |
+
+## 안전 규칙
+
+- **사용자 승인 필수**: skill 자동 생성 없음, 항상 사용자 확인 후 mgr-creator 위임
+- **중복 체크**: 기존 skill과 80%+ 겹침 시 신규 생성 대신 업데이트 권장
+- **dry-run 모드**: 부작용 없는 미리보기
+- **context fork cap 체크**: `context: fork` 필요 skill은 cap(12) 초과 여부 사전 확인
+
+## 한계
+
+- **transcript 형식 의존**: CC `session-*.jsonl` 스키마 변경 시 파싱 재구현 필요.
+  AgentMemory 마이그레이션(#1169, Phase 3 DECOUPLE) 완료 후 transcript 경로/형식 재검토 예정.
+- **클러스터링 정확도**: 키워드 기반 클러스터링으로 의미적 동의어 처리 제한.
+- **Phase γ 제약**: #1169 AgentMemory Phase 3 이전에는 transcript 형식 불안정 — `--dry-run` 권장.

package/templates/.claude/skills/profile/SKILL.md

@@ -137,3 +137,60 @@ IMPORTANT: Restart this Claude Code session for plugin changes to take effect.
 - Profiles define a subset: plugins not listed in `enabled` or `disabled` keep their current state
 - Profile JSON `enabled`/`disabled` lists use full plugin keys: `<name>@<marketplace>` format
 - All `.claude/` writes use the /tmp bypass pattern (see Implementation rules above)
+
+## Manifest Profile Integration
+
+`templates/manifest.json` 의 `profiles` 키는 **자산 필터링** (에이전트·스킬·가이드 범위)을 정의합니다. 기존 `.claude/profiles/*.json` 의 **플러그인 전환** 역할과 분리된 개념입니다.
+
+### 두 프로필 시스템 비교
+
+| 시스템 | 경로 | 역할 | 적용 시점 |
+|--------|------|------|-----------|
+| Plugin profiles | `.claude/profiles/*.json` | `~/.claude/settings.json` plugin on/off | 세션 재시작 후 |
+| Manifest profiles | `templates/manifest.json#profiles` | 설치 시 에이전트·스킬·가이드 범위 지정 | `omcustom install --profile <name>` |
+
+### Manifest Profile 사용 시나리오
+
+```bash
+# 최소 자산으로 설치 (학습·실험 환경)
+omcustom install --profile minimal
+
+# Web 앱 개발 전용 자산 설치
+omcustom install --profile web-app
+
+# 데이터 엔지니어링 전용 자산 설치
+omcustom install --profile data-eng
+
+# 전체 자산 설치 (기본값)
+omcustom install --profile full
+# 또는 (profile 생략 시 full과 동일)
+omcustom install
+```
+
+### include 패턴 해석 규칙
+
+| 패턴 | 의미 | 예시 |
+|------|------|------|
+| `"*"` | 해당 카테고리 전체 포함 | `"include": "*"` |
+| `"mgr-*"` | glob 패턴, 접두사 매칭 | mgr-creator, mgr-gitnerd 등 |
+| `{"scope": "core"}` | SKILL.md의 scope 필드 기준 | scope: core인 스킬 전체 |
+| `"react-best-practices"` | 특정 스킬/가이드 이름 | 해당 항목만 포함 |
+
+### Plugin + Manifest 프로필 연동 가이드
+
+동일 이름(예: `web-app`)으로 두 시스템을 함께 사용할 수 있습니다:
+
+```bash
+# 1. Manifest profile로 자산 설치
+omcustom install --profile web-app
+
+# 2. Plugin profile로 플러그인 전환
+/profile load web-app
+```
+
+두 시스템은 독립적이므로 어느 하나만 사용해도 무방합니다.
+
+### 관련 문서
+
+- `guides/profiles/manifest-install.md` — 전체 사용 가이드 및 프로필별 자산 표
+- `templates/manifest.json#profiles` — 프로필 정의 소스

package/templates/.claude/skills/sec-agentshield-wrapper/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: sec-agentshield-wrapper
+description: Pre-flight security analysis before code changes — identifies trust boundary risks, dangerous patterns, and provides proceed/caution/block advisory before implementation starts
+scope: core
+version: 0.1.0
+user-invocable: true
+effort: medium
+argument-hint: '"<파일/영역 설명> — <변경 의도>"'
+---
+
+# 보안 사전 분석 Wrapper (sec-agentshield-wrapper)
+
+코드 작업을 시작하기 전에 보안 위험을 사전 식별하는 pre-flight 스킬.
+작업 진입 전 단계에서 트러스트 경계, 위험 패턴, 권한 변경을 분석하여 진행 여부 advisory를 제공한다.
+
+## 기존 보안 자산과의 차별점
+
+| 자산 | 시점 | 강점 | 약점 |
+|------|------|------|------|
+| `sec-codeql-expert` | post-write (작성 후 분석) | CodeQL 정적 분석, CVE 매칭, SARIF 출력 | 코드가 이미 작성된 후 문제 발견 |
+| `adversarial-review` | post-write (리뷰 단계) | 공격자 마인드, STRIDE+OWASP 4단계 리뷰 | 구현 완료 후 대규모 수정 필요할 수 있음 |
+| `cve-triage` | issue-triggered (CVE 발생 후) | CVE 평가, 재현 분석, 패치 검증 | 알려진 CVE에만 반응, 사전 예방 불가 |
+| **sec-agentshield-wrapper** | **pre-write (작업 시작 전)** | **사전 차단, 작업 진입 전 위험 식별** | 휴리스틱 기반, 구현 세부사항 미파악 |
+
+**핵심 차별점**: 이 스킬은 코드를 쓰기 _전에_ 실행한다. 작업 범위와 의도만으로 위험 패턴을 식별하여 설계 단계에서 보안 방향을 잡는다.
+
+## 워크플로우
+
+### 입력 형식
+
+```
+/sec-agentshield-wrapper "<변경 대상 파일/영역> — <변경 의도>"
+```
+
+예시:
+```
+/sec-agentshield-wrapper "auth-middleware.ts — refresh token 처리 추가"
+/sec-agentshield-wrapper "UserController.java — 외부 API 호출 기능 추가"
+/sec-agentshield-wrapper "upload.py — 파일 업로드 엔드포인트 신규 구현"
+```
+
+### 1단계: 트러스트 경계 영역 식별
+
+변경 대상 파일/영역이 트러스트 경계에 해당하는지 판단한다.
+
+**고위험 영역 분류**:
+
+| 영역 유형 | 예시 | 위험 수준 |
+|-----------|------|-----------|
+| 인증/인가 로직 | auth, jwt, session, permission | CRITICAL |
+| 외부 입력 처리 | request body, query params, file upload | HIGH |
+| 외부 API 호출 | HTTP client, SDK wrapper, webhook | HIGH |
+| 데이터 직렬화 | JSON parse, YAML, XML | MEDIUM |
+| 파일 시스템 접근 | read/write path, temp files | MEDIUM |
+| 설정/환경 변수 | config, env, secrets | HIGH |
+| 데이터베이스 쿼리 | raw SQL, ORM query builder | HIGH |
+
+CRG `query_graph` 활용 권장 — 변경 함수의 caller 체인을 추적하여 트러스트 경계 도달 여부를 확인한다.
+
+### 2단계: 위험 패턴 매칭
+
+변경 의도에서 다음 위험 패턴을 식별한다:
+
+**자동 트리거 패턴**:
+
+| 패턴 키워드 | 위험 유형 | 체크 항목 |
+|-------------|-----------|-----------|
+| token, jwt, session | 토큰 위조/재사용 | 서명 검증, 만료 처리, 재사용 방지 |
+| refresh, rotation | 토큰 갱신 경쟁 조건 | 원자성, 동시 요청 처리 |
+| upload, file, multipart | 파일 업로드 공격 | 확장자 검증, 경로 탐색, 크기 제한 |
+| admin, role, permission | 권한 상승 | 역할 검증, 최소 권한, 기본값 |
+| external, api, webhook | SSRF/외부 요청 | URL 화이트리스트, 타임아웃, 재시도 |
+| query, sql, filter | SQL 인젝션 | 파라미터화 쿼리, ORM 사용 여부 |
+| eval, exec, subprocess | 코드 실행 | 입력 새니타이즈, 허용 명령 목록 |
+| serialize, deserialize, pickle | 역직렬화 공격 | 신뢰할 수 없는 데이터 처리 여부 |
+| redirect, url, callback | 오픈 리다이렉트 | URL 검증, 도메인 화이트리스트 |
+
+### 3단계: Advisory 출력
+
+분석 결과를 3가지 레벨로 출력한다:
+
+- **PROCEED** — 식별된 고위험 패턴 없음, 표준 구현 진행 가능
+- **CAUTION** — 주의 필요 항목 존재, 체크리스트와 함께 진행
+- **BLOCK** — 설계 재검토 권장, 보안 전문가 리뷰 후 진행
+
+## 출력 형식
+
+```markdown
+## 보안 사전 분석 — sec-agentshield-wrapper
+
+**대상**: {파일/영역}
+**의도**: {변경 의도}
+**Advisory**: PROCEED | CAUTION | BLOCK
+
+### 트러스트 경계 분석
+
+| 영역 | 해당 여부 | 위험 수준 |
+|------|-----------|-----------|
+| {영역명} | Yes/No | CRITICAL/HIGH/MEDIUM/LOW |
+
+### 식별된 위험 패턴
+
+| 패턴 | 위험 유형 | 권장 사항 |
+|------|-----------|-----------|
+| {패턴} | {유형} | {권장} |
+
+### 구현 전 체크리스트
+
+- [ ] {체크 항목 1}
+- [ ] {체크 항목 2}
+
+### 권장 후속 작업
+
+- 구현 후: `adversarial-review` 로 공격자 관점 리뷰
+- 패턴 기반 분석: `sec-codeql-expert` 로 CodeQL 정적 분석
+- CVE 관련: `cve-triage` 로 의존성 취약점 확인
+```
+
+## 호출 패턴 예시
+
+**단일 파일**:
+```
+/sec-agentshield-wrapper "auth-middleware.ts — refresh token 처리 추가"
+```
+
+**여러 파일/영역**:
+```
+/sec-agentshield-wrapper "UserService.java, AuthController.java — OAuth2 로그인 플로우 추가"
+```
+
+**신규 기능**:
+```
+/sec-agentshield-wrapper "upload/ 디렉토리 — 사용자 파일 업로드 기능 신규 구현"
+```
+
+## 다른 자산과의 조합
+
+권장 보안 파이프라인:
+
+```
+sec-agentshield-wrapper (pre-write)
+  → 구현
+  → adversarial-review (post-write, 공격자 관점)
+  → sec-codeql-expert (post-write, 정적 분석)
+```
+
+CVE 발생 시 별도 트리거:
+```
+cve-triage (CVE 이슈 수신 시)
+  → sec-codeql-expert (영향 범위 분석)
+```
+
+## CRG 통합 (선택)
+
+CRG MCP 연결 시 1단계 트러스트 경계 분석 정확도가 향상된다:
+
+| CRG 도구 | 활용 목적 |
+|----------|-----------|
+| `query_graph` | 변경 함수의 caller 체인 추적, 트러스트 경계 도달 여부 확인 |
+| `get_impact_radius` | 변경의 영향 반경 파악, 위험 확산 범위 예측 |
+| `detect_changes` | 보안 관련 함수의 의미적 변경 감지 |
+
+CRG 미연결 시 Grep + Read 조합으로 fallback.
+
+## 한계
+
+- **휴리스틱 기반**: 키워드 매칭과 영역 분류 기반이므로 100% recall을 보장하지 않음
+- **구현 세부사항 미파악**: 실제 코드가 없으므로 로직 플로우 분석 불가
+- **False positive 가능성**: 보안 관련 키워드가 포함되어도 실제 위험이 없을 수 있음
+- **보완 필요**: 구현 후 `adversarial-review` + `sec-codeql-expert` 조합으로 보완 권장
+
+## Permission Mode
+
+이 스킬에서 Agent 도구를 사용하여 에이전트를 스폰할 경우, 항상 `mode: "bypassPermissions"` 를 전달해야 한다. Agent 도구의 기본값(`acceptEdits`)은 에이전트 frontmatter `permissionMode` 를 덮어쓰므로 무인 실행 중 권한 프롬프트가 발생할 수 있다.

package/templates/.claude/skills/semble-integration/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: semble-integration
+description: Semble (MinishLab) MCP wrapper — semantic code search via embeddings (98% token reduction vs grep+read, NDCG@10=0.854)
+scope: core
+version: 0.1.0
+user-invocable: true
+effort: low
+---
+
+# Semble Integration Skill
+
+[MinishLab/semble](https://github.com/MinishLab/semble) MCP 서버의 의미 기반 코드 검색 도구를 노출하는 wrapper 스킬.
+코드 인식 청킹 + 정적 임베딩 + BM25 + RRF 조합으로 transformer 수준 정확도를 CPU에서 달성한다.
+
+## 목적
+
+- **~98% 토큰 절감** (grep+Read 대비): 전체 파일 읽기 없이 의미적으로 관련된 코드 청크만 반환
+- **의미 기반 검색**: 자연어 쿼리로 "비슷한 코드 찾기", "에러 핸들링 패턴 검색" 등 구조 검색이 어려운 작업에 특화
+- **NDCG@10 = 0.854**: transformer 모델 수준 정확도를 CPU 인덱싱 (~250ms), 쿼리 (~1.5ms)로 달성
+- **R013 ecomode 보완**: context 사용량 ≥ 60% 시점에 Semble 호출로 추가 파일 읽기 비용 절감
+
+## CRG와의 보완 관계
+
+Semble과 CRG는 서로 다른 검색 축을 담당하며 상호 보완적이다.
+
+| 도구 | 검색 유형 | 강점 | 약점 |
+|------|----------|------|------|
+| `crg-integration` | 구조 (AST) | 호출 그래프, 영향 분석, recall-우선 | 의미 검색 약함 |
+| `semble-integration` | 의미 (임베딩) | 자연어 쿼리, "비슷한 코드 찾기" | 구조 정보 없음 |
+
+**사용 가이드**:
+- "이 함수의 caller는?" → CRG (`query_graph`)
+- "에러 핸들링 코드 패턴" → Semble
+- "변경 영향 범위" → CRG (`get_impact_radius`)
+- "인증 관련 코드 전부 찾기" → Semble (자연어 쿼리)
+
+## 노출 도구
+
+Semble MCP 서버가 제공하는 도구를 통해 다음 기능을 수행한다.
+구체적인 tool 이름은 MCP 서버 설치 후 Claude Code MCP introspection으로 확인한다.
+
+| 기능 | 설명 |
+|------|------|
+| 의미 검색 | 자연어 쿼리로 코드베이스 내 관련 청크 반환 |
+| 인덱싱 | 코드베이스를 code-aware 청킹 + 정적 임베딩으로 인덱싱 (CPU ~250ms) |
+| 결과 ranking | BM25 + RRF + embedding fusion으로 최종 랭킹 결정 |
+
+> 자세한 tool 사양은 `guides/token-efficiency/semble.md` 참조.
+
+## 설치 가이드
+
+> R001 정책: auto-install 스크립트 금지. 아래 명령어는 **사용자가 직접** 실행한다.
+
+### 1단계: 패키지 설치
+
+```bash
+# uv 기반 설치 (권장)
+uv tool install semble
+```
+
+### 2단계: MCP 서버 등록
+
+```bash
+# 방법 A: claude mcp 명령어 (권장)
+claude mcp add semble -- semble mcp
+
+# 방법 B: .mcp.json 수동 편집
+# 프로젝트 루트 또는 ~/.claude/.mcp.json 직접 수정
+```
+
+`.mcp.json` 수동 설정 예시:
+
+```json
+{
+  "mcpServers": {
+    "semble": {
+      "command": "semble",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+auto-install hook 또는 스크립트로 `.mcp.json`을 자동 수정하는 방식은 R001 위반이다.
+
+### 3단계: 인덱싱
+
+```bash
+# 명시적 인덱싱 (선택 — 첫 MCP 호출 시 lazy 인덱싱도 가능)
+semble index
+```
+
+자세한 설치/설정 절차는 `guides/token-efficiency/semble.md` 참조.
+
+## 사용 패턴
+
+### 의미 기반 코드 검색
+
+```
+"인증 미들웨어 관련 코드 찾아줘"
+→ Semble 의미 검색 → 관련 청크 반환 → 전체 파일 읽기 없이 컨텍스트 주입
+```
+
+### 패턴 검색
+
+```
+"에러 핸들링 컨벤션이 어떻게 되어 있어?"
+→ Semble "error handling convention" 쿼리 → 패턴 예시 청크 반환
+```
+
+### dev-review/adversarial-review와 조합
+
+```
+1. Semble로 유사 패턴 사전 조사
+2. /dev-review {focused_files} → 범위를 좁힌 리뷰
+```
+
+### CRG와 결합 사용
+
+```
+1. Semble "authentication related code" → 관련 파일 목록 식별
+2. CRG get_impact_radius(identified_files) → 영향 범위 확인
+3. 두 결과를 조합하여 완전한 컨텍스트 구성
+```
+
+## R013 Ecomode와의 관계
+
+R013 ecomode가 자동 활성화되는 시점 (context 사용량 ≥ 60%)에서 Semble을 적극 활용한다:
+
+| Ecomode 상황 | Semble 활용법 |
+|-------------|--------------|
+| 광범위 grep 대신 | Semble 의미 검색 → 관련 청크만 추출 |
+| 파일 전체 읽기 대신 | Semble으로 관련 섹션만 수신 |
+| 패턴 파악 시 | Semble 쿼리 → 대표 예시만 수집 |
+
+## 다른 자산과의 관계
+
+### 보완 관계 (함께 사용)
+
+| 자산 | 조합 방식 |
+|------|----------|
+| `crg-integration` | Semble (의미) + CRG (구조) 결합으로 완전한 코드 이해 |
+| `dev-review` | Semble로 유사 패턴 사전 조사 → dev-review 입력 최적화 |
+| `adversarial-review` | Semble로 관련 보안 패턴 수집 → adversarial-review 컨텍스트 보강 |
+
+### 대체 후보 (일부 use case)
+
+| 기존 방식 | Semble 대체 가능 여부 |
+|----------|---------------------|
+| `claude-mem:smart-explore` 의 자연어 탐색 | 일부 대체 가능 — 구조 탐색은 CRG 유지 |
+| grep + Read 조합의 패턴 검색 | 대체 권장 (98% 토큰 절감) |
+
+## 트러블슈팅
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| MCP 도구가 보이지 않음 | `.mcp.json` 미설정 또는 `claude mcp add` 미실행 | MCP 등록 확인, Claude Code 재시작 |
+| `command not found: semble` | uv tool install 미실행 또는 PATH 누락 | `uv tool install semble` 재실행, `which semble` 확인 |
+| 인덱싱 오류 | 초기 인덱싱 미완료 | `semble index` 실행 후 재시도 |
+| 검색 결과 없음 | 인덱싱 범위 외 또는 쿼리 불명확 | 인덱싱 재실행, 쿼리 구체화 |
+| 서버 연결 실패 | Semble MCP 서버 미실행 | MCP 서버 로그 확인, Claude Code 재시작 |
+| uv 미설치 | uv 패키지 매니저 없음 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` (사용자 직접 실행) |
+
+## 참고
+
+- 상세 설치/설정: `guides/token-efficiency/semble.md`
+- 관련 이슈: #1173 (scout:integrate Semble)
+- 기술 출처: [MinishLab/semble](https://github.com/MinishLab/semble)
+- 보완 자산: `crg-integration` (구조 기반 검색)