클로드코드 지침 정리하기: prompt-audit 사용법

클로드코드를 쓰다 보면 같은 말을 반복하게 됩니다.

“기존 버튼을 먼저 찾아봐.” “수정한 뒤 테스트해줘.” “배포는 나한테 확인받고 해.”

이런 규칙을 매번 말하지 않으려고 CLAUDE.md에 적어둡니다. 클로드가 작업을 시작할 때 읽는 프로젝트 안내문이에요.

그런데 규칙을 계속 추가하다 보면 안내문도 정리가 필요해집니다. 이미 없어진 기능의 설명이 남아 있거나, 같은 말이 여러 곳에 적혀 있을 수 있어요.

prompt-audit은 이렇게 쌓인 클로드의 작업 지침을 점검하는 기능입니다. Claude Code 2.1.283에 추가됐습니다.

어떤 내용을 점검하나요?

공식 안내에 따르면 prompt-audit은 다음 내용을 살펴봅니다.

이름을 모두 외울 필요는 없습니다. 클로드에게 일을 맡기려고 적어둔 설명서들을 점검한다고 이해하면 됩니다.

특히 이전 모델에 맞춰 작성한 오래된 지시 방식을 찾습니다. 다만 어떤 문장을 반드시 찾아내는지, 어디까지 자동으로 고치는지는 공식 변경 기록에 자세히 나와 있지 않습니다.

결과를 받아본 뒤 지금 내 프로젝트에도 맞는 제안인지 확인해야 해요.

출처: Claude Code 공식 변경 기록 (새 탭에서 열림)

어떻게 실행하나요?

작업할 프로젝트에서 클로드코드를 열고 다음을 입력합니다.

/doctor prompt-audit

명령을 사용할 수 없다면 터미널에서 버전을 확인하세요.

claude --version

2.1.283보다 이전 버전이라면 업데이트가 필요할 수 있습니다.

claude update

실행 전에는 수정 중인 내용을 먼저 저장해두세요. 나중에 지침이 바뀌었을 때 이전 내용과 비교할 수 있어야 합니다.

Git을 사용한다면 현재 변경 내용을 확인하고, 완료한 작업을 커밋해두면 비교하기 편합니다. 커밋은 파일의 현재 상태를 기록하는 기능이에요.

결과는 세 가지 질문으로 살펴보세요

점검 결과에 어려운 설명이 많더라도 다음 세 가지만 생각하면 됩니다.

지금도 필요한가요?

이미 삭제한 기능이나 더 이상 쓰지 않는 명령을 설명한다면 정리할 수 있습니다.

예를 들어 로그인 방식을 바꿨는데 예전 로그인 도구의 사용법이 남아 있다면 클로드가 잘못된 방법을 따라갈 수 있어요.

같은 말을 반복하나요?

“기존 디자인을 따라라”라는 규칙이 여러 파일에 있다면 관리하기 어려워집니다. 한 곳만 고쳤을 때 다른 파일에는 예전 규칙이 남을 수도 있고요.

같은 규칙은 한곳에서 관리하고, 다른 곳에서는 필요한 내용을 참조하도록 정리할 수 있습니다.

모든 작업에서 필요한가요?

배포 절차는 배포할 때 필요합니다. 버튼의 문구를 바꾸는 작업에 긴 배포 설명까지 매번 전달할 필요는 적어요.

가끔 사용하는 긴 절차는 별도의 스킬로 옮기는 방법을 검토할 수 있습니다.

“꼼꼼하게 해줘”를 구체적인 요청으로 바꾸세요

다음과 같은 지침을 적어본 적 있나요?

실수하지 말고 꼼꼼하게 작업해.
수정한 뒤 충분히 확인해.
좋은 코드를 작성해.

원하는 마음은 전달되지만, 무엇을 해야 하는지는 모호합니다.

대신 확인할 행동을 적어보세요.

새 버튼을 만들기 전에 프로젝트에 비슷한 버튼이 있는지 찾아줘.

예약 화면을 수정하면 날짜 선택부터 예약 완료까지 확인해줘.

작업이 끝나면 바꾼 파일과 확인하지 못한 내용을 알려줘.

이렇게 쓰면 클로드도 무엇을 해야 하는지 알기 쉽습니다. 사용자도 요청을 지켰는지 확인할 수 있고요.

프로젝트에 정해진 테스트 명령이 있다면 그 명령을 적어두는 것도 좋습니다. 다만 다른 프로젝트의 명령을 그대로 복사하기보다 현재 프로젝트에서 실제로 사용하는지 먼저 확인하세요.

중요한 규칙까지 지우지는 마세요

설명서를 짧게 만드는 것이 유일한 목표는 아닙니다.

다음처럼 프로젝트에 꼭 필요한 규칙은 남겨야 합니다.

고객에게 이메일을 보내기 전에 내 확인을 받아줘.

이미 운영에 적용한 데이터 변경 파일은 고치지 마.

결제 금액은 서버에서 다시 확인해.

배포하기 전에 변경 내용과 확인 결과를 알려줘.

이런 규칙에는 과거에 겪은 문제나 업무상의 약속이 담겨 있을 수 있습니다. 클로드가 파일만 읽고 그 이유까지 모두 알기는 어려워요.

삭제를 제안받았다면 “이 규칙을 없애도 괜찮은 이유가 무엇인가?”를 먼저 물어보세요.

잘 모르겠다면 설명부터 요청하세요

점검 결과를 모두 이해한 뒤에만 작업할 필요는 없습니다. 클로드에게 쉬운 말로 풀어달라고 할 수 있어요.

방금 나온 prompt-audit 결과를 쉬운 말로 설명해줘.
아직 파일은 수정하지 마.

각 제안마다 다음 내용을 알려줘.
- 지금 어떤 규칙이 적혀 있는지
- 왜 바꾸자고 하는지
- 바꾸면 무엇이 좋아지는지
- 지웠을 때 문제가 생길 수 있는지

내가 판단해야 하는 항목은 따로 표시해줘.

설명을 읽고 확실한 항목부터 선택합니다.

이미 삭제한 기능의 설명과
완전히 같은 내용이 반복되는 부분만 정리해줘.

배포, 결제, 고객 정보와 관련된 규칙은 유지해줘.
끝나면 어떤 문장을 바꿨는지 보여줘.

처음부터 모든 지침을 새로 쓰게 하는 것보다 바꿀 범위를 정해주면 결과를 검토하기 쉽습니다.

정리한 뒤에는 작은 작업을 맡겨보세요

지침이 짧아졌다고 클로드가 일을 더 잘하게 됐다고 판단할 수는 없습니다.

새 대화를 열고 평소 자주 하는 작은 작업을 맡겨보세요.

예를 들어 예약 완료 화면의 안내 문구를 바꾸게 할 수 있습니다. 이때 다음을 확인합니다.

• 기존 화면과 버튼을 먼저 살펴봤나요?
• 요청한 부분만 바꿨나요?
• 필요한 확인 작업을 했나요?
• 바뀐 내용과 확인하지 못한 부분을 알려줬나요?

빠뜨린 규칙이 있다면 다시 보완하면 됩니다. 지침 정리는 한 번에 완벽하게 끝내는 작업이 아니에요.

언제 사용하면 좋을까요?

다음 상황이라면 한 번 점검해볼 만합니다.

• 프로젝트 안내문이 길어져 나도 읽기 어려울 때
• 클로드가 예전 작업 방식을 계속 따라갈 때
• 같은 규칙을 여러 파일에 복사해두었을 때
• 프로젝트 구조나 사용하는 도구가 크게 바뀌었을 때
• 모델을 바꾼 뒤 기존 지침이 여전히 필요한지 궁금할 때

처음에는 prompt-audit을 실행하고, 더 이상 사실이 아닌 설명과 중복된 규칙부터 살펴보세요.

중요한 결정은 남기고, 모호한 요청은 구체적인 행동으로 바꾸면 됩니다. 정리한 뒤에는 작은 작업으로 실제 결과를 확인해보세요.

CLAUDE.md 자체가 낯설다면 CLAUDE.md 작성법을, 반복 작업을 따로 정리하고 싶다면 클로드코드 스킬·서브에이전트·훅 사용법을 이어서 참고할 수 있습니다.

---

사실 확인 기준은 2026년 9월 27일입니다. 기능과 검사 대상은 공식 변경 기록 (새 탭에서 열림), 지침을 정리하는 방법은 공식 모범 사례 (새 탭에서 열림)를 바탕으로 작성했습니다. 본문의 예시가 모두 자동으로 탐지된다는 의미는 아닙니다.