클로드 코드 원라인 명령어 `/claude-api prompt-audit`로 프롬프트 레거시 정리하기

Lance Martin이 공유하고 X의 @RoundtableSpace를 통해 알려진 원라인 명령어 /claude-api prompt-audit는 Claude Code 사용자를 위해 프로젝트 내 축적된 구형 프롬프트 관행을 진단하고 정리해 줍니다. Anthropic 공식 스킬 저장소(anthropics/skills)에 수록된 프롬프트 감사 스펙을 기반으로 동작하는 이 명령어는 개발자의 작업 디렉터리에 존재하는 CLAUDE.md, AGENTS.md, 커스텀 스킬 정의 및 시스템 프롬프트 전반을 스캔하여, 최신 Claude 모델(Opus 5.5 등)의 성능과 유연성을 저해하는 과거의 우회 기법을 식별합니다.

이미지 출처: @RoundtableSpace via X

개발자가 Claude Code 세션을 장기간 운영하다 보면, 초기 모델 시절의 도구 미호출 버그나 기획 능력 부족을 해결하기 위해 작성했던 강제 지침들이 규칙 파일에 그대로 남아있기 쉽습니다. /claude-api prompt-audit는 이러한 지침들을 비대화형(non-interactive) 파이프라인으로 일괄 스캔하여 구체적인 폐기 사유와 권장 수정안을 제시합니다.

구형 프롬프트 패턴이 최신 Claude 모델의 발목을 잡는 이유

많은 개발자들은 규칙 파일이나 스킬을 최적화할 때 '텍스트를 짧게 줄이는 것'에 집중합니다. 그러나 Anthropic의 프롬프트 감사 프레임워크가 제시하는 핵심 기준은 단순한 토큰 절약이 아니라 **"모든 토큰은 존재 이유를 스스로 증명해야 한다(Every token earns its place)"**는 원칙입니다.

과거 구형 모델들은 지시사항을 무시하거나 도구 호출(Tool Calling)을 누락하고 계획 수립 능력이 미흡한 경우가 잦았습니다. 이를 보정하기 위해 개발자들은 과도한 대문자 강조, 강제적인 단계별 계획 수립 지침, 출력 형식 강제용 스캐폴딩을 프롬프트 곳곳에 추가했습니다.

하지만 Claude Opus 5.5와 최신 Claude 모델들은 주어진 시스템 지침을 과거보다 훨씬 문자 그대로(literally), 그리고 엄격하게 따릅니다. 따라서 과거 모델을 위해 추가되었던 임시방편 지침들은 단순한 토큰 낭비를 넘어 다음과 같은 실질적인 성능 저하를 일으킵니다:

• 도구 과잉 호출(Over-triggering): 과거에 도구를 잘 쓰지 않던 모델을 위해 추가한 강한 호출 조건 때문에, 도구가 필요 없는 단순 질의에서도 불필요한 도구를 연쇄 실행함
• 과도한 계획 수립(Over-planning): 모델의 네이티브 추론 기능이 발전했음에도 인위적인 단계별 계획 스크립트에 묶여 간단한 편집 작업조차 과도하게 쪼개어 처리함
• 그레이존 경직성(Rigid responses in gray areas): 예외 상황이나 모호한 문맥에서 유연하게 판단해야 할 모델이 과거의 엄격한 포맷 규칙에 갇혀 비효율적인 답변을 반복함

즉, 단순히 무의미한 텍스트보다 과거 모델의 결함을 메우기 위해 작성된 '구체적인 구형 지침'이 최신 모델의 능동적 판단을 직접적으로 방해합니다.

감사 범위와 비대화형(Non-Interactive) 실행 구조

Claude Code 터미널에서 다음 명령어를 실행하면 즉시 감사가 시작됩니다:

/claude-api prompt-audit

이 명령어는 anthropics/skills 공식 저장소에 정의된 skills/claude-api/shared/prompt-audit.md 스펙을 기반으로 동작합니다.

감사 엔진은 세션 중간에 사용자에게 질문을 던지지 않고, 오직 요청 문맥과 리포지토리 파일 시스템에서 직접 정보를 추출하는 비대화형(non-interactive) 방식으로 설계되었습니다. 따라서 단일 채팅 세션뿐만 아니라 CI/CD 파이프라인이나 대규모 배치 마이그레이션 작업에서도 동일하게 일관된 결과를 출력합니다.

감사 프로세스는 시작 단계(Step 0)에서 대상 타깃 모델(예: Claude Opus 5.5)과 진단 범위를 자동으로 확정하며, 프로젝트 내의 다음 프롬프트 접점 전반을 빠짐없이 탐색합니다:

• CLAUDE.md 및 AGENTS.md (프로젝트 규칙 및 컨텍스트 파일)
• SKILL.md 및 커스텀 스킬 정의 폴더
• 시스템 프롬프트(System prompts) 정의 파일
• 도구 설명(Tool descriptions) 및 스키마 명세
• 코드베이스 내에서 API 요청 프롬프트를 조립하는 빌더 로직

집중 탐지 대상: 구형 모델용 레거시 패턴 3가지

/claude-api prompt-audit가 중점적으로 추적하여 깃발을 올리는(flag) 대표적인 구형 패턴은 다음과 같습니다.

1. 인위적인 단계별 추론 강제 ("think step by step")

초기 LLM에서 추론 품질을 높이기 위해 삽입했던 "Think step by step"이나 수동 사고 흐름 강제 문구입니다. 네이티브 추론(Thinking) 기능과 자율 에이전트 플래닝이 내장된 최신 Claude 모델에서는 이러한 수동 문구가 오히려 사고 폭을 제한하고 응답 지연을 가중시킵니다.

2. 어시스턴트 턴 JSON 프리필 (Assistant Prefills)

과거 구조화된 출력을 보장하기 위해 어시스턴트 메시지의 시작 부분을 강제로 채워 넣던 테크닉입니다:

{"role": "assistant", "content": "{"}

현재 Claude API는 정식 Tool Calling 및 구조화된 출력(Structured Outputs) 인터페이스를 네이티브로 완벽히 지원하므로, 이러한 프리필 잔재는 즉시 공식 API 기능으로 전환하거나 제거해야 합니다.

3. 과도한 인용 우선 추출 스캐폴딩 및 호출 유도문

문서 분석 시 환각을 줄이기 위해 인용문을 먼저 추출하도록 강제했던 복잡한 포맷 템플릿(Quotes-first extraction scaffolds)이나, 구형 모델이 도구를 지나치지 않도록 반복 명시했던 중복 트리거 지침들입니다. 최신 모델에서는 지시 준수율이 높아 이러한 장치가 불필요한 추론 비용만 발생시킵니다.

Step 0~6 감사 파이프라인과 최종 산출물

감사 워크플로우는 내부적으로 Step 0부터 Step 6까지 순차적으로 실행됩니다. 감사 명령은 중간 단계를 장황하게 요약하지 않고, 최종 단계에서 다음 두 가지 핵심 결과물을 출력합니다:

1. Step 0: 요청 및 리포지토리 상태 기반으로 진단 범위 및 대상 모델(Opus 5.5 등) 확정
2. Step 1~4: 작업 디렉터리 내 프롬프트 접점 전수 조사 및 구형 패턴 대조 분석
3. Step 5 (Deliverable 1): 구조화된 진단 리포트 (Audit Report)
4. Step 6 (Deliverable 2): 즉시 반영 가능한 제안 패치 (Proposed Diff)

진단 리포트(Findings Report)의 필드 구성

감사 리포트는 발견된 각 패턴에 대해 추측이 아닌 명확한 근거 데이터를 제공합니다:

필드	설명
Location	구형 지침이 발견된 파일명과 구체적인 라인 위치
Evidence	실제 코드 또는 마크다운 내의 원문 스니펫
Pattern	탐지된 레거시 프롬프팅 기법의 유형
Why Obsolete	최신 Claude 모델(Opus 5.5 등)에서 해당 지침이 성능을 저해하는 이유
Confidence	탐지 정확도 및 확신 수준 (High, Medium 등)
Proposed Action	권장 조치 방안 (remove, rewrite, move, replace-with-API-feature)

보고서에 이어 제공되는 제안 패치(Proposed Diff)는 불필요한 규칙을 안전하게 삭제하거나 최신 API 호환 방식으로 수정한 Git diff 형태를 제공하므로, 개발자는 변경 사항을 검토한 후 즉시 코드베이스에 적용할 수 있습니다.

다국어 규칙 파일과 실전 활용 팁

소셜 커뮤니티에서는 비영어권 언어로 작성된 규칙 파일에 대한 질문도 제기되었습니다. 예를 들어 CLAUDE.md 전체가 베트남어나 한국어로 작성되어 있고, 과거에 발생했던 장애 사례나 단순 비즈니스 규칙이 평문 문장으로 적혀 있는 경우입니다.

감사 엔진의 설계 목적은 프로젝트 고유의 도메인 지식이나 순수 업무 규칙을 삭제하는 것이 아닙니다. 과거 오류 방지를 위해 기록해 둔 평문 문맥은 모델에게 여전히 유효한 도메인 지식으로 작동합니다. 감사의 칼날은 오직 **"과거 모델의 한계를 우회하기 위해 인위적으로 주입했던 프롬프트 엔지니어링 잔재"**만을 정밀하게 타깃팅합니다.

Claude Code로 대규모 코딩이나 에이전트 작업을 시작하기 전, /claude-api prompt-audit를 한 번 실행해 보세요. 오랜 기간 쌓여 있던 규칙 파일의 불필요한 족쇄를 풀고 최신 Claude Opus 5.5 본연의 추론 능력을 온전히 끌어낼 수 있습니다.

원문 출처

• RoundtableSpace 포스트 (Lance Martin 팁 공유)
• Anthropic Skills 공식 저장소 (claude-api/shared/prompt-audit.md)