AI 규칙 파일 점검하기, 리포트 읽는 법과 남길 줄 고르는 기준

1. 점검 돌리기와 리포트 읽는 법

한 줄로: 명령 한 줄로 내 규칙 파일들을 훑어서, 낡거나 틀리거나 부딪히는 지시를 리포트로 받아요.

왜 필요해요? 규칙 파일은 쓰고 나면 잘 안 보게 돼요. 이사 간 지 오래인데 옛날 주소가 적힌 메모처럼, 없는 파일을 가리키거나 서로 다른 말을 하는 줄이 쌓여요. 공식 문서에 따르면 두 지시가 부딪히면 AI가 아무거나 하나 고를 수 있어요.

따라 하기

1. 버전 확인 (터미널에서)

claude --version

2.1.283보다 낮으면 업데이트하세요.

claude update

2. 클로드 코드를 열고 점검 실행

/doctor prompt-audit

파일 하나나 폴더 하나만 보려면 경로를 붙여요.

/doctor prompt-audit CLAUDE.md
/doctor prompt-audit .claude/skills/deploy

리포트 읽는 법 — 항목마다 이 순서로 보세요.

고른 것만 적용하기 — 리포트를 보고 클로드한테 이렇게 말하세요.

방금 점검 리포트에서 [1, 3, 4]번만 적용해 줘. 나머지는 그대로 둬. 적용하기 전에 바뀌는 부분을 파일별로 보여 주고, 내가 좋다고 하면 그때 고쳐.

막히면

• 명령이 안 먹혀요: 버전이 2.1.283보다 낮거나, 내장 /claude-api 스킬을 꺼 둔 경우예요 (설정의 skillOverrides, disableBundledSkills). 점검이 그 스킬로 돌아가요.
• 리포트가 영어로 나오면: "리포트를 한국어로 정리해 줘"라고 덧붙이세요.

2. 남길 줄 고르는 기준 세 가지

뜬 걸 그대로 다 적용하면 안 돼요. 내 프로젝트에 아직 필요한 줄이 섞여 있을 수 있어요. 잘못 지우면 AI가 우리 규칙을 놓쳐요. 이 셋 중 하나라도 해당하면 지우지 말고 남기세요 (말투만 다듬는 건 괜찮아요).

무슨 일이 있어도 막아야 하는 건 규칙 파일만 믿지 마세요. 공식 문서는 규칙 파일을 "강제 설정이 아니라 참고"로 다룬다고 해요. 꼭 막아야 하는 동작은 훅(PreToolUse hook)으로 막으라고 안내해요.

3. 고친 예시 세 가지

예시 1. 강조 지우기 (예전 모델용 지시)

고치기 전

- IMPORTANT!! 작업이 끝나면 반드시 두 번 확인해!!!
- CRITICAL: 테스트 도구를 무조건 써라

고친 뒤

- 작업이 끝나면 `npm test` 를 한 번 돌려서 통과하는지 확인한다.
- 코드를 바꿨을 때는 테스트 도구를 쓴다.

포인트: 대문자·느낌표·"무조건"을 빼고, 무엇으로 확인하는지 구체적으로. 공식 가이드도 "CRITICAL: You MUST use this tool when…" 대신 "Use this tool when…"처럼 보통 말투로 쓰라고 해요.

예시 2. 이유 붙이기

고치기 전

- 절대 말줄임표(...) 쓰지 마.

고친 뒤

- 답변은 음성(TTS)으로 읽히니까 말줄임표(...)는 쓰지 않는다. 읽는 프로그램이 발음을 못 한다.

포인트: 왜 그런지 한 줄을 붙이면 AI가 목표를 알고 비슷한 경우(물결표·이모지 등)도 알아서 피해요. 공식 가이드에 나오는 예시를 우리말로 옮긴 거예요.

예시 3. 모순 합치기

고치기 전 (두 파일이 다른 말을 해요)

CLAUDE.md          : - 답은 짧게 한다.
.claude/rules/docs.md : - 설명은 자세히 한다.

고친 뒤 (CLAUDE.md 한 곳에)

- 대화 답변은 3줄 안으로 짧게 한다.
- 단, docs/ 폴더의 문서를 쓸 때는 단계별로 자세히 쓴다.

포인트: 둘 다 지우지 말고, 언제 어느 쪽인지 조건을 붙여 하나로 합쳐요.

4. 점검 뒤에 할 일

• 고친 뒤 /doctor prompt-audit 를 한 번 더 돌려서 같은 항목이 다시 안 뜨는지 봐요.
• 규칙 파일은 200줄 아래로 (공식 권장). 길수록 덜 지켜요.
• 새 모델이 나오거나, 규칙 파일을 크게 고친 뒤에 한 번씩 돌려요.

용어 정리

체크리스트

• claude --version 이 2.1.283 이상이다
• /doctor prompt-audit 를 돌려 리포트를 받았다
• 우리 프로젝트 사실·보안 규칙·이유 붙은 규칙은 남겼다
• 고른 번호만 적용했고, 적용 전에 바뀌는 부분을 확인했다
• 다시 점검해서 같은 항목이 안 뜬다

출처

• How Claude remembers your project › Audit your instruction files (2026-10-26 확인)
• Prompting best practices (2026-10-26 확인)