앤트로픽이 Claude Code의 시스템 프롬프트를 80% 넘게 줄였는데도 코딩 평가 점수에서 측정 가능한 하락이 없었다는 내용이 공개됐습니다. 이 사례가 흥미로운 이유는 단순히 프롬프트를 짧게 만들었다는 데 있지 않습니다. 오랫동안 코딩 에이전트 설정에 추가해 온 세부 규칙 중 상당수가 실제 품질을 높이기보다 모델의 판단을 묶는 장치였을 가능성을 보여주기 때문입니다.

다만 이 결과는 Opus 5와 Fable 5를 기준으로 한 것으로, 다른 모델이나 구형 사내 세팅에 그대로 적용해도 같은 결과가 나온다고 단정할 수는 없습니다. 중요한 것은 ‘규칙을 모두 지워라’가 아니라 어떤 지침을 어디에, 어떤 형태로 남길지 다시 설계하라는 메시지에 가깝습니다.

긴 시스템 프롬프트가 항상 더 안전하지 않은 이유

기존 코딩 에이전트 설정에는 비슷한 규칙이 계속 누적되기 쉽습니다. 예를 들어 주석을 작성하지 말 것, 여러 문단짜리 docstring을 만들지 말 것, 사용자가 요청하지 않으면 문서를 추가하지 말 것 같은 조항입니다. 각각은 특정 문제를 해결하기 위해 만들어졌을 수 있지만, 전체 맥락에서는 서로 충돌할 수 있습니다.

시스템 프롬프트는 적절한 문서화를 요구하고, Skills는 주석을 금지하며, 사용자는 이번 변경에 대한 설명을 별도로 요청하는 식입니다. 모델은 코드를 수정하기 전에 어느 지침이 우선인지부터 조정해야 합니다. 이 과정은 사람에게는 간단한 판단처럼 보여도 에이전트 입장에서는 컨텍스트와 추론 자원을 사용하는 추가 작업입니다.

규칙이 많으면 누락 가능성도 커집니다. 모델이 모든 문장을 동일한 강도로 처리하지 못할 뿐 아니라, 특정 문구에 과도하게 끌려가 정상적인 저장소 관행과 어긋나는 코드를 만들 수도 있습니다. ‘주석을 쓰지 말라’는 지침이 코드의 복잡한 이유를 설명해야 하는 상황까지 막아버리는 것이 대표적인 예입니다.

Claude Code 설정은 무엇을 남겨야 하는가

이번 재배치 방향에서 CLAUDE.md는 저장소의 사용 설명서라기보다 ‘코드만 봐서는 알기 어려운 함정’을 기록하는 파일에 가까워집니다. 저장소가 어떤 서비스인지 한두 줄로 설명하는 것은 유용하지만, 디렉터리 이름과 파일 트리만 확인해도 알 수 있는 내용까지 길게 적을 필요는 적습니다.

반대로 다음과 같은 규칙은 남길 가치가 있습니다.

• 모든 타입 정의가 특정 단일 파일에 모여 있음
• 데이터베이스 마이그레이션을 직접 실행하면 안 됨
• 특정 API 호출은 반드시 래퍼를 거쳐야 함
• 테스트 환경과 운영 환경의 설정 방식이 다름
• 특정 모듈의 변경이 별도의 생성 작업을 요구함

이런 정보는 일반적인 코딩 상식이 아니고, 저장소 내부의 구조적 제약입니다. 파일을 몇 개 읽는다고 바로 알아내기 어렵기 때문에 에이전트가 실수하기 전에 알려주는 편이 효과적입니다.

반면 ‘항상 깔끔한 코드를 작성하라’, ‘변경 후 테스트하라’처럼 너무 일반적인 문장은 우선순위가 낮습니다. 구체적인 실행 명령, 적용 범위, 실패하기 쉬운 조건으로 바꾸지 못한다면 긴 설명을 유지할 이유가 크지 않습니다.

긴 지침은 Skills로 분리하고 필요할 때 열게 한다

모든 작업에 항상 필요한 규칙과 특정 상황에서만 필요한 지침을 한 파일에 섞는 것이 문제의 출발점입니다. 코드 구현, 코드 리뷰, 테스트 검증, 배포 준비는 서로 참고해야 하는 정보가 다릅니다. 그런데 이 내용을 하나의 CLAUDE.md에 넣으면 간단한 수정 작업에도 리뷰와 배포 절차까지 함께 읽게 됩니다.

따라서 저장소의 기본 맥락은 작게 유지하고, 긴 절차는 Skills로 분리하는 방식이 적합합니다. Skills 자체도 지나치게 커지면 다시 여러 파일로 나눠 필요한 시점에만 참조하도록 구성할 수 있습니다. 원자료에서는 검증 지침과 코드 리뷰 지침이 이런 방식으로 분리된 사례가 언급됐습니다.

실무에서는 다음처럼 구분하면 관리하기 쉽습니다. CLAUDE.md에는 저장소 전체에 적용되는 핵심 제약과 함정만 두고, `/review` 같은 작업에는 리뷰 기준을, `/verify` 같은 작업에는 테스트·검증 절차를 연결하는 식입니다. 이렇게 하면 설정 파일의 길이를 줄이는 동시에 작업별로 필요한 정보의 밀도를 높일 수 있습니다.

확인 방법도 마련돼 있습니다. Claude Code의 `/doctor`와 `claude doctor` 명령은 Skills와 CLAUDE.md의 크기와 구성을 점검하는 데 사용할 수 있습니다. 설정을 계속 추가해 왔다면 먼저 실제로 얼마나 많은 토큰을 매 작업에 주입하고 있는지 확인하는 편이 좋습니다. 줄이는 작업은 감으로 하기보다, 어떤 파일이 항상 읽히고 어떤 지침이 특정 작업에서만 필요한지 구분하면서 진행해야 합니다.

예시를 줄이고 인터페이스를 더 명확하게 만들기

프롬프트에 예시를 많이 넣으면 모델이 쉽게 이해할 것 같지만, 예시는 탐색 범위를 오히려 좁힐 수 있습니다. 모델이 문제의 본질보다 제공된 예시와 비슷한 코드 형태를 찾는 데 집중할 수 있기 때문입니다. 하나의 예시가 표준처럼 작동하면 저장소의 다른 관용 표현을 충분히 살피지 않고 그 주변을 모방할 가능성도 생깁니다.

대안은 문장으로 사용법을 반복해서 설명하는 대신, 도구와 데이터 구조의 인터페이스를 명확하게 만드는 것입니다. Todo 도구의 상태를 임의의 문자열이 아니라 `pending`, `in_progress`, `completed`라는 열거형으로 정의하면 가능한 값과 의미가 자연스럽게 드러납니다. 한 번에 하나만 `in_progress`로 둘 수 있다는 제약까지 인터페이스나 검증 로직에 반영하면, 모델이 긴 지침을 기억하지 않아도 잘못된 상태를 만들기 어려워집니다.

이는 프롬프트를 잘 쓰는 문제를 소프트웨어 설계 문제로 옮기는 접근입니다. 자유로운 텍스트 지시보다 타입, 스키마, 명시적인 오류, 자동 검증이 에이전트의 행동 범위를 더 안정적으로 제한할 때가 많습니다. 규칙을 계속 추가하기 전에 도구가 잘못된 입력을 애초에 받아들이지 않도록 만들 수 있는지 먼저 보는 이유입니다.

문장보다 코드와 테스트가 강한 참조 자료가 된다

에이전트에게 전달하는 자료의 형식도 결과에 영향을 줍니다. 설명 문장만으로 구현 의도를 전달하는 것보다 실제 코드가 기존 관행을 보여주는 경우가 많습니다. UI 작업이라면 장황한 디자인 묘사보다 HTML 모형이 구조와 상태를 더 정확히 드러낼 수 있습니다. 기능 명세 역시 자연어 문서만 제공하는 것보다 테스트 스위트가 기대 동작과 예외 조건을 구체적으로 보여줄 수 있습니다.

검증 에이전트를 별도로 둔다면 평가 기준표를 함께 제공하는 방식이 유용합니다. 예를 들어 기능 구현 여부만 묻는 것이 아니라 기존 API 계약을 지켰는지, 실패 입력을 처리하는지, 관련 테스트가 통과하는지, 불필요한 파일을 만들지 않았는지를 기준별로 확인하게 할 수 있습니다. 이때 기준표는 구현 에이전트의 행동을 지나치게 지시하는 문서가 아니라 결과를 판정하는 검사 규칙이어야 합니다.

여기서 주의할 부분은 테스트가 항상 충분한 사양은 아니라는 점입니다. 테스트에 포함되지 않은 동작은 검증되지 않고, 기존 테스트가 잘못된 기대를 고정하고 있을 수도 있습니다. 따라서 코드, 테스트, 저장소의 예외 규칙을 서로 대조해야 하며, 테스트가 통과했다는 이유만으로 설계 의도까지 모두 충족했다고 보기는 어렵습니다.

규칙을 줄일 때 함께 확인할 조건

이번 사례를 보고 CLAUDE.md를 무작정 삭제하는 것은 위험합니다. 최신 모델은 긴 지침 없이도 일반적인 코딩 관행을 상당 부분 추론할 수 있지만, 사내 프레임워크나 오래된 코드베이스의 특수한 제약까지 자동으로 알아내지는 못합니다. 구형 모델은 짧은 규칙보다 명시적인 예시가 더 안정적으로 작동하는 경우도 있습니다.

설정을 정리할 때는 먼저 규칙을 세 부류로 나누는 것이 현실적입니다. 모든 작업에 필요한 전역 제약, 특정 작업에서만 필요한 절차, 코드와 도구의 구조로 옮길 수 있는 규칙입니다. 세 번째 부류는 프롬프트에서 삭제하는 대신 타입·린터·테스트·CLI 검증으로 이전합니다.

그다음 설정을 줄인 버전과 기존 버전을 같은 작업으로 비교해야 합니다. 코딩 평가 점수뿐 아니라 수정 범위, 테스트 누락, 불필요한 문서 생성, 기존 코드 스타일과의 불일치도 봐야 합니다. 특히 ‘주변 코드처럼 읽히는 코드’를 쓰라는 방향은 주석 개수 같은 고정 규칙보다 저장소의 실제 관행을 따르라는 뜻에 가깝습니다. 주석을 무조건 없애는 것이 아니라, 주변 코드가 주석을 사용하는 상황과 밀도를 읽고 맞추라는 의미입니다.

이번 변화에서 얻을 수 있는 실용적인 기준은 분명합니다. CLAUDE.md는 짧게 유지하되 저장소의 함정을 구체적으로 적고, 작업별 절차는 Skills로 나누며, 반복적인 설명은 인터페이스와 자동 검증으로 옮기는 것입니다. 다만 Opus 5와 Fable 5에서 확인된 결과를 모든 모델에 일반화해서는 안 됩니다. 설정을 덜어낸 뒤 실제 저장소에서 어떤 종류의 오류가 늘거나 줄었는지 측정하면서 적용 범위를 정하는 편이 안전합니다.