| name | codebase-audit |
| description | 프로젝트 전체를 대상으로 CLAUDE.md 헌법 및 시행령 문서 위반, 패턴 불일치, 코드 중복, 문서 동기화 문제를
5개 전문 에이전트로 병렬 검사하고 통합 감사 보고서를 생성하는 스킬입니다.
이 스킬은 다음 상황에서 사용됩니다:
- 정기 코드베이스 감사가 필요할 때
- 기술 부채 점검이 필요할 때
- 사용자가 "/codebase-audit", "코드베이스 감사", "아키텍처 감사" 등을 요청할 때
|
Codebase Audit
Purpose
프로젝트 전체(또는 지정 도메인)를 대상으로 기술 부채와 일관성을 점검하고,
CLAUDE.md 헌법 및 시행령 문서 준수 여부를 포함한 통합 감사 보고서를 생성한다.
검사 영역 (5가지)
| # | 영역 | 담당 에이전트 | 검사 내용 |
|---|
| 1 | 헌법 위반 | constitution-checker | CLAUDE.md 핵심 원칙 위반 |
| 2 | 시행령 위반 | policy-checker | docs/standards/*.md 규칙 위반 |
| 3 | 패턴 불일치 | pattern-analyzer | 같은 계층 내 구현 패턴 불일치 |
| 4 | 코드 중복 | duplication-detector | 유사 로직 반복 |
| 5 | 문서 동기화 | doc-sync-checker | 코드↔주석, 코드↔MD 불일치 |
Workflow
Step 0: 인자 파싱
/codebase-audit # 전체 감사
/codebase-audit user # user 도메인만 감사
/codebase-audit --focus=pattern # 패턴 검사만 수행
파싱 규칙:
- 도메인 인자: 첫 번째 비-옵션 인자 (예:
user, warehouse)
--focus 옵션: constitution, policy, pattern, duplication, doc-sync
도메인이 지정되면 해당 도메인 관련 파일만 검사 대상으로 한다:
modules/*/src/**/domain/{domain}/**modules/*/src/**/application/{domain}/**modules/*/src/**/persistence/{domain}/**modules/*/src/**/api/{domain}/**
Step 1: 프로젝트 컨텍스트 로드
- CLAUDE.md 읽기: 아키텍처 핵심 원칙 파악
- 시행령 문서 목록 확인: CLAUDE.md에서 참조하는 문서 경로 추출
docs/standards/messaging-policy.mddocs/standards/temporal-data-policy.mddocs/standards/query-pattern.mddocs/standards/validation-exception-policy.mddocs/standards/db-migration-policy.mddocs/standards/excel-export-policy.mddocs/standards/audit-logging-policy.mddocs/plans/ready/test-infrastructure-spec.md
- 이전 감사 보고서 확인:
docs/audits/AUDIT_*.md 중 가장 최근 파일
Step 2: 검사 대상 파일 수집
도메인이 지정된 경우 해당 도메인 파일만, 아니면 전체 modules/**/*.kt 대상.
제외 패턴:
*Test.kt, *Spec.kt (테스트 파일 - 일부 규칙에서 제외)build/, .gradle/
Step 3: 5개 에이전트 병렬 실행
반드시 단일 메시지에서 5개의 Task 도구를 동시에 호출하여 병렬 실행한다.
--focus 옵션이 있으면 해당 에이전트만 실행한다.
공통 프롬프트 규칙
모든 에이전트에게 다음 규칙을 전달한다:
필수: 최종 파일 상태 기반 검사
- 지적하기 전에 반드시 해당 파일을 Read 도구로 직접 읽어 현재 상태를 확인하라.
- 모든 지적에는 파일경로:라인번호, 클래스/함수명, 코드 근거가 포함되어야 한다.
필수: 기존 코드 패턴 참조
- 같은 계층(controller, service, adapter 등)의 기존 파일을 2-3개 Read로 읽어 기존 패턴을 파악하라.
- 기존 패턴과 다른 방식으로 구현된 부분을 지적하라.
필수: 심각도 기준
- 심각: 런타임 오류, 데이터 손실, 보안 취약점, 아키텍처 규칙 명백한 위반
- 중간: 유지보수성 저하, 컨벤션 불일치, 잠재적 버그
- 낮음: 코드 스타일, 가독성 개선, 더 나은 대안 존재
필수: 검사 범위
- 도메인이 지정된 경우: 해당 도메인 관련 파일만 검사
- 전체 감사: modules/ 하위 모든 Kotlin 파일 (테스트 제외)
에이전트별 상세 검사 항목은 references/checklist.md 참조.
Step 4: 결과 통합 및 보고서 생성
5개 에이전트 결과를 수집하여 통합 감사 보고서를 생성한다.
중복 제거: 동일한 파일·동일한 이슈는 가장 구체적인 하나만 남긴다.
보고서 경로: docs/audits/AUDIT_{YYYY-MM-DD}.md
보고서 형식: references/report-template.md 참조
Step 5: 트렌드 분석 (이전 감사 대비)
이전 감사 보고서가 있으면 비교 분석한다:
- 해결된 항목 수
- 새로 발생한 항목 수
- 영역별 증감 추이
Step 6: 결과 안내
✅ 코드베이스 감사가 완료되었습니다.
| 항목 | 결과 |
|------|------|
| 감사 범위 | 전체 / {domain} 도메인 |
| 검사 파일 수 | N개 |
| 헌법 위반 | X건 |
| 시행령 위반 | Y건 |
| 패턴 불일치 | Z건 |
| 코드 중복 | W건 |
| 문서 동기화 | V건 |
{이전 감사 대비 변화 요약}
보고서: docs/audits/AUDIT_{date}.md
CLI Reference
ls modules/*/src/main/kotlin/
rg "class.*Service" --type kotlin -l
rg "LocalDateTime" --type kotlin -l
rg "@DirtiesContext" --type kotlin
find modules -name "*.kt" -not -path "*/build/*" -not -name "*Test.kt"
ls -la docs/audits/AUDIT_*.md | tail -1
