Claude 5 세대 모델을 위한 새로운 컨텍스트 엔지니어링 규칙

TL;DR Highlight

Claude Code 시스템 프롬프트 80% 이상 삭제해도 코딩 평가 성능 손실 없었다

Who Should Read

CLAUDE.md와 Skill이 비대해져 Claude Code가 규칙끼리 충돌하는 느낌을 받는 개발자

Core Mechanics

시스템 프롬프트 80% 넘게 삭제
- Claude Opus 5와 Claude Fable 5용 Claude Code 시스템 프롬프트에서 80% 이상을 뺐다.
- 코딩 평가에서 측정 가능한 성능 손실은 없었다고 한다.
규칙끼리 충돌하고 있었다
- 내부 사용 기록을 보니 "문서는 적절히 남겨라"와 "주석 달지 마라"가 한 요청 안에 같이 들어 있었다.
- Claude는 겹치고 충돌하는 지시를 두고 더 오래 고민해야 한다.
규칙 대신 판단에 맡기기
- 예전엔 "주석 기본 금지, 한 줄만" 같은 강한 규칙을 썼다.
- 지금은 "주변 코드처럼 써라: 주석 밀도, 네이밍, 관용구를 맞춰라" 한 줄로 바꿨다.
예시 대신 인터페이스 설계
- 최신 모델은 예시를 주면 탐색 범위가 그 예시로 좁아진다.
- 대신 도구 파라미터를 표현력 있게 설계하라고 한다(예: Todo 도구의 status를 pending, in_progress, completed enum으로).
한꺼번에 넣지 말고 점진적 공개
- 검증과 코드 리뷰는 시스템 프롬프트에서 빼 별도 skill로 옮겼다.
- 일부 도구는 deferred loading(ToolSearch로 정의를 검색해야 로드)이라 필요할 때까지 컨텍스트를 안 먹는다.

Community Reactions

프롬프트 장황함에 대한 공감 의견
- 긴 지시문 대신 그냥 에이전트에게 말하는 편이 낫다는 의견이 있었다.
- 도구가 좋고 요청이 어느 정도 명확하면 시스템 프롬프트는 거의 쓸모없었다는 경험도 있었다.
auto-memory 끄니 나아졌다는 경험
- auto-memory를 끄고 CLAUDE.md, skill, 문서를 직접 관리했더니 결과가 더 예측 가능했다는 경험이 있었다.
- 메모리를 너무 많이 쓰고 잘 줄이지 못한다는 지적이 있었다.
- 벤더 락인을 노린 것 아니냐는 의견도 있었다.
근거 부족하다는 반론
- 새 방식이 실제 사례에서 더 낫다는 증거가 없고 Anthropic 코드베이스에서만 좋을 수도 있다는 의견이 있었다.
- Opus 5에서 실수와 토큰 사용이 늘었고 Fable 5는 틀렸을 때 교정이 어렵다는 경험도 있었다.
실용 팁과 활용 경험
- Fable 5에 "use your own judgement"라고 했더니 테스트 관련해서 잘 됐다는 경험이 있었다.
- 예시 대신 반례(counter-example)를 쓴다는 사례가 있었다.
- 이 글을 Claude에 넘겨 CLAUDE.md를 고치게 했더니 잘 됐다는 경험이 있었다.
시스템 프롬프트 비용 문제

How to Apply

CLAUDE.md의 뻔한 줄과 충돌 규칙 지우기
- 오늘 CLAUDE.md를 열어 파일 구조만 봐도 알 수 있는 내용을 삭제하라.
- "주석 금지"처럼 서로 부딪히는 규칙은 "주변 코드 스타일에 맞춰라"로 바꿔라.
- 남은 토큰은 코드베이스의 함정(예: 타입은 한 파일에만 둔다)에 써라.
검증·리뷰 지침을 skill로 분리하기
- CLAUDE.md에 길게 쓴 검증 절차를 verification skill 파일로 옮겨라.
- CLAUDE.md에는 그 skill을 가리키는 한 줄만 남겨라.
도구 예시를 파라미터 설계로 바꾸기
- 자체 에이전트에서 도구 설명에 붙인 사용 예시를 빼라.
- 대신 enum 같은 값으로 사용법이 드러나게 파라미터를 설계하라.
- 사용법은 시스템 프롬프트가 아니라 도구 설명에 한 번만 써라.
스펙을 코드 형태로 전달하기
- 긴 작업에는 설명 대신 테스트 스위트나 HTML 목업을 @로 넘겨라.
- 결과를 비교해 효과를 직접 확인하라.

Try It

복사해서 바로 해보기

# Claude Code에 그대로 붙여넣기 (원문 원칙을 프롬프트로 옮긴 것, claude doctor의 간이 버전)

아래는 내 CLAUDE.md다.
{{CLAUDE.md 내용}}

다음 기준으로 점검해 줘.
1. 파일 구조나 레포를 보면 알 수 있는 뻔한 내용은 삭제 대상으로 표시해.
2. 서로 충돌하는 규칙을 찾아 하나로 정리해. 가능하면 규칙 대신 "주변 코드처럼 써라" 같은 판단 기준으로 바꿔.
3. 코드베이스의 함정(gotcha)만 남겨.
4. 길고 상황별인 지침(검증, 리뷰 등)은 별도 skill 파일로 분리하고 CLAUDE.md에는 참조 한 줄만 남겨.

수정안과 삭제한 항목 목록을 각각 보여줘.

이어서 해 볼 것: Claude Code에서 /doctor 명령도 실행해 결과를 비교해 봐.

Terminology

컨텍스트 엔지니어링프롬프트 한 줄이 아니라 시스템 프롬프트, Skills, CLAUDE.md, 메모리 등 모델이 받는 입력 전체를 설계하는 일이다.

progressive disclosure필요한 정보를 필요한 때에 불러오는 방식이다. 책 전체를 외우게 하지 않고 목차만 주고 해당 장을 펴 보게 하는 것과 같다.

deferred loading도구 정의를 처음부터 올리지 않고 ToolSearch로 찾아야 로드되는 방식이다. 쓰기 전까지 컨텍스트를 차지하지 않는다.

rubric좋은 결과의 기준표다. Claude가 이 기준으로 검증 에이전트를 띄워 취향에 맞는지 확인하게 할 수 있다.

SkillClaude가 필요할 때 찾아 읽는 가벼운 지침 파일이다. 팀만의 의견이나 노하우를 담는 데 좋다.