review-rules

에이전트 지침 파일(AGENTS.md, CLAUDE.md, CLAUDE.local.md 등)을 모범사례에 근거해 진단하고, 개선안을 제시하는 스킬이다.

핵심 원칙: 진단 결과와 개선안을 먼저 보여주고, 사용자가 동의한 항목만 수정한다.

검사 대상 파일

프로젝트 루트에서 아래 파일들을 자동 탐색한다:

파일	유형
AGENTS.md	팀 공유
CLAUDE.md	Claude Code 팀 공유
CLAUDE.local.md	Claude Code 개인
GEMINI.md	Gemini CLI
.cursor/rules/*.mdc	Cursor
.roo/rules/*.md	Roo Code
.junie/guidelines.md	JetBrains Junie
.github/copilot-instructions.md	GitHub Copilot

존재하는 파일만 검사한다. 아무것도 없으면 안내한다:

"에이전트 지침 파일이 없습니다. /init-project-rules 로 먼저 생성하세요."

진단 항목

references/checklist.md를 읽고 전체 체크리스트를 확인한다.

1. 안티패턴 검출

ID	안티패턴	심각도	판단 기준
A1	자명한 조언	중	"write clean code", "follow best practices" 등 행동 변화 없는 문구
A2	린터/포매터 영역 침범	중	ESLint/Prettier/Biome 등이 존재하는데 들여쓰기, 세미콜론 등 포매팅 규칙을 명시
A3	코드로 알 수 있는 내용	중	package.json의 scripts를 그대로 복사, 디렉토리 구조를 tree 출력 그대로 나열
A4	낡은 참조	상	존재하지 않는 파일/디렉토리/함수를 언급
A5	도구 간 내용 중복	중	AGENTS.md와 CLAUDE.md에 같은 규칙이 중복
A6	모호한 경계	중	Boundaries 섹션 없음, 또는 Always/Ask/Never 구분 없이 나열
A7	개인 설정이 팀 파일에	상	AGENTS.md에 응답 언어, 개인 URL, 개인 습관 등이 포함

2. 토큰 효율성 분석

ID	항목	기준
T1	전체 길이	AGENTS.md: 150줄 이하 권장, 300줄 경고, 500줄 이상 위험
T2	섹션별 비중	특정 섹션이 전체의 40% 이상이면 분리 검토
T3	브릿지 비효율	CLAUDE.md가 @AGENTS.md가 아닌 내용을 중복 포함
T4	주석/설명 과다	규칙보다 설명이 많은 경우 (행동 지시 비율 < 50%)

3. 구조 점검

ID	항목	기준
S1	Commands 위치	파일 상단에 명령어 섹션이 없으면 권장
S2	코드 예시 부재	Code Style 섹션에 코드 스니펫 없이 설명만 있으면 개선 권장
S3	명령어 플래그 누락	npm test만 있고 -- --coverage 등 플래그가 없으면 보완 권장
S4	Boundaries 부재	Always/Ask/Never 3단계 경계가 없으면 추가 권장
S5	브릿지 누락	AGENTS.md는 있지만 CLAUDE.md 브릿지가 없으면 안내

워크플로우

1단계: 파일 수집 및 읽기

검사 대상 파일을 모두 읽고, 각 파일의 줄 수와 대략적 토큰 수(줄 수 × 3 으로 추정)를 집계한다.

2단계: 체크리스트 실행

references/checklist.md의 전체 항목을 순회하며 검사한다. 낡은 참조(A4) 검사 시에는 언급된 파일/디렉토리가 실제 존재하는지 확인한다.

3단계: 진단 보고서 출력

검사 결과를 심각도순(상 → 중 → 하)으로 정리하여 보고한다:

📋 Rules 진단 보고서

파일: AGENTS.md (187줄, ~561 토큰)
파일: CLAUDE.md (1줄, @AGENTS.md 브릿지)

--- 발견된 이슈 (5건) ---

🔴 [A4] 낡은 참조
   32행: `src/utils/auth.ts` — 해당 파일이 존재하지 않음
   → 제안: 해당 행 삭제 또는 실제 경로로 수정

🟡 [A2] 린터 영역 침범
   45-48행: "2칸 들여쓰기, 세미콜론 필수" — .prettierrc가 이미 이를 관리하고 있음
   → 제안: 해당 4줄 삭제 (Prettier가 자동 처리)

🟡 [T1] 길이 경고
   187줄 — 권장 150줄 이하. 현재 수준은 허용 범위이나 추가 시 주의
   → 제안: Code Style 섹션(52줄)을 줄일 수 있는지 검토

🟡 [A1] 자명한 조언
   71행: "항상 깨끗한 코드를 작성하세요"
   → 제안: 삭제 (구체적 행동 지시가 아님)

🟢 [S3] 명령어 플래그 누락
   12행: `npm test` — 커버리지나 단일 파일 실행 옵션 추가 권장
   → 제안: `npm test -- --coverage` 보완

--- 통과 항목 (12건) ---
✅ Commands 위치 적절
✅ Boundaries 3단계 구분 명확
✅ 브릿지 파일(CLAUDE.md) 존재
...

위 제안 중 적용할 항목을 알려주세요.
번호로 선택하거나 "전체 적용"도 가능합니다.

4단계: 사용자 동의 후 수정

사용자가 선택한 항목만 수정한다. 수정 시:

• 각 수정 건마다 어떤 행이 어떻게 바뀌는지 보여준다
• 한 번에 모아서 수정하되, 수정 전후 diff를 보여준다
• 사용자가 "전체 적용"이라고 하면 모든 제안을 일괄 적용한다

수정 완료 후 변경된 파일의 줄 수와 토큰 수를 다시 보여준다:

✅ 4건 적용 완료
   AGENTS.md: 187줄 → 171줄 (−16줄, ~48 토큰 절감)

금지 행위

• 사용자 동의 없이 파일을 수정하지 않는다
• 진단 결과가 없으면 "깨끗합니다"라고만 보고한다. 억지로 이슈를 만들지 않는다
• 파일 내용을 처음부터 다시 쓰자는 제안은 하지 않는다. 항상 부분 수정을 제안한다