Convention Audit Skill

.claude/conventions/에 정의된 코드 컨벤션과 도메인 지식을 기준으로, 실제 구현 코드가 규칙을 준수하는지 자동 점검한다.

인자 파싱

• /convention-audit → 모드 선택 질문
• /convention-audit full → 전체 점검
• /convention-audit branch [branch-name] → 브랜치 비교 (기본: main)
• /convention-audit changes → 현재 변경사항 점검

실행 모드

실행 절차 (기본 모드)

Step 1: 대상 파일 수집

# 전체: apps/ packages/ 하위 *.py (alembic, __pycache__ 제외)
# 브랜치: git diff --name-only --diff-filter=ACMR <branch>...HEAD -- "*.py"
# 변경사항: git diff --name-only + git diff --cached --name-only

Step 2: 컨벤션 문서 로드

.claude/conventions/ 전체를 읽고 점검 규칙 추출.

핵심 매핑:

Step 3: 병렬 점검 (에이전트 분할)

대상 파일이 많을 경우 4개 에이전트로 분할:

Step 4: 결과 취합 및 리포트

# Convention Audit Report

- **모드**: [전체 / 브랜치 비교 (vs main) / 변경사항]
- **점검 일시**: YYYY-MM-DD HH:mm
- **대상 파일 수**: N개
- **위반 건수**: N개 (Critical: N, Warning: N, Info: N)

## Summary
| 컨벤션 | 위반 수 | 심각도 |
|--------|---------|--------|

## 상세 위반 사항
### [Critical] 03-layered-architecture: 레이어 위반
- **파일**: `path/to/file.py:42`
- **내용**: 위반 설명
- **컨벤션 규칙**: 해당 규칙 인용
- **수정 제안**: 구체적 수정 방법

심각도 기준:

• Critical: 아키텍처 위반, 보안 관련, 예외 suppress
• Warning: 네이밍 불일치, 패턴 미준수, 문서화 누락
• Info: 개선 권장, 스타일 제안

Step 5: 리포트 저장

./convention-audit-report.md에 저장.

자동 탐지 패턴

# 레이어 위반: Service에서 직접 session/query 사용
r"from.*models.*import|session\.(query|exec|execute)"  # in service files

# DTO suffix 점검
r"class\s+\w+(?<!Request|Response|RequestQuery|DTO)\(.*Base"  # in dto files

# 예외 suppress 탐지
r"except.*:\s*(pass|\.\.\.)"

# @with_transaction 누락 (DB 수정 메서드)
r"def\s+(create|update|delete|save|remove)"  # without @with_transaction

주의사항

• 컨벤션 문서가 없는 프로젝트에서는 실행 불가
• 위반 사항 자동 수정은 하지 않는다. 리포트만 만든다
• alembic/, __pycache__/, tests/ 기본 제외 (옵션으로 포함 가능)