From 916a50992c7d8d918c0b7d35cc5c59d242d4a358 Mon Sep 17 00:00:00 2001 From: JiWoong Sul Date: Fri, 27 Mar 2026 16:52:52 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20=EC=9E=91=EC=97=85=20?= =?UTF-8?q?=ED=94=84=EB=A1=9C=ED=86=A0=EC=BD=9C=20=EC=B6=94=EA=B0=80=20?= =?UTF-8?q?=EB=B0=8F=20=EC=88=98=EC=A0=95=20=EA=B3=84=ED=9A=8D=20=EC=9E=91?= =?UTF-8?q?=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLAUDE.md: Claude-Gemini 교차 토론 프로토콜 추가 - CLAUDE.md: 존재하지 않는 디렉토리 3개 제거 - analysis/fix-plan: 4 Phase 수정 계획 (Claude-Gemini 합의) - .claude/agents/: dev 리뷰 에이전트 9개 복사 - .claude/skills/: 프로젝트 스킬 4개 복사 --- .claude/agents/dev-architecture.md | 95 +++++++++++ .claude/agents/dev-code-quality.md | 94 ++++++++++ .claude/agents/dev-devops.md | 101 +++++++++++ .claude/agents/dev-docs-sync.md | 95 +++++++++++ .claude/agents/dev-idea-alignment.md | 113 +++++++++++++ .claude/agents/dev-performance.md | 96 +++++++++++ .claude/agents/dev-security.md | 91 ++++++++++ .claude/agents/dev-supply-chain.md | 85 ++++++++++ .claude/agents/dev-test-coverage.md | 100 +++++++++++ .claude/skills/project-audit.md | 78 +++++++++ .claude/skills/project-diff-review.md | 69 ++++++++ .claude/skills/project-fix-plan.md | 61 +++++++ .claude/skills/project-health-score.md | 68 ++++++++ CLAUDE.md | 31 +++- analysis/fix-plan-2026-03-27.md | 97 +++++++++++ analysis/full-audit-2026-03-27.md | 226 +++++++++++++++++++++++++ analysis/supply-chain-review.md | 175 +++++++++++++++++++ 17 files changed, 1672 insertions(+), 3 deletions(-) create mode 100644 .claude/agents/dev-architecture.md create mode 100644 .claude/agents/dev-code-quality.md create mode 100644 .claude/agents/dev-devops.md create mode 100644 .claude/agents/dev-docs-sync.md create mode 100644 .claude/agents/dev-idea-alignment.md create mode 100644 .claude/agents/dev-performance.md create mode 100644 .claude/agents/dev-security.md create mode 100644 .claude/agents/dev-supply-chain.md create mode 100644 .claude/agents/dev-test-coverage.md create mode 100644 .claude/skills/project-audit.md create mode 100644 .claude/skills/project-diff-review.md create mode 100644 .claude/skills/project-fix-plan.md create mode 100644 .claude/skills/project-health-score.md create mode 100644 analysis/fix-plan-2026-03-27.md create mode 100644 analysis/full-audit-2026-03-27.md create mode 100644 analysis/supply-chain-review.md diff --git a/.claude/agents/dev-architecture.md b/.claude/agents/dev-architecture.md new file mode 100644 index 0000000..ede4aab --- /dev/null +++ b/.claude/agents/dev-architecture.md @@ -0,0 +1,95 @@ +--- +name: dev-architecture +description: Architecture review agent. Clean architecture compliance, SOLID principles, module boundaries, dependency direction, component coupling analysis +--- + +# Architecture Review Agent + +## Role +Evaluate the structural design and architectural health of a development project. +Answers: "Is this codebase well-structured, maintainable, and scalable?" + +## Input +Receives an absolute directory path. Must scan and analyze ALL source files and project structure within. + +## Analysis Framework + +### 1. Project Structure Analysis +- Directory layout and organization +- Separation of concerns (presentation / domain / data layers) +- Module boundaries and encapsulation +- File naming conventions consistency + +### 2. Dependency Direction +- Clean Architecture compliance: dependencies point inward only +- No domain layer depending on infrastructure/framework +- Circular dependency detection +- Import graph analysis + +### 3. SOLID Principles Compliance +- **S**: Single Responsibility — files/classes with multiple concerns +- **O**: Open/Closed — extensibility without modification +- **L**: Liskov Substitution — proper interface contracts +- **I**: Interface Segregation — bloated interfaces +- **D**: Dependency Inversion — concrete vs abstract dependencies + +### 4. Component Coupling & Cohesion +- Tight coupling indicators (god classes, shared mutable state) +- Cohesion assessment per module +- API surface area per module + +### 5. Design Pattern Usage +- Appropriate pattern application +- Anti-patterns detected +- Over-engineering indicators + +## Tools +- `Glob`: Scan project structure +- `Grep`: Search for patterns, imports, dependencies +- `Read`: Read source files +- `Bash`: Run dependency analysis tools if available + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] Architecture Review + +## Architecture Score: [1-10] + +## Project Structure +- Layout: [description] +- Layer separation: [GOOD/PARTIAL/NONE] + +## Dependency Direction +| Violation | File | Depends On | Should Be | +|-----------|------|-----------|-----------| + +## SOLID Compliance +| Principle | Score | Key Violations | +|-----------|-------|---------------| + +## Coupling/Cohesion +| Module | Coupling | Cohesion | Issues | +|--------|----------|----------|--------| + +## Critical Findings +1. [Finding + File:Line] +2. ... + +## Recommendations (Priority Order) +1. [Critical] +2. [Important] +3. [Nice-to-have] +``` + +## Brutal Analysis Principles +- **No sugar-coating**: If architecture is a mess, say "ARCHITECTURE IS A MESS" +- **Evidence required**: Every finding must reference specific file:line +- **Never hide negative facts**: Spaghetti code is spaghetti code + +## Claude-Gemini Cross-Debate Protocol +1. Claude runs analysis → draft +2. Gemini reviews: `gemini -y -p "{analysis + project context}" -o text` +3. Debate disagreements: `gemini -y -r latest -p "{debate}" -o text` +4. Only agreed findings in final output. Unresolved → "[NO CONSENSUS]" diff --git a/.claude/agents/dev-code-quality.md b/.claude/agents/dev-code-quality.md new file mode 100644 index 0000000..9680686 --- /dev/null +++ b/.claude/agents/dev-code-quality.md @@ -0,0 +1,94 @@ +--- +name: dev-code-quality +description: Code quality review agent. Code smells, complexity, naming, duplication, readability. Runs linters/analyzers if available +--- + +# Code Quality Review Agent + +## Role +Evaluate the code quality, readability, and maintainability of source code. +Answers: "Is this code clean, readable, and maintainable by a new developer?" + +## Input +Receives an absolute directory path. Scans all source files. + +## Analysis Framework + +### 1. Code Smells Detection +- Long methods (>60 lines), large files (>400 lines) +- Deep nesting (>3 levels) +- Magic numbers/strings +- Dead code, commented-out code +- God objects/classes + +### 2. Complexity Analysis +- Cyclomatic complexity per function +- Cognitive complexity +- Function parameter count (>3 = smell) + +### 3. Naming Conventions +- Consistency check (camelCase, snake_case, PascalCase) +- Descriptive vs cryptic names +- Boolean naming (is/has/should prefixes) +- Function naming (verb-first) + +### 4. Duplication +- Copy-paste code detection +- Similar logic in multiple places +- Opportunities for abstraction (only when 3+ occurrences) + +### 5. Readability +- Comment quality (meaningful vs noise) +- Code self-documentation level +- Early returns vs deep nesting + +### 6. Linter/Analyzer Results +- Run available linters (eslint, pylint, dart analyze, cargo clippy, etc.) +- Report warnings and errors +- Configuration quality of lint rules + +## Tools +- `Glob`, `Grep`, `Read`: Code scanning +- `Bash`: Run linters/analyzers + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] Code Quality Review + +## Quality Score: [1-10] + +## Code Smells +| Type | File:Line | Description | Severity | +|------|-----------|-------------|----------| + +## Complexity Hotspots +| Function | File | Complexity | Recommendation | +|----------|------|-----------|---------------| + +## Naming Issues +| File:Line | Current | Suggested | Rule | +|-----------|---------|-----------|------| + +## Duplication +| Pattern | Locations | Lines Duplicated | +|---------|-----------|-----------------| + +## Linter Results +- Tool: [name] +- Errors: [count] +- Warnings: [count] +- Key issues: ... + +## Top 5 Files Needing Refactor +1. [file] — [reason] +``` + +## Brutal Analysis Principles +- **No sugar-coating**: Bad code is bad code. Name it +- **Evidence required**: Every finding → file:line reference +- **Never hide negative facts**: If the codebase is unmaintainable, say so + +## Claude-Gemini Cross-Debate Protocol +Same protocol as all agents. Claude analyzes → Gemini reviews → debate → consensus only. diff --git a/.claude/agents/dev-devops.md b/.claude/agents/dev-devops.md new file mode 100644 index 0000000..078c606 --- /dev/null +++ b/.claude/agents/dev-devops.md @@ -0,0 +1,101 @@ +--- +name: dev-devops +description: DevOps review agent. CI/CD pipelines, Docker configuration, deployment setup, environment management, monitoring, logging +--- + +# DevOps Review Agent + +## Role +Evaluate the deployment, CI/CD, and operational infrastructure of the project. +Answers: "Can this be deployed reliably? Is it observable in production?" + +## Input +Receives an absolute directory path. Reads CI/CD configs, Dockerfiles, deployment scripts, env files. + +## Analysis Framework + +### 1. CI/CD Pipeline +- Pipeline configuration present? (GitHub Actions, GitLab CI, etc.) +- Build → Test → Deploy stages +- Branch protection rules +- Automated testing in pipeline +- Deployment automation level + +### 2. Containerization +- Dockerfile quality (multi-stage, layer caching, security) +- Docker Compose for local development +- Image size optimization +- Base image currency + +### 3. Environment Management +- .env handling (not committed, .env.example provided) +- Environment-specific configs (dev/staging/prod) +- Secret management strategy +- Configuration validation + +### 4. Deployment Configuration +- Infrastructure as Code (Terraform, Pulumi, etc.) +- Deployment strategy (blue-green, rolling, canary) +- Rollback capability +- Database migration strategy + +### 5. Monitoring & Logging +- Application logging implementation +- Error tracking (Sentry, etc.) +- Health check endpoints +- Metrics collection +- Alerting configuration + +### 6. Backup & Recovery +- Database backup strategy +- Disaster recovery plan +- Data retention policy + +## Tools +- `Glob`, `Read`: Config files +- `Bash`: Validate configs, check tool versions +- `Grep`: Search for logging/monitoring patterns + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] DevOps Review + +## DevOps Score: [1-10] + +## CI/CD +- Pipeline: [present/absent] +- Stages: [list] +- Issues: ... + +## Docker +- Dockerfile: [present/absent] +- Quality: [score] +- Issues: ... + +## Environment +- .env handling: [SAFE/RISKY] +- Secret management: [description] + +## Monitoring +- Logging: [present/absent] +- Error tracking: [present/absent] +- Health checks: [present/absent] + +## Critical Gaps +1. ... +2. ... + +## Recommendations +1. [Critical] +2. [Important] +``` + +## Brutal Analysis Principles +- **No sugar-coating**: No CI/CD in 2026 = amateur hour. Say it +- **Evidence required**: Reference specific config files +- **Never hide negative facts**: .env committed to git = CRITICAL + +## Claude-Gemini Cross-Debate Protocol +Same protocol. Claude analyzes → Gemini reviews → debate → consensus only. diff --git a/.claude/agents/dev-docs-sync.md b/.claude/agents/dev-docs-sync.md new file mode 100644 index 0000000..115bd4f --- /dev/null +++ b/.claude/agents/dev-docs-sync.md @@ -0,0 +1,95 @@ +--- +name: dev-docs-sync +description: Documentation sync review. README/SPEC/API docs vs actual code sync, missing docs, stale docs, API contract consistency +--- + +# Documentation Sync Review Agent + +## Role +Verify that all documentation accurately reflects the current state of the code. +Answers: "Can a new developer onboard using these docs? Are they truthful?" + +## Input +Receives an absolute directory path. Reads all markdown/doc files AND cross-references with source code. + +## Analysis Framework + +### 1. README Accuracy +- Setup instructions: do they actually work? +- Feature list: matches implemented features? +- Architecture description: matches actual structure? +- Environment variables: all documented? + +### 2. API Documentation +- All endpoints documented? +- Request/response schemas match code? +- Error codes documented? +- Authentication requirements clear? +- API contract consistency (versioning, naming conventions) + +### 3. SPEC/Design Documents +- Specs match implementation? +- Outdated design decisions still documented as current? +- Missing specs for implemented features? + +### 4. Code Comments +- Misleading comments (code changed, comment didn't) +- TODO/FIXME/HACK inventory +- JSDoc/docstring accuracy + +### 5. Configuration Documentation +- All config files explained? +- Default values documented? +- Deployment instructions complete? + +### 6. CLAUDE.md / Project Instructions +- Accurate project description? +- Build/test commands correct? +- Dependencies listed correctly? + +## Tools +- `Glob`, `Read`: Doc files and source code +- `Grep`: Cross-reference doc claims with code +- `Bash`: Test setup instructions if safe + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] Documentation Sync Review + +## Docs Score: [1-10] + +## README Issues +| Claim | Reality | File | Status | +|-------|---------|------|--------| +| | | | STALE/MISSING/WRONG | + +## API Doc Gaps +| Endpoint | Documented? | Accurate? | Issue | +|----------|------------|-----------|-------| + +## Stale/Misleading Content +| Doc File | Line | Issue | +|----------|------|-------| + +## TODO/FIXME Inventory +| Tag | File:Line | Content | Age | +|-----|-----------|---------|-----| + +## Missing Documentation +1. [What's missing] +2. ... + +## Recommendations +1. [Critical — blocks onboarding] +2. [Important — causes confusion] +``` + +## Brutal Analysis Principles +- **No sugar-coating**: Stale docs are worse than no docs — they actively mislead +- **Evidence required**: Cross-reference doc claims with actual code +- **Never hide negative facts**: If README setup instructions don't work, that's CRITICAL + +## Claude-Gemini Cross-Debate Protocol +Same protocol. Claude analyzes → Gemini reviews → debate → consensus only. diff --git a/.claude/agents/dev-idea-alignment.md b/.claude/agents/dev-idea-alignment.md new file mode 100644 index 0000000..82b6d42 --- /dev/null +++ b/.claude/agents/dev-idea-alignment.md @@ -0,0 +1,113 @@ +--- +name: dev-idea-alignment +description: Cross-references idea analysis recommendations with actual implementation. Checks what was recommended vs what was built, identifies gaps and deviations +--- + +# Idea-to-Implementation Alignment Agent + +## Role +Verify whether business idea analysis findings and recommendations are actually reflected in the development project. +Answers: "Did you build what the analysis told you to build? What's missing? What deviated?" + +## Input +1. **Analysis directory path** — containing all idea evaluation reports (market-intel, risk-guard, growth-hacker, sales-validator, biz-tech, ops-launcher, fortify, comprehensive) +2. **Project directory path** — the actual development project + +## Analysis Framework + +### 1. Tech Stack Alignment +- Recommended stack (from biz-tech agent) vs actual stack +- If different: is the deviation justified or problematic? +- Framework choices, database, infrastructure + +### 2. MVP Feature Alignment +- Must-have features (from biz-tech/mvp-scoping) — implemented? partially? missing? +- Should-have features — any premature implementation? +- Won't-have features — any scope creep into v2 features? + +### 3. Business Model Implementation +- Pricing tiers (from sales-validator) — reflected in code? +- Free/paid gates implemented? +- Payment integration present? +- Subscription management + +### 4. Risk Mitigation Implementation +- Security risks (from risk-guard) — addressed in code? +- Legal requirements (법정 양식, 면책조항) — implemented? +- Data security measures for sensitive data +- Platform dependency mitigations + +### 5. Growth/Marketing Readiness +- SEO optimization (from growth-hacker) — meta tags, SSR, sitemap? +- Analytics/tracking implemented? +- Referral/viral loop mechanisms? +- Onboarding flow quality + +### 6. Operational Readiness +- KPIs (from ops-launcher) — measurable in current code? +- Monitoring/logging for production +- Scaling preparation +- Backup/recovery mechanisms + +### 7. Competitor Differentiation +- Top differentiation points (from fortify) — visible in product? +- Competitor weaknesses exploited? +- Unique features actually built? + +## Tools +- `Read`: Analysis reports + source code +- `Glob`, `Grep`: Search codebase for specific implementations +- `Bash`: Run project, check configs + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] 아이디어-구현 정합성 리포트 + +## 정합성 점수: [0-100] + +## 1. 기술 스택 정합성 +| 영역 | 분석 권고 | 실제 구현 | 일치 | 비고 | +|------|----------|----------|------|------| + +## 2. MVP 기능 정합성 +### Must-Have +| 기능 | 권고 | 구현 상태 | 완성도 | +|------|------|----------|--------| +| | | ✅/🔄/❌ | % | + +### 스코프 크리프 (권고 외 구현) +| 기능 | 분석 분류 | 현재 상태 | 리스크 | +|------|----------|----------|--------| + +## 3. BM 구현 상태 +| 항목 | 권고 | 구현 | 상태 | +|------|------|------|------| + +## 4. 리스크 대응 구현 +| 리스크 | 권고 대응 | 구현 상태 | +|--------|----------|----------| + +## 5. 성장 준비도 +| 항목 | 권고 | 구현 | 상태 | +|------|------|------|------| + +## 6. 핵심 괴리 TOP 5 +1. [가장 큰 괴리] +2. ... + +## 7. 즉시 조치 필요 사항 +1. ... +``` + +## Brutal Analysis Principles +- **No sugar-coating**: If the analysis said "Must Have X" and it's not built, that's a CRITICAL gap +- **Evidence required**: File:line references for implementations, report references for recommendations +- **Track scope creep**: Building Won't-Have features while Must-Have features are incomplete = RED FLAG + +## Claude-Gemini Cross-Debate Protocol +1. Claude reads all analysis reports + scans codebase → alignment draft +2. Gemini reviews: `gemini -y -p "{alignment findings}" -o text` +3. Debate disagreements +4. Only agreed findings in final output diff --git a/.claude/agents/dev-performance.md b/.claude/agents/dev-performance.md new file mode 100644 index 0000000..464b937 --- /dev/null +++ b/.claude/agents/dev-performance.md @@ -0,0 +1,96 @@ +--- +name: dev-performance +description: Performance review agent. N+1 queries, memory patterns, bundle size, API response design, caching strategy, database indexing +--- + +# Performance Review Agent + +## Role +Identify performance bottlenecks and optimization opportunities. +Answers: "Will this code perform well under load? Where are the bottlenecks?" + +## Input +Receives an absolute directory path. Analyzes source code for performance anti-patterns. + +## Analysis Framework + +### 1. Database & Query Patterns +- N+1 query detection (ORM usage patterns) +- Missing indexes (based on query patterns) +- Unbounded queries (no LIMIT/pagination) +- Raw query vs ORM efficiency + +### 2. Memory & Resource Patterns +- Memory leak indicators (unclosed connections, event listener buildup) +- Large object creation in loops +- Unbounded caches +- Stream vs buffer for large data + +### 3. Frontend Performance (if applicable) +- Bundle size analysis +- Unnecessary re-renders +- Image optimization +- Lazy loading implementation +- Code splitting + +### 4. API Design +- Response payload size +- Pagination implementation +- Batch vs individual requests +- Compression (gzip/brotli) + +### 5. Caching Strategy +- Cache layer presence and placement +- Cache invalidation strategy +- Cache hit ratio design +- CDN usage + +### 6. Concurrency & Async +- Blocking operations in async context +- Parallel vs sequential execution where applicable +- Connection pooling +- Rate limiting implementation + +## Tools +- `Glob`, `Grep`, `Read`: Code analysis +- `Bash`: Run build tools, check bundle size + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] Performance Review + +## Performance Score: [1-10] + +## Database Issues +| Issue | File:Line | Impact | Fix | +|-------|-----------|--------|-----| + +## Memory Concerns +| Pattern | File:Line | Risk | +|---------|-----------|------| + +## Frontend (if applicable) +- Bundle size: +- Key issues: + +## API Optimization +| Endpoint | Issue | Recommendation | +|----------|-------|---------------| + +## Caching +- Current strategy: +- Gaps: + +## Top 5 Performance Hotspots +1. [file:line] — [issue] — [estimated impact] +``` + +## Brutal Analysis Principles +- **No sugar-coating**: N+1 in production = ticking time bomb. Say it +- **Evidence required**: File:line + estimated impact +- **Never hide negative facts**: Missing caching on hot paths is a critical finding + +## Claude-Gemini Cross-Debate Protocol +Same protocol. Claude analyzes → Gemini reviews → debate → consensus only. diff --git a/.claude/agents/dev-security.md b/.claude/agents/dev-security.md new file mode 100644 index 0000000..af44f85 --- /dev/null +++ b/.claude/agents/dev-security.md @@ -0,0 +1,91 @@ +--- +name: dev-security +description: Security review agent. OWASP Top 10, secrets in code, dependency vulnerabilities, auth/authz patterns, input validation +--- + +# Security Review Agent + +## Role +Identify security vulnerabilities and weaknesses in the codebase. +Answers: "Can this code be exploited? What are the attack surfaces?" + +## Input +Receives an absolute directory path. Scans all source files, configs, and environment files. + +## Analysis Framework + +### 1. Secrets Detection +- Hardcoded API keys, passwords, tokens +- .env files committed to repo +- Private keys in codebase +- Connection strings with credentials + +### 2. OWASP Top 10 +- Injection (SQL, NoSQL, OS command, LDAP) +- Broken authentication +- Sensitive data exposure +- XML External Entities (XXE) +- Broken access control +- Security misconfiguration +- Cross-Site Scripting (XSS) +- Insecure deserialization +- Using components with known vulnerabilities +- Insufficient logging & monitoring + +### 3. Authentication & Authorization +- Auth implementation review +- Session management +- Password hashing algorithm +- JWT handling (expiration, validation) +- Role-based access control (RBAC) implementation + +### 4. Input Validation +- User input sanitization +- File upload validation +- API parameter validation +- SQL parameterization + +### 5. Configuration Security +- CORS configuration +- HTTPS enforcement +- Security headers +- Rate limiting +- Error handling (information leakage) + +## Tools +- `Glob`, `Grep`, `Read`: Code scanning +- `Bash`: Run security scanners if available (npm audit, cargo audit, etc.) + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] Security Review + +## Security Score: [1-10] +## Critical Vulnerabilities: [count] + +## Secrets Found +| Type | File:Line | Severity | Action | +|------|-----------|----------|--------| + +## OWASP Findings +| Category | File:Line | Description | Severity | Fix | +|----------|-----------|-------------|----------|-----| + +## Auth/Authz Issues +- ... + +## Recommendations (Critical First) +1. [CRITICAL] ... +2. [HIGH] ... +3. [MEDIUM] ... +``` + +## Brutal Analysis Principles +- **No sugar-coating**: Security holes are security holes. No "minor concern" for critical vulns +- **Evidence required**: File:line for every finding +- **Never hide negative facts**: If secrets are in the repo, flag IMMEDIATELY + +## Claude-Gemini Cross-Debate Protocol +Same protocol. Claude analyzes → Gemini reviews → debate → consensus only. diff --git a/.claude/agents/dev-supply-chain.md b/.claude/agents/dev-supply-chain.md new file mode 100644 index 0000000..435b553 --- /dev/null +++ b/.claude/agents/dev-supply-chain.md @@ -0,0 +1,85 @@ +--- +name: dev-supply-chain +description: Dependency and supply chain review. Vulnerability scanning, license compliance (GPL etc.), package maintenance health, outdated packages +--- + +# Supply Chain & Dependency Review Agent + +## Role +Evaluate the health and risk of all third-party dependencies. +Answers: "Are our dependencies safe, legal, and maintained?" + +## Input +Receives an absolute directory path. Reads package manifests (package.json, Cargo.toml, pubspec.yaml, requirements.txt, etc.) + +## Analysis Framework + +### 1. Vulnerability Scanning +- Known CVEs in dependencies +- Run `npm audit` / `cargo audit` / `pip audit` / equivalent +- Severity classification (critical, high, medium, low) +- Transitive dependency risks + +### 2. License Compliance +- GPL/AGPL contamination risk (copyleft in commercial project) +- License compatibility matrix +- Unlicensed packages +- License obligation checklist + +### 3. Package Maintenance Health +- Last update date per dependency +- GitHub stars/activity (proxy for maintenance) +- Deprecated packages +- Single-maintainer risk (bus factor) + +### 4. Outdated Packages +- Major version behind count +- Security-relevant updates missed +- Breaking change risk assessment + +### 5. Dependency Bloat +- Total dependency count (direct + transitive) +- Unused dependencies +- Overlapping functionality (multiple libs for same purpose) + +## Tools +- `Read`: Package manifests, lock files +- `Bash`: Run audit tools, check package info +- `Grep`: Search for imports/requires + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] Supply Chain Review + +## Supply Chain Score: [1-10] + +## Vulnerabilities +| Package | Version | CVE | Severity | Fix Version | +|---------|---------|-----|----------|-------------| + +## License Issues +| Package | License | Risk | Action Required | +|---------|---------|------|-----------------| + +## Maintenance Health +| Package | Last Updated | Status | Risk | +|---------|-------------|--------|------| + +## Outdated (Major Behind) +| Package | Current | Latest | Behind | +|---------|---------|--------|--------| + +## Recommendations +1. [CRITICAL] ... +2. [HIGH] ... +``` + +## Brutal Analysis Principles +- **No sugar-coating**: GPL in a commercial SaaS = legal time bomb. Say it +- **Evidence required**: CVE numbers, license names, dates +- **Never hide negative facts**: Abandoned dependencies must be flagged + +## Claude-Gemini Cross-Debate Protocol +Same protocol. Claude analyzes → Gemini reviews → debate → consensus only. diff --git a/.claude/agents/dev-test-coverage.md b/.claude/agents/dev-test-coverage.md new file mode 100644 index 0000000..3448b6f --- /dev/null +++ b/.claude/agents/dev-test-coverage.md @@ -0,0 +1,100 @@ +--- +name: dev-test-coverage +description: Test quality review agent. Test coverage quality (not just %), edge cases, integration tests, mocking strategy, test reliability +--- + +# Test Coverage & Quality Review Agent + +## Role +Evaluate the testing strategy, quality, and reliability of the test suite. +Answers: "Can we trust these tests? Do they catch real bugs?" + +## Input +Receives an absolute directory path. Reads test files and analyzes test patterns. + +## Analysis Framework + +### 1. Test Presence & Structure +- Test directory organization +- Test file naming conventions +- Test runner configuration +- Test-to-source file mapping + +### 2. Coverage Quality (not just %) +- Critical paths covered? +- Edge cases tested? (null, empty, boundary values) +- Error paths tested? +- Happy path vs unhappy path ratio +- Lines covered ≠ logic covered + +### 3. Test Types +- Unit tests presence and quality +- Integration tests presence +- E2E tests presence +- API tests +- Appropriate level for each test + +### 4. Mocking Strategy +- Over-mocking (testing mocks, not code) +- Under-mocking (tests depend on external services) +- Mock consistency with real implementations +- Test doubles quality (spy, stub, mock, fake) + +### 5. Test Reliability +- Flaky test indicators (time-dependent, order-dependent) +- Test isolation (shared state between tests) +- Deterministic assertions +- Timeout handling + +### 6. Test Maintenance +- Brittle tests (break on refactor, not on bug) +- Test readability (arrange-act-assert pattern) +- Test naming (describes behavior, not implementation) +- DRY vs readable tradeoff + +## Tools +- `Glob`, `Read`: Test files +- `Bash`: Run test suite, check coverage +- `Grep`: Search test patterns + +## Output Format +Final deliverable in **Korean (한국어)**. + +```markdown +# [Project Name] Test Quality Review + +## Test Score: [1-10] + +## Coverage Overview +- Unit tests: [count] files, [coverage]% +- Integration tests: [count] +- E2E tests: [count] + +## Untested Critical Paths +| Feature/Path | Risk Level | Why It Matters | +|-------------|-----------|---------------| + +## Mocking Issues +| Test File | Issue | Impact | +|-----------|-------|--------| + +## Flaky/Brittle Tests +| Test | File:Line | Issue | +|------|-----------|-------| + +## Test Gaps (Priority) +1. [Critical — no test for core business logic] +2. [High — error paths untested] +3. [Medium — edge cases missing] + +## Recommendations +1. ... +``` + +## Brutal Analysis Principles +- **No sugar-coating**: 0% test coverage = "THIS PROJECT HAS NO SAFETY NET" +- **Evidence required**: File references for all findings +- **Never hide negative facts**: Tests that test mocks instead of code are worse than no tests + +## Claude-Gemini Cross-Debate Protocol +Same protocol. Claude analyzes → Gemini reviews → debate → consensus only. diff --git a/.claude/skills/project-audit.md b/.claude/skills/project-audit.md new file mode 100644 index 0000000..64bd60d --- /dev/null +++ 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 diff --git a/.claude/skills/project-diff-review.md b/.claude/skills/project-diff-review.md new file mode 100644 index 0000000..7047386 --- /dev/null +++ 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. diff --git a/.claude/skills/project-fix-plan.md b/.claude/skills/project-fix-plan.md new file mode 100644 index 0000000..771a871 --- /dev/null +++ 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. diff --git a/.claude/skills/project-health-score.md b/.claude/skills/project-health-score.md new file mode 100644 index 0000000..d90de90 --- /dev/null +++ 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. diff --git a/CLAUDE.md b/CLAUDE.md index df80248..6ed55eb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -55,12 +55,9 @@ lib/ │ │ ├── story_service.dart # 스토리 진행 │ │ └── ... # 기타 서비스 │ ├── model/ # 게임 상태 및 데이터 모델 - │ ├── animation/ # ASCII 애니메이션 데이터/렌더링 │ ├── audio/ # 오디오 서비스 │ ├── storage/ # 세이브/설정 저장소 │ ├── notification/ # 알림 서비스 - │ ├── constants/ # 상수 정의 - │ ├── l10n/ # 게임 데이터 번역 유틸 │ └── util/ # 유틸리티 (RNG, 로직 헬퍼 등) ├── features/ │ ├── front/ # 타이틀/세이브 선택 화면 @@ -141,3 +138,31 @@ type(scope): 한국어 설명 ``` Types: `feat`, `fix`, `refactor`, `test`, `docs`, `style`, `chore`, `perf` + +## 작업 프로토콜 + +### Claude-Gemini 교차 토론 (Cross-Debate) +모든 에이전트/스킬 실행 결과는 Claude와 Gemini가 독립 분석 후 토론하여 합의된 결과만 사용자에게 제공한다. + +``` +[실행 흐름] +1. Claude 에이전트 실행 → 초안 생성 +2. Gemini 동일 프롬프트 실행: + - 최초: gemini -y -p "{에이전트 프롬프트 + 컨텍스트}" -o text + - 후속: gemini -y -r latest -p "{토론 프롬프트}" -o text +3. 결과 비교 → 불일치 항목 식별 +4. Gemini와 불일치 항목 토론 (후속 호출) +5. 합의 시: 합의 내용만 출력 +6. 미합의 시: "[NO CONSENSUS]" 표기 + 양측 의견 병기 +``` + +### 에이전트/스킬 활용 +- 에이전트 정의: `.claude/agents/` (origin에서 복사) +- 스킬 정의: `.claude/skills/` (origin에서 복사) +- 비사소한 작업은 반드시 에이전트를 병렬 배포하여 진행 +- 작업 완료 조건: Gemini 토론 합의 완료 + +## 프로젝트 분석 리포트 + +- `analysis/full-audit-2026-03-27.md` — 9개 에이전트 전체 감사 (Health Score: 49/100) +- `analysis/supply-chain-review.md` — 의존성/라이선스/CVE 분석 diff --git a/analysis/fix-plan-2026-03-27.md b/analysis/fix-plan-2026-03-27.md new file mode 100644 index 0000000..93933bd --- /dev/null +++ b/analysis/fix-plan-2026-03-27.md @@ -0,0 +1,97 @@ +# Askii Never Die — 수정 계획 (Fix Plan) + +> 작성일: 2026-03-27 +> Claude-Gemini Cross-Debate 합의 완료 +> 기준: full-audit-2026-03-27.md (Health Score: 49/100) + +--- + +## 합의된 조정 사항 + +| 항목 | Claude 초안 | Gemini 의견 | 합의 | +|------|------------|------------|------| +| Crashlytics 배치 | Phase 4 | Phase 1 전진 | **Phase 4 유지** (오프라인 정책 충돌, 로컬 로그 대안) | +| IAP 검증 | 로컬 RSA + Secure Storage | 서버 검증 권고 | **로컬 RSA + Secure Storage** (서버 인프라 없음) | +| Force Update | 미포함 | 추가 권고 | **미포함** (오프라인 앱에서 구현 불가) | +| Code Obfuscation | 미포함 | 추가 권고 | **Phase 1에 추가** (빌드 설정 확인) | +| 공수 | P1:2-3일, P3:1-2주 | P1:4-5일, P3:2-3주 | **P1:5일, P3:3주** | + +--- + +## Phase 1: 보안 강화 + DevOps 기반 (5일) + +| # | 작업 | 근거 | 검증 방법 | +|---|------|------|-----------| +| 1-1 | CI 파이프라인 구축 | DevOps 2/10 → 6/10 | push 시 format+analyze+test 자동 실행 | +| 1-2 | 폰트 라이선스 파일 추가 | Supply Chain: OFL 의무 | assets/fonts/에 LICENSE 존재 | +| 1-3 | IAP 로컬 영수증 RSA 검증 | Security: Lucky Patcher 방어 | 검증 실패 시 구매 거부 테스트 | +| 1-4 | 구매 상태 flutter_secure_storage 전환 | Security: 평문 저장 제거 | 기존 SharedPreferences 마이그레이션 테스트 | +| 1-5 | 세이브 파일 HMAC 체크섬 | Security: 변조 감지 | 변조 세이브 로드 거부 테스트 | +| 1-6 | 난독화 설정 확인/적용 | Security: APK 디컴파일 방어 | --obfuscate + --split-debug-info 빌드 성공 | +| 1-7 | 중복 파일 제거 | Code Quality: 100% 중복 | features/arena/widgets/ascii_disintegrate_widget.dart 삭제 | +| 1-8 | cupertino_icons 제거 | Supply Chain: 미사용 ~280KB | pubspec.yaml에서 삭제 + flutter pub get | + +--- + +## Phase 2: 수익 보호 + 버전 업데이트 (5일) + +| # | 작업 | 근거 | 검증 방법 | +|---|------|------|-----------| +| 2-1 | AdMob 미디에이션 (AppLovin MAX) | Idea Alignment: 수익 보호 | AdMob 비활성 시 백업 네트워크 로드 | +| 2-2 | google_mobile_ads 5.3→7.x | Supply Chain: iOS Privacy Manifest | App Store 심사 통과 | +| 2-3 | freezed 2.x→3.x + build_runner 업데이트 | Supply Chain: 중단된 전이 의존성 | dart run build_runner build 성공 | +| 2-4 | CHANGELOG + 버전 태그 체계 | DevOps: 릴리즈 이력 | git tag 존재 | +| 2-5 | flutter_lints 5→6 업데이트 | Code Quality: 최신 lint | flutter analyze 통과 | + +--- + +## Phase 3: 아키텍처 개선 (3주, 점진적) + +| # | 작업 | 근거 | 검증 방법 | +|---|------|------|-----------| +| 3-1 | 핵심 서비스 인터페이스 정의 | Architecture: 인터페이스 0개 | abstract class 6개 이상 | +| 3-2 | DI 컨테이너 (GetIt) 도입 | Architecture: 싱글톤 6개 제거 | 싱글톤 0개, GetIt 등록 | +| 3-3 | ad/iap_service → core/infrastructure/ 이동 | Architecture: 엔진 프레임워크 오염 | core/engine/에 Flutter import 0개 | +| 3-4 | setState → ValueNotifier 세분화 | Performance: 50ms 전체 리빌드 | 프레임 드롭 측정 (before/after) | +| 3-5 | God Widget 분할 (arena_battle_screen) | Code Quality: 759 LOC | 400 LOC 이하 | +| 3-6 | progress_service.dart 분할 | Code Quality: 832 LOC | 각 서비스 200 LOC 이하 | +| 3-7 | 저장 시스템 테스트 작성 | Test Coverage: 0% | save/load/delete 라운드트립 테스트 | +| 3-8 | Model 직렬화 라운드트립 테스트 | Test Coverage: 0% | toJson→fromJson 동일성 검증 | + +--- + +## Phase 4: 콘텐츠/성장 (2주+) + +| # | 작업 | 근거 | 검증 방법 | +|---|------|------|-----------| +| 4-1 | Analytics 연동 (Firebase/PostHog) | Idea Alignment: DAU/리텐션 | 이벤트 로깅 확인 | +| 4-2 | 크래시 리포팅 (로컬 로그 또는 Crashlytics) | DevOps: 크래시 추적 | 에러 발생 시 로그 저장 | +| 4-3 | 피벗 후 시장 재분석 | Idea Alignment: 22/100 | idea-market-intel 리포트 | +| 4-4 | README 전면 재작성 | Docs Sync: 극빈약 | 6개 화면, 수익화, 다국어 반영 | +| 4-5 | ARCHITECTURE.md 작성 | Docs Sync: 없음 | 계층 구조, 데이터 흐름 문서화 | + +--- + +## 예상 점수 변화 + +| Phase 완료 | Architecture | Code Quality | Security | Performance | Test | Supply Chain | Docs | DevOps | 예상 총점 | +|-----------|:-----------:|:-----------:|:--------:|:-----------:|:----:|:-----------:|:----:|:------:|:---------:| +| 현재 (0%) | 5 | 6 | 5 | 7 | 5 | 6 | 5 | 2 | **49** | +| Phase 1 | 5 | 6.5 | 7.5 | 7 | 5.5 | 7 | 5 | 5 | **59** | +| Phase 2 | 5 | 7 | 7.5 | 7 | 5.5 | 8 | 5.5 | 6 | **64** | +| Phase 3 | 8 | 8 | 7.5 | 8 | 7 | 8 | 6 | 6 | **76** | +| Phase 4 | 8 | 8 | 7.5 | 8 | 7 | 8 | 8 | 7 | **80+** | + +--- + +## 제외된 항목 + +| 항목 | 제외 사유 | +|------|----------| +| Force Update | 오프라인 앱에서 네트워크 기반 버전 체크 불가 | +| IAP 서버 검증 | 서버 인프라 없음. 로컬 RSA 검증으로 대체 | +| Crashlytics Phase 1 | 오프라인 정책 충돌. Phase 4에서 로컬 로그 대안 검토 | + +--- + +*Claude-Gemini Cross-Debate 합의 완료 (2026-03-27)* diff --git a/analysis/full-audit-2026-03-27.md b/analysis/full-audit-2026-03-27.md new file mode 100644 index 0000000..0782546 --- /dev/null +++ b/analysis/full-audit-2026-03-27.md @@ -0,0 +1,226 @@ +# Askii Never Die - Full Project Audit Report + +**분석일**: 2026-03-27 +**분석 도구**: 9개 개발 리뷰 에이전트 (Claude-Gemini 교차 토론 적용) +**프로젝트**: Askii Never Die (오프라인 방치형 Idle RPG, Flutter) +**규모**: 61,000 LOC / 224개 Dart 파일 / 247개 테스트 (전부 통과) + +--- + +## Project Health Score: 49 / 100 + +| # | 영역 | 점수 | 가중치 | 가중 점수 | 핵심 이슈 | +|---|------|:----:|:------:|:---------:|-----------| +| 1 | Architecture | 5/10 | 15% | 7.5 | 인터페이스 0개, DI 부재, 싱글톤 6개, 엔진에 프레임워크 직접 의존 | +| 2 | Code Quality | 6/10 | 15% | 9.0 | 200 LOC 초과 47.6%, God Widget 2개, 100% 중복 파일 1쌍 | +| 3 | Security | 5/10 | 15% | 7.5 | IAP 로컬 영수증 검증 미구현, 세이브 무결성 없음, 구매 상태 평문 저장 | +| 4 | Performance | 7/10 | 10% | 7.0 | 매 50ms setState 전체 리빌드, 서비스 객체 반복 생성, SFX 캐싱 부재 | +| 5 | Test Coverage | 5/10 | 10% | 5.0 | 파일 커버리지 10%, 저장/전투틱/Model 직렬화 테스트 전무 | +| 6 | Supply Chain | 6/10 | 10% | 6.0 | 폰트 라이선스 미포함, google_mobile_ads 2 메이저 뒤처짐 | +| 7 | Docs Sync | 5/10 | 5% | 2.5 | CLAUDE.md에 존재하지 않는 디렉토리 3개, README 극빈약 | +| 8 | DevOps | 2/10 | 10% | 2.0 | CI/CD 완전 부재, 릴리즈 프로세스 미정립 | +| 9 | Idea Alignment | 22/100 | 10% | 2.2 | 완전 피벗 (RPS 격투 -> Idle RPG), 피벗 후 시장 재분석 없음 | +| | **합계** | | **100%** | **48.7** | | + +> **점수 해석**: 49점대는 "동작하는 프로토타입~알파" 수준. 제품으로서 기능하지만 프로덕션 배포에 필요한 품질/운영 기반이 미비. + +> **참고**: Keystore Git 노출은 개인 Git 서버에서 사용자가 허가한 사항이므로 이슈에서 제외. IAP는 서버가 없는 구조이므로 로컬 검증 강화 방안으로 조정. + +--- + +## CRITICAL Issues (즉시 조치 필요) + +### 1. CI/CD 파이프라인 완전 부재 [DevOps] +- **영향**: 빌드/테스트/린트 모두 수동. 깨진 코드 push 가능 +- **조치**: Gitea Actions 또는 GitHub Actions로 `dart format` + `flutter analyze` + `flutter test` 자동화 +- **예상 공수**: 반나절 + +### 2. AdMob 미디에이션 미구현 [Idea Alignment + Security] +- **영향**: AdMob 계정 정지 = 수익 즉시 소멸 (인디 개발자 가장 흔한 수익 소멸 시나리오) +- **조치**: AppLovin MAX 또는 IronSource 연동 +- **예상 공수**: 2-3일 + +--- + +## HIGH Issues (단기 조치) + +### 3. IAP 로컬 영수증 서명 검증 미구현 [Security] +- **파일**: `lib/src/core/engine/iap_service.dart:332-336` +- **영향**: 서버 없이도 로컬 서명 검증으로 캐주얼 크래킹(Lucky Patcher 등) 방어 가능 +- **조치**: + - **Google Play**: `purchase.verificationData.localVerificationData`에서 서명된 JSON 추출 -> Google Play Console의 공개 키(Base64 RSA)로 `RSASSA-PKCS1-v1_5 + SHA1` 서명 검증. `pointycastle` 패키지 활용 + - **Apple**: StoreKit 2의 JWS(JSON Web Signature) 토큰을 로컬에서 Apple 루트 인증서로 검증 + - **구매 상태 저장**: `shared_preferences` -> `flutter_secure_storage` (Android Keystore / iOS Keychain) +- **공수**: 1-2일 +- **한계**: 루팅+후킹 조합 공격은 로컬 검증으로 완전 차단 불가. 그러나 90%+ 캐주얼 크래킹 방어 가능 + +### 4. 구매 상태 평문 저장 [Security] +- **파일**: `iap_service.dart:65-66`, `monetization_state.dart:17-45` +- **조치**: shared_preferences -> flutter_secure_storage 전환 (3번 작업과 동시 진행) +- **공수**: 반나절 + +### 5. 세이브 파일 무결성 없음 [Security] +- **파일**: `save_service.dart:17-20` +- **조치**: HMAC-SHA256 체크섬 추가. 키는 앱 번들에 난독화 포함 +- **공수**: 반나절 + +### 6. Analytics 부재 [Idea Alignment] +- **영향**: DAU, 리텐션, 광고 시청률, IAP 전환율 측정 불가 +- **조치**: Firebase Analytics 또는 PostHog 연동 +- **공수**: 1일 + +### 7. 인터페이스 0개 + DI 부재 [Architecture] +- **영향**: 테스트 격리 불가, 싱글톤 6개로 모킹 원천 봉쇄 +- **조치**: GetIt 또는 생성자 주입 도입, 핵심 서비스 abstract class 정의 +- **공수**: 3-5일 (점진적) + +### 8. 매 50ms 전체 위젯 setState [Performance] +- **파일**: `game_play_screen.dart:352-368` +- **영향**: 모바일 프레임 드롭 원인 1순위 +- **조치**: ValueNotifier/Selector로 세분화된 상태 관리 +- **공수**: 1-2일 + +### 9. 저장 시스템 테스트 전무 [Test Coverage] +- **파일**: `save_repository.dart`, `save_service.dart`, `save_manager.dart` (6개 파일 모두) +- **영향**: 세이브 파일 손상 시 플레이어 데이터 영구 손실 +- **조치**: IOOverrides/임시 디렉토리 기반 저장/로드/삭제 테스트 작성 +- **공수**: 1일 + +--- + +## MEDIUM Issues (중기 개선) + +### 10. 폰트 라이선스 파일 미포함 [Supply Chain] +- JetBrainsMono (OFL), PressStart2P (OFL) LICENSE 파일 `assets/fonts/`에 추가 필수 + +### 11. google_mobile_ads 5.3.0 -> 7.0.0 업그레이드 [Supply Chain] +- iOS Privacy Manifest 미대응으로 App Store 심사 거절 리스크 + +### 12. God Widget 2개 분할 [Code Quality] +- `game_play_screen.dart` (736 LOC), `arena_battle_screen.dart` (759 LOC) + +### 13. progress_service.dart 832 LOC 분할 [Code Quality] +- Quest/Plot/Exp/Combat 서비스로 분리 + +### 14. 100% 중복 파일 제거 [Code Quality] +- `features/arena/widgets/ascii_disintegrate_widget.dart` 삭제 (shared/ 버전 사용) + +### 15. CLAUDE.md 디렉토리 구조 수정 [Docs Sync] +- `core/animation/` -> `shared/animation/`, `core/constants/` 삭제, `core/l10n/` -> `shared/l10n/` + +### 16. README 전면 재작성 [Docs Sync] +- 현재 프로젝트 초기 임시 메모 수준. 6개 화면, 수익화, 다국어 지원 등 전혀 반영 안 됨 + +### 17. 크래시 리포팅 도입 [DevOps] +- Firebase Crashlytics 또는 Sentry + +### 18. 엔진 계층 프레임워크 오염 제거 [Architecture] +- `ad_service.dart`, `iap_service.dart` 등을 `core/infrastructure/`로 이동 + +### 19. 피벗 후 시장 재분석 [Idea Alignment] +- "오프라인 Idle RPG + ASCII 아트" 시장 분석이 전무. idea-market-intel 재실행 필요 + +--- + +## LOW Issues (장기) + +- cupertino_icons 미사용 제거 (~280KB 절약) +- SFX 에셋 프리로드 및 캐싱 +- 모바일 포그라운드 복귀 시 전체 화면 재생성 최적화 +- gcd_simulation_test/balance_analysis_test를 실제 assert 포함 테스트로 전환 +- analysis_options.yaml lint rule 추가 (prefer_const_constructors, prefer_final_locals 등) +- CHANGELOG에 실제 릴리즈 이력 기록 +- Model 직렬화 라운드트립 테스트 작성 + +--- + +## Fix Plan (Eisenhower Matrix) + +``` + 긴급 (Urgent) 비긴급 (Not Urgent) + ┌──────────────────────────┬──────────────────────────┐ + 중요 │ DO FIRST (즉시) │ SCHEDULE (계획) │ + (Important) │ │ │ + │ 1. CI/CD 구축 │ 7. 인터페이스+DI 도입 │ + │ 2. AdMob 미디에이션 │ 12. God Widget 분할 │ + │ 3. IAP 로컬 서명 검증 │ 13. progress_service 분할│ + │ 4. 구매 상태 보안 저장 │ 18. 엔진 프레임워크 분리 │ + │ 5. 세이브 무결성 추가 │ 19. 피벗 후 시장 재분석 │ + │ 10. 폰트 라이선스 추가 │ 17. 크래시 리포팅 도입 │ + ├──────────────────────────┼──────────────────────────┤ + 덜 중요 │ DELEGATE (위임 가능) │ ELIMINATE (후순위) │ + (Less │ │ │ + Important) │ 6. Analytics 연동 │ 14. 중복 파일 제거 │ + │ 8. setState 세분화 │ 15. CLAUDE.md 수정 │ + │ 9. 저장 시스템 테스트 │ 16. README 재작성 │ + │ 11. google_mobile_ads 7.x│ + LOW 이슈 전체 │ + └──────────────────────────┴──────────────────────────┘ +``` + +--- + +## 실행 로드맵 (권장 순서) + +### Phase 1: 보안 강화 + DevOps 기반 (2-3일) +``` +1. CI 파이프라인 구축 (dart format + analyze + test) → verify: push 시 자동 실행 +2. 폰트 라이선스 파일 추가 → verify: assets/fonts/에 LICENSE.txt 존재 +3. IAP 로컬 영수증 서명 검증 구현 (Google Play 공개키 RSA 검증) → verify: 검증 실패 시 구매 거부 테스트 +4. 구매 상태 flutter_secure_storage 전환 → verify: 기존 테스트 통과 +5. 세이브 파일 HMAC 체크섬 추가 → verify: 변조된 세이브 로드 거부 테스트 +``` + +### Phase 2: 수익 보호 (3-5일) +``` +1. AdMob 미디에이션 연동 (AppLovin MAX) → verify: AdMob 비활성 시 백업 네트워크 로드 +2. google_mobile_ads 7.x 마이그레이션 → verify: iOS Privacy Manifest 포함 확인 +3. CHANGELOG 정리 + 버전 태그 체계 수립 → verify: git tag 존재 +``` + +### Phase 3: 아키텍처 개선 (1-2주, 점진적) +``` +1. 핵심 서비스 인터페이스 정의 (SaveRepository, AdService, IAPService) +2. DI 컨테이너(GetIt) 도입 +3. ad_service, iap_service를 core/infrastructure/로 이동 +4. GamePlayScreen setState 세분화 +5. 저장 시스템 테스트 작성 +``` + +### Phase 4: 콘텐츠/성장 (2주+) +``` +1. Firebase Analytics 연동 +2. Crashlytics 연동 +3. 피벗 후 시장 재분석 (idea-market-intel 실행) +4. Web meta 태그 수정 + ASO 최적화 +5. README / CLAUDE.md / ARCHITECTURE.md 동기화 +``` + +--- + +## 에이전트별 상세 리포트 참조 + +| 에이전트 | 점수 | 주요 발견 | +|---------|:----:|----------| +| Architecture | 5/10 | 인터페이스 0개, 싱글톤 6개, core/engine/ Flutter 오염 6파일, app.dart God Class 459 LOC | +| Code Quality | 6/10 | dart format/analyze 통과, 200 LOC 초과 100개(47.6%), God Widget 2개, var 31회 남용 | +| Security | 5/10 | IAP 로컬 서명 검증 미구현, 세이브 무결성 없음, 구매 상태 평문 저장 | +| Supply Chain | 6/10 | CVE 0, GPL 0, 폰트 라이선스 미포함, google_mobile_ads 2메이저 뒤처짐 | +| Performance | 7/10 | 50ms setState 전체 리빌드, 서비스 객체 매틱 재생성, SFX 캐싱 부재, RepaintBoundary 활용 양호 | +| Test Coverage | 5/10 | 247개 테스트 전통과, 파일 커버리지 10%, 저장/전투틱/Model 직렬화 테스트 전무 | +| Docs Sync | 5/10 | CLAUDE.md 존재하지 않는 경로 3개, README 극빈약, CHANGELOG 릴리즈 이력 없음 | +| DevOps | 2/10 | CI/CD 완전 부재, 릴리즈 프로세스 미정립, Crashlytics 없음 | +| Idea Alignment | 22/100 | 완전 피벗 (RPS -> Idle RPG), 수익화만 일치, 피벗 후 시장 재분석 없음, Analytics 부재 | + +--- + +## 제외된 이슈 + +| 이슈 | 제외 사유 | +|------|----------| +| Keystore + 비밀번호 Git 노출 | 개인 Git 서버(Gitea)에서 사용자가 허가한 운영 방식 | +| IAP 서버 측 영수증 검증 | 서버 없는 오프라인 앱 구조. 로컬 서명 검증으로 대체 권고 | + +--- + +*이 보고서는 Claude-Gemini 교차 토론을 통해 합의된 결과입니다.* +*9개 에이전트 병렬 실행, 총 분석 시간: ~6분* diff --git a/analysis/supply-chain-review.md b/analysis/supply-chain-review.md new file mode 100644 index 0000000..e00c936 --- /dev/null +++ b/analysis/supply-chain-review.md @@ -0,0 +1,175 @@ +# asciineverdie Supply Chain Review + +> 검토일: 2026-03-27 +> Flutter 3.35.3 / Dart 3.9.2 +> Claude-Gemini Cross-Debate 완료 (합의 도달) + +## Supply Chain Score: 6 / 10 + +| 항목 | 점수 | 비고 | +|------|------|------| +| 보안 (CVE) | 8/10 | 알려진 CVE 없음 | +| 라이선스 | 6/10 | GPL 오염 없음, 폰트 라이선스 파일 누락 | +| 유지보수 건강도 | 5/10 | google_mobile_ads 2 메이저 뒤처짐, build_runner 전이 의존성 중단 | +| 최신성 | 4/10 | 직접 의존성 7개 중 5개 메이저 버전 뒤처짐 | +| 의존성 비대화 | 7/10 | 직접 11개, 프로덕션 전이 포함 ~62개 (합리적 수준) | + +--- + +## 1. 취약점 (Vulnerabilities) + +| 패키지 | 버전 | CVE | 심각도 | 수정 버전 | +|--------|------|-----|--------|-----------| +| (해당 없음) | - | - | - | - | + +**결론:** OSV(Open Source Vulnerabilities) 데이터베이스 및 GitHub Advisory Database 기준, 현재 사용 중인 의존성 버전에서 알려진 CVE는 발견되지 않음. + +다만 `google_mobile_ads` 5.x는 최신 iOS Privacy Manifest 및 UMP(User Messaging Platform) 요구사항을 완벽히 지원하지 않을 가능성이 있어, App Store 심사 거절 리스크 존재. + +--- + +## 2. 라이선스 이슈 + +| 패키지/자산 | 라이선스 | 리스크 | 필요 조치 | +|------------|---------|--------|-----------| +| 모든 Dart 패키지 | BSD-3 / MIT / Apache-2.0 | 없음 | GPL 오염 없음 -- 상업적 사용 안전 | +| JetBrainsMono (폰트) | OFL-1.1 (추정) | 중간 | 라이선스 파일 미포함. `assets/fonts/`에 OFL.txt 추가 필요 | +| PressStart2P (폰트) | OFL-1.1 (추정) | 중간 | 라이선스 파일 미포함. `assets/fonts/`에 OFL.txt 추가 필요 | + +**폰트 라이선스 상세:** +- JetBrains Mono: JetBrains 배포, Apache 2.0 라이선스 +- Press Start 2P: Google Fonts 배포, OFL 라이선스 +- 두 폰트 모두 상업적 사용 가능하나, 라이선스 텍스트를 앱에 포함해야 하는 의무(attribution) 존재 +- 현재 `assets/fonts/` 디렉토리에 LICENSE 파일이 **전혀 없음** +- App Store / Play Store 심사에서는 보통 문제되지 않으나, 법적 리스크는 존재 + +--- + +## 3. 유지보수 건강도 + +| 패키지 | 현재 버전 | 상태 | 리스크 | +|--------|----------|------|--------| +| cupertino_icons | 1.0.8 | 정상 유지보수 | 낮음 (단, 미사용) | +| intl | 0.20.2 | Dart 팀 관리 | 없음 | +| path_provider | 2.1.5 | Flutter 팀 관리 | 없음 | +| shared_preferences | 2.5.3 | Flutter 팀 관리 | 없음 | +| just_audio | 0.9.46 | 활발한 커뮤니티 (ryanheise) | 단일 메인테이너 리스크 | +| freezed_annotation | 2.4.4 | 활발한 커뮤니티 (rrousselGit) | 단일 메인테이너 리스크 | +| json_annotation | 4.9.0 | Google/Dart 팀 관리 | 없음 | +| google_mobile_ads | 5.3.1 | Google 관리 | **v5.x 지원 종료 임박** | +| in_app_purchase | 3.2.3 | Flutter 팀 관리 | 없음 | +| package_info_plus | 8.3.1 | FlutterCommunity 관리 | 낮음 | +| build_runner | 2.5.4 | Google/Dart 팀 관리 | **전이 의존성 중단됨** | + +**중단된 전이 의존성 (Discontinued transitive deps):** +- `build_resolvers` 2.5.4 -- 공식 중단 선언 +- `build_runner_core` 9.1.2 -- 공식 중단 선언 +- 이 패키지들의 기능은 최신 `build_runner`(2.10+)에 내재화됨 +- 즉각적인 빌드 실패를 일으키진 않으나, 향후 Dart SDK 업데이트 시 호환성 문제 발생 확실 + +--- + +## 4. 메이저 버전 뒤처짐 (Outdated - Major Behind) + +### 직접 의존성 (Direct) + +| 패키지 | 현재 | 최신 | 뒤처짐 | 비고 | +|--------|------|------|--------|------| +| google_mobile_ads | 5.3.1 | 7.0.0 | **2 메이저** | iOS Privacy Manifest, UMP 지원 필수 | +| freezed_annotation | 2.4.4 | 3.1.0 | 1 메이저 | freezed 3.x와 짝 맞춰야 함 | +| package_info_plus | 8.3.1 | 9.0.0 | 1 메이저 | | +| just_audio | 0.9.46 | 0.10.5 | 1 마이너 (pre-1.0) | 0.x 시맨틱에서는 마이너 = 메이저 | +| json_annotation | 4.9.0 | 4.11.0 | 2 마이너 | | + +### 개발 의존성 (Dev) + +| 패키지 | 현재 | 최신 | 뒤처짐 | 비고 | +|--------|------|------|--------|------| +| build_runner | 2.5.4 | 2.13.1 | 8 마이너 | 중단된 전이 의존성 해소 위해 업데이트 필요 | +| freezed | 2.5.8 | 3.2.5 | **1 메이저** | freezed_annotation 3.x와 함께 업데이트 | +| json_serializable | 6.9.5 | 6.13.1 | 4 마이너 | | +| flutter_lints | 5.0.0 | 6.0.0 | 1 메이저 | | + +--- + +## 5. 불필요한 의존성 + +| 패키지 | 사용 여부 | 판정 | 근거 | +|--------|----------|------|------| +| cupertino_icons | 미사용 | **제거 권장** | `lib/` 전체에서 `CupertinoIcons` import 0건. ~280KB 바이너리 낭비 | +| json_annotation | 간접 사용 | 유지 | freezed_annotation이 re-export하지만, .g.dart 생성 파일이 직접 import함. 제거 시 빌드 깨질 수 있음 | + +--- + +## 6. 의존성 트리 통계 + +| 항목 | 수치 | +|------|------| +| 직접 프로덕션 의존성 | 11개 (SDK 포함) | +| 직접 개발 의존성 | 6개 (SDK 포함) | +| 프로덕션 전이 포함 총 패키지 | ~62개 | +| 개발 포함 총 패키지 (pubspec.lock) | 122개 | +| 코드 생성 대상 파일 (.freezed.dart + .g.dart) | 8개 | + +--- + +## 권장 조치 사항 + +### [CRITICAL] 즉시 조치 + +1. **폰트 라이선스 파일 추가** + - `assets/fonts/JetBrainsMono-LICENSE.txt` (Apache 2.0) + - `assets/fonts/PressStart2P-OFL.txt` (OFL 1.1) + - 앱 내 오픈소스 라이선스 화면에 표시 필요 + - Google Fonts 및 JetBrains 공식 사이트에서 다운로드 + +2. **google_mobile_ads 7.x 업데이트 계획 수립** + - iOS Privacy Manifest 대응 필수 (App Store 심사 거절 리스크) + - v7.0.0 마이그레이션 가이드: https://developers.google.com/admob/flutter/migration + +### [HIGH] 단기 조치 (1-2주) + +3. **cupertino_icons 제거** + ```yaml + # pubspec.yaml에서 삭제 + # cupertino_icons: ^1.0.8 + ``` + +4. **build_runner 체인 업데이트** + ```bash + flutter pub upgrade build_runner json_serializable + ``` + - 중단된 `build_resolvers`, `build_runner_core` 전이 의존성 해소 + - 빌드 성능 개선 기대 + +5. **freezed 2.x -> 3.x 마이그레이션** + - freezed_annotation + freezed 동시에 메이저 업데이트 + - 코드 생성 파일 전체 재생성 필요: `dart run build_runner build --delete-conflicting-outputs` + +### [MEDIUM] 중기 조치 (1개월) + +6. **just_audio 0.10.x 업데이트** + - Android 최신 버전 호환성 개선 + - 단일 메인테이너(ryanheise) 패키지이므로 대안(audioplayers) 검토도 병행 + +7. **package_info_plus 9.x 업데이트** + +8. **flutter_lints 6.x 업데이트** + - 최신 lint 규칙 적용으로 코드 품질 향상 + +### [LOW] 장기 고려 + +9. **win32 전이 의존성** -- package_info_plus가 Windows 지원에 사용. 모바일 전용이면 무시 가능 + +--- + +## Claude-Gemini Cross-Debate 결과 + +| 항목 | Claude 의견 | Gemini 초기 의견 | 합의 | +|------|------------|-----------------|------| +| 종합 점수 | 6/10 | 3.5/10 | **6/10** (Gemini 수정 동의) | +| CVE-2023-48220 | 해당 없음 (Nextcloud 취약점) | package_info_plus 관련 주장 | **해당 없음** (Gemini 철회) | +| json_annotation 제거 | 위험 (빌드 깨짐 가능) | 제거 권장 | **유지** (Gemini 수정 동의) | +| build_runner 긴급도 | 중기 과제 (당장은 동작) | 즉시 수술 필요 | **단기 과제** (절충) | +| 보안 리스크 수준 | Low | Medium-High | **Low** (Gemini 수정 동의) | +| 폰트 라이선스 | 중간 리스크 | 중간 리스크 | **합의** |