docs: CLAUDE.md 작업 프로토콜 추가 및 수정 계획 작성

- CLAUDE.md: Claude-Gemini 교차 토론 프로토콜 추가 - CLAUDE.md: 존재하지 않는 디렉토리 3개 제거 - analysis/fix-plan: 4 Phase 수정 계획 (Claude-Gemini 합의) - .claude/agents/: dev 리뷰 에이전트 9개 복사 - .claude/skills/: 프로젝트 스킬 4개 복사
2026-03-27 16:52:52 +09:00
parent 6f5b3ba8f4
commit 916a50992c
17 changed files with 1672 additions and 3 deletions
--- a/.claude/skills/project-audit.md
+++ b/.claude/skills/project-audit.md
@@ -0,0 +1,78 @@
+# Project Audit Skill
+
+## Trigger
+`/project-audit [absolute_path]` or "프로젝트 감사", "코드 리뷰"
+
+## Description
+Runs all 8 dev review agents on a given directory path. Produces a unified audit report.
+
+## Input
+- Absolute directory path (e.g., `/Users/user/projects/my-app`)
+- The path MUST exist and contain a development project
+
+## Execution Workflow
+
+### Step 1: Reconnaissance
+- Scan directory structure (Glob)
+- Identify project type (language, framework)
+- Find entry points, configs, package manifests
+
+### Step 2: Parallel Analysis (4 agents)
+- `dev-architecture`: Structure and design
+- `dev-code-quality`: Code smells and readability
+- `dev-security`: Vulnerabilities and secrets
+- `dev-supply-chain`: Dependencies and licenses
+
+### Step 3: Parallel Analysis (4 agents, may use Step 2 context)
+- `dev-performance`: Bottlenecks
+- `dev-docs-sync`: Documentation accuracy
+- `dev-devops`: CI/CD and deployment
+- `dev-test-coverage`: Test quality
+
+### Step 4: Unified Report
+Merge all 8 agent results into a single audit document.
+
+## Context Window Management (Layered Analysis)
+For large projects, each agent follows this scan strategy:
+1. **L1 (Always)**: Entry points, configs, package manifests, README
+2. **L2 (Core)**: Core business logic, domain layer, API routes
+3. **L3 (On demand)**: Utilities, helpers, generated code — only if L1/L2 findings indicate issues
+
+## Output Format
+Final deliverable in **Korean (한국어)**.
+
+```markdown
+# [Project Name] 종합 감사 리포트
+
+## 종합 건강 점수: [0-100]
+
+## 요약 대시보드
+| 영역 | 점수(/10) | 상태 | 핵심 이슈 |
+|------|----------|------|----------|
+| Architecture | | 🟢/🟡/🔴 | |
+| Code Quality | | | |
+| Security | | | |
+| Supply Chain | | | |
+| Performance | | | |
+| Documentation | | | |
+| DevOps | | | |
+| Testing | | | |
+
+## Critical Findings (즉시 조치)
+1. ...
+
+## 상세 보고서 링크
+- [Architecture](./dev-architecture-report.md)
+- [Code Quality](./dev-code-quality-report.md)
+- ...
+```
+
+## Brutal Analysis Principles
+- Scores must reflect reality. A project with no tests and hardcoded secrets cannot score above 30
+- Cross-reference findings between agents (e.g., security finding + missing test = compounded risk)
+
+## Claude-Gemini Cross-Debate Protocol
+Each agent step includes Claude-Gemini debate. The unified report is also Gemini-reviewed.
+
+## Save Path
+`[project_path]/audit/project_audit_[date].md` or user-specified location
--- a/.claude/skills/project-diff-review.md
+++ b/.claude/skills/project-diff-review.md
@@ -0,0 +1,69 @@
+# Project Diff Review Skill
+
+## Trigger
+`/project-diff [absolute_path] [commit_range or PR#]` or "변경분 리뷰", "PR 리뷰"
+
+## Description
+Targeted review of a specific commit range or PR. Only analyzes changed files against the existing audit baseline. Much faster than full audit.
+
+## Input
+- Absolute project path
+- Commit range (e.g., `HEAD~3..HEAD`) or PR number
+- Optional: previous audit report for delta comparison
+
+## Execution Workflow
+
+### Step 1: Identify Changes
+- `git diff --name-only [range]` to get changed files
+- Categorize changes: new files, modified files, deleted files
+
+### Step 2: Targeted Analysis (only relevant agents)
+- Changed source files → `dev-code-quality`, `dev-architecture`
+- Changed security-related files → `dev-security`
+- Changed package files → `dev-supply-chain`
+- Changed test files → `dev-test-coverage`
+- Changed docs → `dev-docs-sync`
+- Changed CI/config → `dev-devops`
+- Performance-sensitive changes → `dev-performance`
+
+### Step 3: Impact Assessment
+- Does this change improve or degrade each dimension?
+- New technical debt introduced?
+- Existing issues fixed?
+
+## Output Format
+Final deliverable in **Korean (한국어)**.
+
+```markdown
+# [Project Name] Diff Review — [commit range]
+
+## Changes Summary
+- Files changed: [count]
+- Lines added: [count]
+- Lines removed: [count]
+
+## Review Results
+| File | Agent | Finding | Severity |
+|------|-------|---------|----------|
+| | | | |
+
+## Health Score Impact
+| Dimension | Before | After | Delta |
+|-----------|--------|-------|-------|
+
+## Approval Status
+- [ ] Security: PASS/FAIL
+- [ ] Architecture: PASS/FAIL
+- [ ] Tests: PASS/FAIL
+- [ ] Docs updated: PASS/FAIL
+
+## Verdict: [✅ APPROVE / ⚠️ REQUEST CHANGES / 🔴 BLOCK]
+```
+
+## Brutal Analysis Principles
+- A diff that adds code without tests should be flagged
+- A diff that changes API without updating docs should be flagged
+- Security regressions = automatic BLOCK
+
+## Claude-Gemini Cross-Debate Protocol
+For diff reviews, Claude analyzes → Gemini reviews the same diff → consensus on verdict.
--- a/.claude/skills/project-fix-plan.md
+++ b/.claude/skills/project-fix-plan.md
@@ -0,0 +1,61 @@
+# Project Fix Plan Skill
+
+## Trigger
+`/project-fix [absolute_path]` or "수정 계획", "개선 플랜"
+
+## Description
+Creates a prioritized action plan from audit findings. Groups fixes by urgency and effort.
+
+## Priority Framework (Eisenhower Matrix for Code)
+
+| | Low Effort | High Effort |
+|---|-----------|-------------|
+| **Critical** | 🔴 DO NOW (Sprint 0) | 🟠 PLAN (Sprint 1-2) |
+| **Important** | 🟡 SCHEDULE (Sprint 1) | ⚪ BACKLOG |
+
+## Categorization Rules
+- **Critical**: Security vulnerabilities, data loss risk, production blockers
+- **Important**: Architecture violations, performance bottlenecks, test gaps
+- **Low Effort**: < 2 hours, single file change
+- **High Effort**: > 1 day, multi-file refactor
+
+## Output Format
+Final deliverable in **Korean (한국어)**.
+
+```markdown
+# [Project Name] Fix Plan
+
+## 🔴 Sprint 0 — 즉시 (이번 주)
+| # | Finding | File | Effort | Agent |
+|---|---------|------|--------|-------|
+| 1 | | | ~Xh | Security |
+
+## 🟠 Sprint 1 — 계획 (다음 2주)
+| # | Finding | Files | Effort | Agent |
+|---|---------|-------|--------|-------|
+
+## 🟡 Sprint 2 — 예정 (이번 달)
+| # | Finding | Scope | Effort | Agent |
+|---|---------|-------|--------|-------|
+
+## ⚪ Backlog — 여유 시 진행
+| # | Finding | Scope | Effort | Agent |
+|---|---------|-------|--------|-------|
+
+## Estimated Total Effort
+- Sprint 0: ~X hours
+- Sprint 1: ~X days
+- Sprint 2: ~X days
+- Backlog: ~X days
+
+## Expected Score Improvement
+| Dimension | Current | After Sprint 0 | After Sprint 1 |
+|-----------|---------|----------------|----------------|
+```
+
+## Brutal Analysis Principles
+- Critical security fixes cannot be pushed to backlog — ever
+- Effort estimates must be realistic for a solo developer
+
+## Claude-Gemini Cross-Debate Protocol
+Priority classification disagreements are debated. Effort estimates are averaged.
--- a/.claude/skills/project-health-score.md
+++ b/.claude/skills/project-health-score.md
@@ -0,0 +1,68 @@
+# Project Health Score Skill
+
+## Trigger
+`/project-health [absolute_path]` or "프로젝트 건강 점수", "헬스 스코어"
+
+## Description
+Calculates a weighted health score (0-100) across all 8 dimensions from the project audit.
+
+## Scoring Weights
+
+| Dimension | Weight | Rationale |
+|-----------|--------|-----------|
+| Security | 20% | Vulnerabilities can kill a product |
+| Architecture | 15% | Foundation determines long-term viability |
+| Code Quality | 15% | Maintainability = team velocity |
+| Testing | 15% | Safety net for changes |
+| Supply Chain | 10% | Legal and security exposure |
+| DevOps | 10% | Deployment reliability |
+| Performance | 10% | User experience |
+| Documentation | 5% | Onboarding and maintenance |
+
+## Score Interpretation
+
+| Range | Grade | Meaning |
+|-------|-------|---------|
+| 90-100 | A | Production-ready, well-maintained |
+| 75-89 | B | Good, minor issues to address |
+| 60-74 | C | Acceptable, significant improvements needed |
+| 40-59 | D | Risky, major issues present |
+| 0-39 | F | Critical, not safe for production |
+
+## Output Format
+Final deliverable in **Korean (한국어)**.
+
+```markdown
+# [Project Name] Health Score
+
+## Overall: [Score]/100 — Grade [A/B/C/D/F]
+
+## Radar Chart Data
+| Dimension | Score | Weight | Weighted |
+|-----------|-------|--------|----------|
+| Security | /10 | 20% | |
+| Architecture | /10 | 15% | |
+| Code Quality | /10 | 15% | |
+| Testing | /10 | 15% | |
+| Supply Chain | /10 | 10% | |
+| DevOps | /10 | 10% | |
+| Performance | /10 | 10% | |
+| Documentation | /10 | 5% | |
+| **Total** | | **100%** | **/100** |
+
+## Trend (if previous audit exists)
+| Dimension | Previous | Current | Delta |
+|-----------|----------|---------|-------|
+
+## Bottom 3 (Biggest Improvement Opportunities)
+1. [Dimension] — [Score] — [Quick Win]
+2. ...
+3. ...
+```
+
+## Brutal Analysis Principles
+- Weighted score must be mathematically correct — no rounding in favor
+- Grade F projects must be called out explicitly
+
+## Claude-Gemini Cross-Debate Protocol
+Score disagreements > 1 point per dimension are debated until consensus.