kdyselfreflection — 클로드 코드 자기반성 및 체계 진화

프로젝트 개발 이력을 종합 분석하여 클로드 코드의 반복적 취약점·비효율 패턴을 도출하고, 기존 스킬/에이전트/개발 규칙 체계는 물론 MCP 서버/플러그인/Hooks까지 포괄적으로 진화시키는 메타 스킬입니다.

핵심 원칙

1. 증거 기반 분석: 추측이 아닌 실제 개발 이력 데이터에서 패턴 도출
2. 양방향 진화: 규칙을 추가만 하지 않음 — 해로운 규칙은 수정·삭제 제안
3. 사용자 최종 결정: 모든 변경은 사용자 승인 후 적용
4. 최소 변경 원칙: 검증된 문제에만 대응, 과잉 규칙 생성 금지
5. 범용성: 프로젝트 구조에 관계없이 Git 이력만으로도 동작 (docs 있으면 정밀도 향상)

인수 처리

사용자가 제공한 인수: $ARGUMENTS

기본 경로

PROJECT_ROOT      = {현재 프로젝트 또는 --project 경로}
GENERAL_PRO       = {--general-pro 경로 또는 자동 탐지 (선택적)}
DEV_RULES         = $GENERAL_PRO/01-dev-rules-system (GENERAL_PRO 있을 때만)
SKILLS_DIR        = $GENERAL_PRO/03-skills (GENERAL_PRO 있을 때만)
AGENTS_DIR        = $GENERAL_PRO/04-agents (GENERAL_PRO 있을 때만)
ANALYSIS_REF      = {스킬 디렉토리}/references/analysis-categories.md
IMPROVEMENT_TMPL  = {스킬 디렉토리}/references/improvement-templates.md

GENERAL_PRO 자동 탐지

--general-pro 인수가 없으면 다음 순서로 탐지:

1. 환경변수 GENERAL_PRO_PATH
2. CWD가 00-general-pro* 내부이면 해당 루트
3. ~/{develop,dev}/00-general-pro-web 존재 탐색
4. 탐지 실패 시 → 프로젝트 전용 모드 (글로벌 규칙 체계 없이 프로젝트 내부 규칙만 분석·수정)

Step 0-0: 체크포인트 확인

--resume 인수 또는 기존 체크포인트 파일 존재 시 중단 지점에서 재개합니다.

if --resume:
  Read: docs/references/_CHECKPOINT_KDYSELFREFLECTION.md
  → 마지막 완료 Phase 확인
  → "수집 데이터 요약" 로드 (Phase 0 재실행 불필요)
  → 해당 Phase 이후부터 재개
elif _CHECKPOINT_KDYSELFREFLECTION.md 파일이 이미 존재:
  AskUserQuestion: "이전 세션의 체크포인트가 있습니다. 재개/새로 시작?"
  → "재개" → 위 --resume 로직과 동일
  → "새로 시작" → 새 체크포인트 생성, Phase 0부터 정상 진행
else:
  새 체크포인트 생성, Phase 0부터 정상 진행

체크포인트 파일 위치: 대상 프로젝트의 docs/references/_CHECKPOINT_KDYSELFREFLECTION.md

Phase 0: 컨텍스트 수집

프로젝트의 개발 이력 데이터를 수집합니다. 데이터 가용성에 따라 자동으로 분석 모드를 결정합니다.

0-1. 프로젝트 식별 및 언어 감지

Read: $PROJECT_ROOT/CLAUDE.md
Read: $PROJECT_ROOT/docs/status/current.md (없으면 건너뜀)
Bash: git -C "$PROJECT_ROOT" log --oneline -5  # 커밋 메시지 언어 감지용

프로젝트명, 스택, 현재 상태를 파악합니다. 프로젝트 루트에 CLAUDE.md가 없으면 AskUserQuestion으로 프로젝트 경로를 재확인합니다.

프로젝트 언어 감지: 최근 5개 커밋 메시지를 분석하여 한국어/영어/혼합 판별. 이 결과는 Phase 1 Grep 패턴 선택에 사용됩니다.

0-2. 데이터 가용성 감지

다음 소스의 존재 여부를 확인하여 분석 모드를 결정합니다:

Glob: $PROJECT_ROOT/docs/handover/*.md
Glob: $PROJECT_ROOT/docs/logs/*.md
Glob: $PROJECT_ROOT/docs/references/_*.md
Glob: $PROJECT_ROOT/.claude/rules/*.md
Bash: git -C "$PROJECT_ROOT" log --oneline -1  # Git 이력 존재 여부

분석 모드 결정:

Git 이력조차 없으면 분석 불가 — 사용자에게 안내 후 종료합니다.

0-2-B. 부하 예측 및 볼륨 자동 분기

데이터 가용성 감지 직후, 인수인계 문서량과 분석 깊이를 기반으로 부하를 예측합니다.

handover_count = Glob docs/handover/*.md 파일 개수

if handover_count > 30 AND --depth == deep (기본값):
  AskUserQuestion:
    question: "인수인계 문서 {N}개. 전체 분석은 컨텍스트 한계 초과 가능성이 있습니다."
    options:
      - "최근 15개만 분석 (권장)" → --depth shallow 전환 + 최근 15개만 읽기
      - "전체 분석" → 체크포인트 빈도 증가 (Phase 1 완료 시 + Phase 2 완료 시)
      - "기간 지정" → --since 날짜 입력 요청

if --since <date> 지정:
  handover 파일을 날짜 필터링하여 <date> 이후 파일만 수집
  Git 이력도 --since 날짜로 필터링

0-2-C. 수집 전략 결정: 조건부 병렬화

분석 모드와 깊이에 따라 수집 단계(0-3 ~ 0-6)의 실행 방식을 결정합니다.

if --depth deep AND 분석 모드 == FULL:
  Task(Explore) × 4 병렬:
    A: 인수인계 수집 (0-3)
    B: 세션 로그 수집 (0-4)
    C: Git 이력 수집 (0-5)
    D: 레퍼런스 확인 (0-6)
else:
  기존 순차 수집 유지 (컨텍스트 절약)

0-3. 인수인계 문서 수집 (FULL/STANDARD 모드)

docs/handover/ 존재 시에만 실행.

Glob: $PROJECT_ROOT/docs/handover/*.md
Glob: $PROJECT_ROOT/docs/handover/archive/*.md (있으면 추가)

모든 인수인계 문서를 날짜 역순으로 읽습니다. --depth shallow 시 최근 5개만 읽습니다.

수집 항목:

• 세션별 작업 내용
• 발생한 이슈/장애
• 미완료 항목 및 사유
• 반복 언급되는 문제 키워드

0-4. 세션 로그 수집 (FULL/STANDARD 모드)

docs/logs/ 존재 시에만 실행.

Glob: $PROJECT_ROOT/docs/logs/*.md

세션 로그에서 다음을 추출합니다:

• 작업 시간 대비 완료율
• 반복된 시행착오 기록
• 에러/롤백 기록

0-5. Git 이력 수집 (모든 모드 — 핵심 데이터 소스)

Git 분석은 가장 객관적이고 범용적인 데이터 소스입니다. 모든 분석 모드에서 필수 실행됩니다.

# --depth deep (기본값)
Bash: git -C "$PROJECT_ROOT" log --oneline --since="3 months ago" -100
Bash: git -C "$PROJECT_ROOT" log --oneline --all --grep="fix\|revert\|rollback\|hotfix" --since="3 months ago"
Bash: git -C "$PROJECT_ROOT" log --diff-filter=M --name-only --pretty=format:"" --since="3 months ago" | sort | uniq -c | sort -rn | head -25

# --depth shallow
Bash: git -C "$PROJECT_ROOT" log --oneline --since="2 weeks ago" -30
Bash: git -C "$PROJECT_ROOT" log --oneline --all --grep="fix\|revert\|rollback\|hotfix" --since="2 weeks ago"
Bash: git -C "$PROJECT_ROOT" log --diff-filter=M --name-only --pretty=format:"" --since="2 weeks ago" | sort | uniq -c | sort -rn | head -15

Git 커밋에서 추출하는 핵심 지표:

0-6. 레퍼런스 상태 확인 (FULL/STANDARD 모드)

docs/references/ 존재 시에만 실행.

Glob: $PROJECT_ROOT/docs/references/_*.md

레퍼런스 파일의 최종 수정일과 실제 코드 상태의 괴리를 확인합니다.

0-7. 규칙 체계 로드

두 계층의 규칙을 독립적으로 로드합니다:

# 1. 프로젝트 내부 규칙 (항상)
Glob: $PROJECT_ROOT/.claude/rules/*.md
Read: $PROJECT_ROOT/CLAUDE.md

# 2. 글로벌 규칙 체계 (GENERAL_PRO 탐지 성공 시에만)
Read: $ANALYSIS_REF
Glob: $DEV_RULES/**/*.md
Glob: $SKILLS_DIR/*/SKILL.md
Glob: $AGENTS_DIR/*.md

프로젝트 전용 모드($GENERAL_PRO 미탐지): 프로젝트 .claude/rules/와 CLAUDE.md만 분석 대상. 글로벌 모드($GENERAL_PRO 탐지 성공): 프로젝트 규칙 + 글로벌 규칙 체계 모두 분석 대상.

0-7.5. 인프라 현황 수집

--no-infra 인수가 없을 때만 실행합니다. 프로젝트의 현재 MCP/플러그인/Hooks 구성을 수집합니다.

# 1. MCP 서버 현황
Read: $PROJECT_ROOT/.mcp.json (없으면 "MCP 미설정" 기록)
# 글로벌 MCP 설정
Read: ~/.claude.json → mcpServers 섹션 추출 (없으면 건너뜀)

# 2. 플러그인 현황
Bash: claude plugin list 2>/dev/null || echo "플러그인 CLI 미지원"
Glob: $PROJECT_ROOT/.claude/settings.json → enabledPlugins 섹션
Glob: ~/.claude/settings.json → enabledPlugins 섹션

# 3. Hooks 현황
Read: $PROJECT_ROOT/.claude/settings.json → hooks 섹션 (없으면 "Hooks 미설정")
Read: $PROJECT_ROOT/.claude/settings.local.json → hooks 섹션 (없으면 건너뜀)
Read: ~/.claude/settings.json → hooks 섹션 (없으면 건너뜀)

# 4. 내부 카탈로그 로드 (GENERAL_PRO 있을 때)
Read: $GENERAL_PRO/02-reusable-code/14-mcp-catalog/README.md
Read: $GENERAL_PRO/03-skills/00-community-reference/hooks-patterns.md
Read: $GENERAL_PRO/03-skills/00-community-reference/plugin-system.md
Read: $GENERAL_PRO/03-skills/00-community-reference/useful-repos.md

수집 결과를 다음으로 정리합니다:

0-8. 수집 결과 표시

## Phase 0: 데이터 수집 완료

**분석 모드**: {FULL | STANDARD | GIT_ONLY}
**프로젝트 언어**: {한국어 | 영어 | 혼합}
**규칙 범위**: {프로젝트 전용 | 글로벌 + 프로젝트}

| 소스 | 수집량 |
|------|--------|
| 인수인계 문서 | N개 (또는 "없음 — Git 기반 분석") |
| 세션 로그 | N개월 분량 (또는 "없음") |
| Git 커밋 | N건 (fix/revert: M건, 비율: X%) |
| 핫스팟 파일 | Top N개 추출 |
| 레퍼런스 | N개 파일 (또는 "없음") |
| 프로젝트 규칙 | N개 |
| 글로벌 스킬 | N개 (또는 "N/A — 프로젝트 전용 모드") |
| 글로벌 에이전트 | N개 (또는 "N/A") |
| 글로벌 규칙 파일 | N개 (또는 "N/A") |
| MCP 서버 (프로젝트) | N개 (또는 "미설정") |
| MCP 서버 (글로벌) | N개 (또는 "미설정") |
| 플러그인 | N개 (또는 "미설정") |
| Hooks | N개 이벤트 (또는 "미설정") |
| MCP 카탈로그 | N개 가용 (또는 "N/A — --no-infra") |

분석을 시작합니다...

Phase 1: 패턴 분석

수집된 데이터에서 클로드 코드의 반복적 취약점을 도출합니다. 상세 분석 카테고리는 $ANALYSIS_REF를 참조합니다 (Phase 0-7에서 로드 완료).

1-1. 5대 분석 카테고리

TU (도구 사용 패턴) 카테고리는 제거되었습니다. 세션 내 도구 호출 로그에 외부에서 접근할 수 없어 분석이 사실상 불가능합니다.

--focus <category> 인수가 있으면 해당 카테고리만 분석합니다.

--focus 인수 → 내부 코드 매핑:

1-2. 핵심 데이터: Git 핫스팟 분석

모든 분석 모드에서 가장 먼저 실행합니다. 가장 객관적이고 범용적인 데이터입니다.

# 핫스팟 추출 (0-5에서 이미 수집)
# 결과 해석:
# - 문서 파일 (docs/, CLAUDE.md, .gitignore 등)은 제외하고 해석
# - 소스 파일 중 수정 빈도 상위 = "불안정 모듈"
# - 같은 파일에 대한 fix 커밋이 3건 이상 = "시행착오 핫스팟"

핫스팟에서 추출하는 패턴:

1. 같은 파일 반복 수정: 해당 파일의 커밋 메시지를 읽어 원인 파악
2. fix 커밋 집중 파일: 설계 문제 또는 요구사항 불명확
3. 연속 fix 패턴: commit A(fix) → commit B(fix same file) → 근본 원인 미해결

1-3. 패턴 추출: 다국어 Grep

프로젝트 언어(Phase 0-1에서 감지)에 따라 Grep 패턴을 분기합니다.

한국어 프로젝트:

Grep: pattern="(반복|재발|다시|또|같은 문제|이전에도|여전히|계속)", path="$PROJECT_ROOT/docs/handover/"
Grep: pattern="(실패|오류|에러|롤백|되돌|수정 필요|미완료|못|안 됨)", path="$PROJECT_ROOT/docs/handover/"
Grep: pattern="(과잉|불필요|삭제해야|제거|단순화|복잡)", path="$PROJECT_ROOT/docs/handover/"

영어 프로젝트:

Grep: pattern="(repeat|recur|again|same issue|still broken|keeps happening)", path="$PROJECT_ROOT/docs/handover/"
Grep: pattern="(fail|error|bug|rollback|revert|broken|not working|todo|fixme)", path="$PROJECT_ROOT/docs/handover/"
Grep: pattern="(unnecessary|overkill|simplify|remove|complex|over-engineer)", path="$PROJECT_ROOT/docs/handover/"

혼합 프로젝트: 한국어 + 영어 패턴 모두 실행.

GIT_ONLY 모드: docs Grep을 건너뛰고 Git 커밋 메시지만 분석:

Bash: git -C "$PROJECT_ROOT" log --oneline --all | grep -iE "fix|revert|rollback|hotfix|bug|error"
Bash: git -C "$PROJECT_ROOT" log --oneline --all | grep -iE "수정|에러|오류|되돌|버그"

세션 로그 분석 (FULL 모드):

Grep: pattern="(실패|재시도|타임아웃|중단|fail|retry|timeout)", path="$PROJECT_ROOT/docs/logs/"

1-4. 패턴 빈도 및 심각도 매핑

도출된 패턴을 빈도(발생 횟수)와 심각도(영향 범위)로 분류합니다:

1-5. 분석 결과 표시

## Phase 1: 패턴 분석 결과

### Git 핵심 지표

| 지표 | 값 | 판정 |
|------|-----|------|
| 전체 커밋 | N건 | - |
| fix/revert 커밋 | M건 (X%) | {정상(<30%) | 주의(30~60%) | 경고(>60%)} |
| 핫스팟 파일 | Top 5 나열 | - |
| 연속 fix 패턴 | N건 | - |

### 도출된 취약점 패턴

| # | 카테고리 | 패턴명 | 빈도 | 심각도 | 증거 |
|---|---------|--------|------|--------|------|
| 1 | CQ | {패턴 설명} | N회 | HIGH | {인수인계 날짜, Git 커밋} |
| 2 | WF | {패턴 설명} | N회 | MEDIUM | {세션 로그 위치} |
| ... | | | | | |

### 심각도 분포
- CRITICAL: N건
- HIGH: N건
- MEDIUM: N건
- LOW: N건

Phase 2: 다차원 교차 검증 (분기→통합)

도출된 패턴을 5개 차원에서 병렬 검증한 후 통합 매트릭스로 수렴합니다. --no-infra 지정 시 2-A, 2-B만 실행하고 2-C~2-E를 건너뜁니다.

분기점 ② 구조:

Phase 1 결과 (도출된 패턴 목록)
    │
    ├─→ 2-A: 규칙·스킬·에이전트 커버리지 ──┐
    ├─→ 2-B: 역효과 규칙 탐지 ─────────────┤
    ├─→ 2-C: MCP 서버 커버리지 ─────────────┤ (병렬 실행)
    ├─→ 2-D: 플러그인 커버리지 ─────────────┤
    └─→ 2-E: Hooks 커버리지 ────────────────┘
                                              │
                                    2-F: 통합 매트릭스 (CONVERGE)

2-A. 규칙·스킬·에이전트 커버리지 (기존)

두 계층에서 독립적으로 검색합니다:

# 프로젝트 내부 규칙 (항상)
Grep: pattern="{패턴 키워드}", path="$PROJECT_ROOT/.claude/rules/"

# 글로벌 규칙 체계 (GENERAL_PRO 있을 때만)
Grep: pattern="{패턴 키워드}", path="$DEV_RULES/"
Grep: pattern="{패턴 키워드}", path="$SKILLS_DIR/"
Grep: pattern="{패턴 키워드}", path="$AGENTS_DIR/"

결과를 다음으로 분류합니다:

2-B. 역효과 규칙 탐지 (기존)

프로젝트 내부 규칙 및 글로벌 규칙(있을 때) 중 다음 징후가 있는 규칙을 식별합니다:

삭제/수정 후보 판별 기준:

1. 사문화 규칙: 인수인계/로그에서 한 번도 언급되지 않는 규칙
2. 역효과 규칙: 해당 규칙 때문에 오히려 시간이 더 걸리거나 버그가 발생한 기록
3. 충돌 규칙: 다른 규칙과 상충하여 어느 쪽을 따를지 혼란 유발
4. 과잉 규칙: 실질적 가치 대비 Claude의 컨텍스트 윈도우를 과도하게 소비
5. 시대 착오 규칙: 기술 스택 변경으로 더 이상 유효하지 않은 규칙

각 규칙 파일에 대해:
  Read: {규칙 파일}
  Grep: 인수인계/로그에서 해당 규칙 키워드 언급 횟수
  판정: ACTIVE(활발히 참조) | DORMANT(거의 언급 없음) | HARMFUL(부정적 언급)

2-C. MCP 서버 커버리지 (NEW — 인프라 분기)

도출된 패턴을 해결할 수 있는 MCP 서버가 존재하는지 탐색합니다.

탐색 순서 (3계층):

# 1계층: 내부 카탈로그 매칭
Read: $GENERAL_PRO/02-reusable-code/14-mcp-catalog/README.md
→ 패턴 키워드 ↔ 카탈로그 카테고리/서버 설명 매칭

# 2계층: 현재 설정과 교차 확인
→ .mcp.json에 이미 있는 서버는 COVERED 처리
→ 카탈로그에 있지만 미설치 → GAP_MCP 후보

# 3계층: 외부 탐색 (GAP_MCP가 카탈로그에도 없을 때만)
WebSearch: "{패턴 키워드} MCP server" (최대 3건)
→ npm/GitHub에서 관련 MCP 서버 검색
→ 신뢰도 판별: 공식(@anthropic-ai, @modelcontextprotocol) > 커뮤니티(stars 100+) > 기타

패턴→MCP 매핑 휴리스틱:

2-D. 플러그인 커버리지 (NEW — 인프라 분기)

도출된 패턴을 해결할 수 있는 플러그인(Skills 번들)이 존재하는지 탐색합니다.

탐색 순서 (3계층):

# 1계층: 공식 Anthropic 플러그인 매칭
Read: $GENERAL_PRO/03-skills/00-community-reference/useful-repos.md
→ anthropics/skills 16개 공식 스킬 목록과 패턴 매칭

# 2계층: 커뮤니티 컬렉션 매칭
→ everything-claude-code 37개 스킬 목록과 패턴 매칭
→ awesome-claude-skills, awesome-agent-skills 카탈로그 참조

# 3계층: 외부 탐색 (1~2계층에서 매칭 없을 때만)
WebSearch: "claude code plugin {패턴 키워드}" (최대 3건)
→ GitHub/npm에서 관련 플러그인 검색
→ 보안 주의: Bash 명령 포함 플러그인은 "검토 필요" 플래그

패턴→플러그인 매핑 휴리스틱:

이미 설치된 플러그인과 교차 확인:

현재 설치된 플러그인 목록 (Phase 0-7.5에서 수집)과 비교
→ 이미 설치됨 → COVERED_PLUGIN
→ 미설치 + 패턴 매칭 → GAP_PLUGIN 후보

2-E. Hooks 커버리지 (NEW — 인프라 분기)

도출된 패턴을 자동 방지할 수 있는 Hooks가 존재하는지 분석합니다.

탐색 로직:

# 1. 현재 Hooks 현황 확인 (Phase 0-7.5에서 수집)
→ 등록된 이벤트/핸들러 목록

# 2. 패턴→Hook 매핑
→ 반복적 실수를 PreToolUse/PostToolUse Hook으로 자동 차단 가능한지 판별

# 3. 참조 패턴 확인
Read: $GENERAL_PRO/03-skills/00-community-reference/hooks-patterns.md
→ 커뮤니티 Hook 패턴과 매칭

패턴→Hook 매핑 휴리스틱:

이미 등록된 Hook과 교차 확인:

현재 등록된 Hooks (Phase 0-7.5에서 수집)과 비교
→ 이미 등록됨 → COVERED_HOOK (효과 판정: ACTIVE | DORMANT | HARMFUL)
→ 미등록 + 패턴 매칭 → GAP_HOOK 후보

2-F. 통합 교차 검증 매트릭스 (CONVERGE)

5개 분기의 결과를 하나의 통합 매트릭스로 수렴합니다.

## Phase 2: 교차 검증 결과 (통합)

### 통합 커버리지 매트릭스

| # | 패턴 | 차원 | 기존 커버리지 | 상태 | 관련 체계 | 범위 |
|---|------|------|-------------|------|----------|------|
| 1 | {패턴} | 규칙 | {규칙명} | GAP | - | {PROJECT | GLOBAL} |
| 2 | {패턴} | 스킬 | {스킬명} | WEAK | {파일 경로} | GLOBAL |
| 3 | {패턴} | MCP | {서버명} | GAP_MCP | {카탈로그 경로} | PROJECT |
| 4 | {패턴} | 플러그인 | {플러그인명} | GAP_PLUGIN | {설치 URL} | PROJECT |
| 5 | {패턴} | Hook | - | GAP_HOOK | {추천 이벤트} | PROJECT |
| ... | | | | | | |

### 차원별 요약

| 차원 | GAP | WEAK | CONFLICT | COVERED | 총 분석 |
|------|-----|------|----------|---------|--------|
| 규칙·스킬·에이전트 | N | N | N | N | N건 |
| MCP 서버 | N | - | - | N | N건 |
| 플러그인 | N | - | - | N | N건 |
| Hooks | N | - | - | N | N건 |

### 역효과 규칙 후보

| # | 규칙 파일 | 범위 | 문제 유형 | 증거 | 제안 |
|---|----------|------|----------|------|------|
| 1 | {파일 경로} | {프로젝트 | 글로벌} | CONFLICT | {상충 내용} | 수정/삭제 |
| ... | | | | | |

### 다차원 시너지 기회

동일 패턴을 여러 차원에서 동시에 해결할 수 있는 시너지 기회:
| # | 패턴 | 규칙 | MCP | 플러그인 | Hook | 시너지 효과 |
|---|------|------|-----|---------|------|-----------|
| 1 | {패턴} | {규칙 추가} | {서버 추가} | - | {Hook 추가} | {복합 효과 설명} |

Phase 3: 개선 제안 생성

분석 결과를 기반으로 구체적인 개선 제안을 생성합니다. 제안 템플릿은 $IMPROVEMENT_TMPL를 참조합니다.

3-1. 제안 유형

3-2. 적용 범위 (Scope) 결정

각 제안에 적용 범위를 명시합니다:

범위 결정 기준:

• 이 프로젝트에만 해당하는 문제 → PROJECT
• 여러 프로젝트에 걸쳐 반복될 수 있는 보편적 문제 → GLOBAL
• 프로젝트 전용 모드에서는 모든 제안이 PROJECT

3-3. 제안 생성 기준

새 스킬/에이전트 생성 기준:

• GAP 상태 패턴 중 빈도 3회 이상 + 심각도 HIGH 이상
• 기존 스킬/에이전트로 커버 불가능한 고유 영역
• 자동화 가능한 반복 작업

기존 체계 보완 기준:

• WEAK 상태 패턴 중 개선 가능한 구체적 방법이 있는 경우
• 기존 스킬에 Phase 추가 또는 규칙 확장으로 해결 가능한 경우

규칙 수정/삭제 기준:

• CONFLICT 상태로 판정된 규칙
• DORMANT + 컨텍스트 윈도우 비용이 높은 규칙
• HARMFUL로 판정된 규칙 (역효과 증거 있음)

MCP 서버 추가 기준:

• GAP_MCP 상태 + 패턴 빈도 2회 이상 + 카탈로그에 존재
• 외부 MCP 서버는 빈도 3회 이상 + 공식 패키지(@anthropic-ai, @modelcontextprotocol)만 자동 제안
• 커뮤니티 MCP 서버는 "검토 후 수동 설치" 안내로 제한

플러그인 설치 기준:

• GAP_PLUGIN 상태 + 패턴 빈도 2회 이상
• 공식 플러그인(anthropics/skills)은 적극 추천
• 커뮤니티 플러그인은 stars 1000+ 또는 검증된 출처만 추천, 나머지는 "참고용" 표기
• 보안 주의: Bash 명령 포함 플러그인은 반드시 "보안 검토 필요" 플래그

Hooks 추가 기준:

• GAP_HOOK 상태 + 패턴 빈도 3회 이상 (자동화 임계값)
• 단순 차단(PreToolUse exit 2)은 즉시 제안 가능
• 복합 로직(agent/prompt 타입)은 "설계 제안"으로만 제시, 구현은 사용자 판단

중요: 단 1~2회 발생한 문제를 위해 새 규칙을 만들지 않습니다. 빈도 3회 미만이면 "관찰 목록"에만 등록합니다. (MCP는 2회부터 제안 가능 — 설치가 쉽고 부작용이 적으므로)

3-4. 각 제안에 포함할 내용

### 제안 #{N}: {유형 아이콘} {제목}

**유형**: {NEW_SKILL | IMPROVE_AGENT | DELETE_RULE | ...}
**범위**: {PROJECT | GLOBAL}
**대상 파일**: {수정할 파일 경로}
**근거 패턴**: {Phase 1에서 도출된 패턴명}
**빈도**: {N}회 / **심각도**: {CRITICAL | HIGH | MEDIUM}
**증거**:
- {인수인계/로그/커밋 구체적 인용}
- {인수인계/로그/커밋 구체적 인용}

**현재 상태**: {기존에 어떻게 처리되고 있는지}

**제안 내용**:
{구체적 변경 사항 — 파일 경로, 추가/수정/삭제할 내용 개요}

**예상 효과**:
{이 변경으로 어떤 문제가 해결되는지}

**리스크**:
{부작용 가능성, 다른 체계에 미치는 영향}

3-5. 우선순위 정렬

제안을 다음 기준으로 정렬합니다:

1. 심각도 (CRITICAL > HIGH > MEDIUM > LOW)
2. 빈도 (높은 순)
3. 구현 용이성 (쉬운 것 우선)

Phase 4: 사용자 리뷰 및 승인

모든 제안을 사용자에게 제시하고 승인을 받습니다.

4-1. 전체 제안 요약 표시

## Phase 4: 개선 제안 검토

### 전체 요약

| # | 유형 | 범위 | 제안 | 근거 패턴 | 심각도 | 빈도 |
|---|------|------|------|----------|--------|------|
| 1 | 🆕 | GLOBAL | {제안 제목} | {패턴명} | HIGH | 5회 |
| 2 | ✏️ | PROJECT | {수정 대상 규칙} | {패턴명} | HIGH | 3회 |
| 3 | 🗑️ | GLOBAL | {삭제 대상 규칙} | {역효과 증거} | MEDIUM | - |
| ... | | | | | | |

총 N건 제안 (PROJECT: X건, GLOBAL: Y건)

4-2. 사용자 승인 요청

AskUserQuestion으로 승인 방식을 선택받습니다:

4-3. 개별 검토 모드

개별 검토 선택 시, 각 제안에 대해 AskUserQuestion:

Phase 5: 적용

승인된 제안을 실제로 적용합니다.

--scan-only 모드에서는 이 Phase를 건너뛰고 Phase 6으로 이동합니다.

5-1. 적용 순서

안전한 순서로 적용합니다:

분기점 ④ 구조:

승인된 제안 목록
    │
    ├─→ A: 규칙 계층 (안전 우선)
    │   ├─ 1. 규칙 삭제 (DELETE_RULE) — 불필요한 것부터 제거
    │   ├─ 2. 규칙 수정 (MODIFY_RULE) — 기존 내용 개선
    │   └─ 3. 규칙 추가 (ADD_RULE) — 새 규칙 생성
    │
    ├─→ B: 스킬/에이전트 계층
    │   ├─ 4. 기존 스킬/에이전트 보완 (IMPROVE_*) — 기존 파일 수정
    │   └─ 5. 새 스킬/에이전트 생성 (NEW_*) — 새 파일 생성
    │
    └─→ C: 인프라 계층 (--no-infra 시 건너뜀)
        ├─ 6. MCP 서버 추가 (ADD_MCP) — /kdymcp add 위임
        ├─ 7. 플러그인 설치 (ADD_PLUGIN) — 설치 명령 안내/실행
        └─ 8. Hooks 추가 (ADD_HOOK) — settings.json 편집

5-2. 프로젝트 범위 (PROJECT) 적용

# 프로젝트 규칙 수정
대상: $PROJECT_ROOT/.claude/rules/{규칙 파일}
  1. 기존 내용 Read
  2. 수정 사항 Edit 적용

# 프로젝트 CLAUDE.md 수정 (필요 시)
대상: $PROJECT_ROOT/CLAUDE.md
  1. 기존 내용 Read
  2. 수정 사항 Edit 적용

5-3. 글로벌 범위 (GLOBAL) 적용

$GENERAL_PRO 탐지 성공 시에만 실행됩니다.

규칙 삭제:

대상: $DEV_RULES/{규칙 파일}
0. Read: 대상 파일 전문 → Phase 6 보고서 "삭제된 규칙 백업" 섹션에 저장 (복구용)
1. 파일 삭제 또는 해당 섹션 제거 (Edit)
2. 상위 README.md / 인덱스에서 참조 제거

규칙 수정:

대상: $DEV_RULES/{규칙 파일}
1. 기존 내용 Read
2. 수정 사항 Edit 적용
3. 수정 이유를 주석 또는 changelog로 기록

규칙 추가:

대상: $DEV_RULES/{적절한 하위 디렉토리}/{새 파일명}.md
1. 가장 적합한 디렉토리 판별 (00~99)
2. 기존 규칙 파일 형식에 맞춰 작성
3. 상위 README.md에 참조 추가

기존 스킬/에이전트 보완:

대상: $SKILLS_DIR/{스킬명}/SKILL.md 또는 $AGENTS_DIR/{에이전트명}.md
1. 기존 파일 Read
2. 수정 사항 Edit 적용
3. 변경 내용을 Phase 6 보고서에 기록

새 스킬/에이전트 생성:

새 스킬:
  1. $SKILLS_DIR/{스킬명}/ 디렉토리 생성
  2. SKILL.md 작성 (기존 스킬 패턴 준수)
  3. 필요시 references/ 하위 파일 생성

새 에이전트:
  1. $AGENTS_DIR/{에이전트명}.md 작성 (기존 에이전트 패턴 준수)
  2. frontmatter (name, description, model, color) 포함

5-4. 인프라 계층 적용 (NEW)

--no-infra 모드에서는 이 섹션을 건너뜁니다.

MCP 서버 추가 (ADD_MCP):

# 카탈로그 내 서버 (자동 적용 가능)
→ /kdymcp add {서버명} 위임
→ .mcp.json에 설정 스니펫 추가
→ 필수 환경변수가 있으면 사용자에게 설정 안내

# 카탈로그 외 서버 (안내만)
→ 설치 명령 출력: npm install -g {패키지명}
→ .mcp.json 설정 스니펫 제공
→ "수동 검증 필요" 안내

플러그인 설치 (ADD_PLUGIN):

# 공식 플러그인 (자동 설치 가능)
→ 명령 실행: claude install-skill {URL}
→ 또는: claude plugin install {URL} --scope {project|user}

# 커뮤니티 플러그인 (안내만)
→ 설치 명령 출력 (실행하지 않음)
→ "보안 검토 후 수동 설치 권장" 안내
→ 주요 검토 포인트: Bash 명령, 외부 API 호출, 파일 접근 범위

Hooks 추가 (ADD_HOOK):

# 대상 파일 결정
→ 프로젝트 범위: $PROJECT_ROOT/.claude/settings.json
→ 글로벌 범위: ~/.claude/settings.json

# 적용 방법
1. 기존 settings.json Read
2. hooks 섹션 존재 확인
3. 새 이벤트 핸들러 추가 (Edit)
   - command 타입: 스크립트 경로 지정, 스크립트 파일 Write
   - prompt 타입: 프롬프트 텍스트 직접 삽입
   - agent 타입: 에이전트 프롬프트 + 도구 목록 삽입
4. 기존 hooks와 충돌 없는지 확인 (같은 이벤트+matcher에 중복 핸들러 방지)

5-5. 적용 진행 표시

## Phase 5: 적용 진행 중

### A: 규칙 계층
- [1/N] ✏️ [PROJECT] {규칙 파일} 수정 ✓
- [2/N] ➕ [PROJECT] {새 규칙 파일} 생성 ✓

### B: 스킬/에이전트 계층
- [3/N] 🔧 [GLOBAL] {스킬명} SKILL.md 보완 ✓
- [4/N] 🆕 [GLOBAL] {새 스킬명} 생성 ✓

### C: 인프라 계층
- [5/N] 🔌 [PROJECT] {MCP 서버} .mcp.json 추가 ✓
- [6/N] 📦 [PROJECT] {플러그인} 설치 완료 ✓
- [7/N] 🪝 [PROJECT] {Hook 이벤트} settings.json 추가 ✓
- ...

N건 적용 완료 (규칙: X건, 스킬/에이전트: Y건, 인프라: Z건).

Phase 6: 검증 및 보고

6-1. 일관성 검증

적용된 변경이 기존 체계와 충돌하지 않는지 검증합니다:

# 규칙/스킬/에이전트 검증 (기존)
1. 새/수정된 규칙 파일의 경로 참조가 유효한지 Glob으로 확인
2. 새 스킬의 frontmatter 형식 검증 (글로벌 모드)
3. 새 에이전트의 frontmatter 형식 검증 (글로벌 모드)
4. 상충하는 규칙이 새로 생기지 않았는지 Grep 교차 확인

# 인프라 검증 (NEW — ADD_MCP/ADD_PLUGIN/ADD_HOOK 적용 시)
5. .mcp.json JSON 구문 유효성 (Bash: node -e "JSON.parse(require('fs').readFileSync('.mcp.json'))")
6. 추가된 MCP 서버의 필수 환경변수 존재 확인
7. settings.json hooks 섹션 JSON 구문 유효성
8. Hook 스크립트 파일 존재 + 실행 권한 확인 (command 타입일 때)
9. 플러그인 설치 상태 확인 (claude plugin list)

6-2. CLAUDE.md 동기화 필요 여부 (글로벌 모드)

글로벌 모드에서 새 스킬/에이전트가 생성되었거나 인프라 변경이 있으면:

AskUserQuestion: "후속 동기화가 필요합니다. 어떻게 진행할까요?"

선택지:
  - 지금 직접 업데이트 (새로 생성된 항목만)
  - /kdyupdate 실행 (스킬/에이전트 테이블만 동기화)
  - /inception 실행 권장 (전체 동기화 — 의존성 맵 포함)
  - /kdymcp validate 실행 (MCP 변경 시 설정 검증)
  - 건너뛰기

6-3. 최종 보고서 출력

## kdyselfreflection 분석 완료

### 분석 요약

| 항목 | 값 |
|------|-----|
| 프로젝트 | {프로젝트명} |
| 분석 모드 | {FULL | STANDARD | GIT_ONLY} |
| 규칙 범위 | {프로젝트 전용 | 글로벌 + 프로젝트} |
| 분석 기간 | {시작일} ~ {종료일} |
| 데이터 소스 | 인수인계 N개, 로그 N개, 커밋 N건 |
| fix/revert 비율 | M/N건 (X%) |
| 도출 패턴 | N건 (C:{X} H:{Y} M:{Z} L:{W}) |
| 검증 차원 | 규칙·스킬·에이전트 + MCP({N}개 탐색) + 플러그인({N}개 탐색) + Hooks({N}개 탐색) |

### 적용된 변경

#### 규칙/스킬/에이전트

| # | 유형 | 범위 | 대상 | 변경 내용 |
|---|------|------|------|----------|
| 1 | {아이콘} | {PROJECT} | {파일 경로} | {요약} |
| ... | | | | |

#### 인프라 (MCP/플러그인/Hooks)

| # | 유형 | 범위 | 대상 | 변경 내용 |
|---|------|------|------|----------|
| 1 | 🔌 | {PROJECT} | {.mcp.json} | {서버명 추가} |
| 2 | 📦 | {PROJECT} | {플러그인명} | {설치 완료/안내} |
| 3 | 🪝 | {PROJECT} | {settings.json} | {Hook 이벤트 추가} |
| ... | | | | |

### 거부/보류된 제안

| # | 유형 | 제안 | 사유 |
|---|------|------|------|
| ... | | | |

### 관찰 목록 (빈도 부족, 다음 실행 시 재검토)

| # | 카테고리 | 패턴 | 현재 빈도 | 다음 검토 기준 |
|---|---------|------|----------|-------------|
| ... | | | | 3회 이상 시 제안 생성 |

### 다음 권장 작업
- {구체적 후속 조치}

6-4. 아카이브

$PROJECT_ROOT/docs/logs/ 디렉토리가 존재하면 기록합니다:

## [YYYY-MM-DD] kdyselfreflection — {프로젝트명}

- 분석 모드: {FULL | STANDARD | GIT_ONLY}
- 도출 패턴: N건 (C:{X} H:{Y} M:{Z} L:{W})
- 적용: PROJECT {N}건, GLOBAL {N}건
- 인프라: MCP {N}건, 플러그인 {N}건, Hooks {N}건
- 관찰 목록: {N}건
- 주요 변경: {요약 1줄}

글로벌 모드에서 $GENERAL_PRO/docs/logs/에도 기록합니다:

## [YYYY-MM-DD] kdyselfreflection — from {프로젝트명}

- 01-dev-rules-system 변경: {추가 N / 수정 N / 삭제 N}
- 스킬 변경: {신규 N / 보완 N}
- 에이전트 변경: {신규 N / 보완 N}
- 인프라 변경: MCP {N} / 플러그인 {N} / Hooks {N}

Superpowers 연계

이 스킬 실행 중 아래 superpowers 원칙을 적용한다.

예외사항

다음은 이 스킬의 범위 밖입니다:

1. 코드 직접 수정 — 이 스킬은 규칙/스킬/에이전트/인프라 체계만 다룸. 프로젝트 코드 수정은 해당 스킬(kdyconvention 등)이 담당
2. 1~2회 발생 이슈 — 빈도 3회 미만은 관찰 목록에만 등록, 규칙 생성 안 함 (MCP는 2회부터 제안 가능)
3. 사용자 미승인 변경 — Phase 4 승인 없이 어떤 파일도 수정하지 않음
4. 다른 프로젝트 코드 접근 — --project로 지정된 프로젝트의 docs/만 읽음 (src/ 코드 분석 안 함)
5. Git 이력 없는 프로젝트 — 분석 불가, 사용자에게 안내 후 종료
6. 커뮤니티 플러그인 자동 설치 — 보안 미검증 플러그인은 안내만 하고 자동 설치하지 않음
7. Hook 스크립트 복잡 로직 — agent/prompt 타입 Hook은 설계만 제안, 구현은 사용자에게 위임

관련 스킬/에이전트

사용 예시

# 현재 프로젝트의 개발 이력 분석 + 체계 개선
/kdyselfreflection

# 특정 프로젝트 분석
/kdyselfreflection --project {프로젝트 경로}/my-project

# 분석만 (변경 없음)
/kdyselfreflection --scan-only

# 코드 품질 카테고리만 집중 분석
/kdyselfreflection --focus code-quality

# 최근 5개 세션만 빠르게 분석
/kdyselfreflection --depth shallow

# 규칙 충돌만 집중 탐지
/kdyselfreflection --focus rule-conflict --scan-only

# general-pro 경로 명시
/kdyselfreflection --general-pro /home/user/dev/00-general-pro

# Git 이력만 있는 프로젝트 (docs 없이도 동작)
/kdyselfreflection --project /path/to/git-only-project

# 이전 세션에서 중단된 지점부터 재개
/kdyselfreflection --resume

# 특정 날짜 이후 이력만 분석
/kdyselfreflection --since 2026-02-01

# 최근 이력만 빠르게 + 특정 카테고리
/kdyselfreflection --depth shallow --focus code-quality --since 2026-02-10

# 인프라(MCP/플러그인/Hooks)까지 포함한 전체 분석
/kdyselfreflection --project {프로젝트 경로}/my-project

# 인프라 분석 제외 (규칙/스킬/에이전트만)
/kdyselfreflection --no-infra

# 스캔만 + 인프라 포함 (어떤 MCP/플러그인이 필요한지 확인)
/kdyselfreflection --scan-only --project {프로젝트 경로}/my-project