컨텍스트 엔지니어링이 무엇인가
먼저 용어부터 풀어야 합니다. 프롬프트는 지금 내가 친 한 줄입니다. 컨텍스트는 그 한 줄이 모델에 도착할 때 함께 실려 가는 전부입니다. 시스템 프롬프트, CLAUDE.md 파일, 스킬, 메모리, 그 밖의 출처에서 모인 묶음이고, 내 프롬프트는 그 묶음의 맨 마지막 줄입니다.
원문의 표현이 정확합니다. 「메시지를 보낼 때 프롬프트는 모델이 받는 컨텍스트의 작은 일부일 뿐이다.」 그 묶음을 설계하는 일이 컨텍스트 엔지니어링이고, 결과의 질을 크게 좌우합니다.
비유하면 프롬프트는 오늘 신입에게 준 업무 지시이고, 컨텍스트는 그 신입이 들고 있는 매뉴얼 전체입니다. 지시가 아무리 명확해도 매뉴얼이 엉망이면 결과물이 엉망입니다.
그런데 이 매뉴얼에는 유효기간이 있습니다. 작년의 모델과 지금의 모델이 다르기 때문입니다. 신입용 매뉴얼을 10년 차에게 쥐여 주면 도움이 되지 않고 오히려 방해가 됩니다. 이번 발표의 요지가 정확히 그것입니다.
무엇이 얼마나 바뀌었나
Anthropic은 Claude Opus 5와 Claude Fable 5 같은 최신 세대를 대상으로 Claude Code의 시스템 프롬프트에서 80% 이상을 제거했고, 코딩 평가에서 측정 가능한 성능 저하가 없었다고 밝혔습니다. 원문 첫 문단의 표현 그대로입니다.
회사가 스스로 붙인 이름은 「Unhobbling Claude」입니다. 굳이 옮기면 족쇄를 푼다는 뜻이고, 시스템 프롬프트와 CLAUDE.md와 스킬 세 곳에서 모델을 과하게 제약하고 있었다는 자기 진단입니다.
바뀐 규칙은 여섯 쌍입니다. 원문이 「예전에는 이랬고 지금은 이렇다」 형식으로 나란히 적어 두었습니다.
| 예전 | 지금 |
|---|---|
| 규칙을 준다 | 판단에 맡긴다 |
| 예시를 준다 | 인터페이스를 설계한다 |
| 앞에 다 넣는다 | 점진적 공개를 쓴다 |
| 같은 말을 반복한다 | 도구 설명 한 곳에만 쓴다 |
| CLAUDE.md에 메모리를 쌓는다 | 자동 메모리에 맡긴다 |
| 간단한 명세를 준다 | 풍부한 참조를 준다 |
규칙 하나 — 규칙을 주지 말고 판단에 맡긴다
예전 시스템 프롬프트에는 이런 문장이 있었습니다. 「코드에서는 기본적으로 주석을 쓰지 마라. 여러 문단짜리 독스트링이나 여러 줄 주석 블록을 절대 쓰지 마라. 한 줄이 최대다.」
문제는 이런 규칙이 항상 옳지는 않다는 것입니다. 정말 복잡한 코드에는 긴 주석이 필요할 때가 있는데, 절대 쓰지 말라고 못 박아 두면 필요할 때도 못 씁니다. 예전 모델은 판단력이 부족해서 이 부작용을 감수하고라도 규칙으로 묶어야 했습니다.
지금 남은 문장은 한 줄입니다. 「주변 코드처럼 읽히는 코드를 써라. 주석 밀도와 이름과 관용구를 주변에 맞춰라.」 열 줄짜리 금지 조항이 한 줄짜리 기준으로 바뀌었습니다.
각자의 CLAUDE.md를 열어 보시기 바랍니다. 「절대 하지 마라」로 끝나는 문장이 여러 줄 있을 것입니다. 몇 달 전에는 그게 권장 사항이었습니다. 그 상당 부분은 이제 지우는 편이 성능에 낫습니다.
규칙 둘 — 예시 대신 인터페이스를 설계한다
도구를 만들 때 예전의 정석은 사용법 예시를 많이 붙이는 것이었습니다. 이런 상황에는 이렇게 쓰고 저런 상황에는 저렇게 쓰라는 식입니다.
그런데 최신 모델에서는 예시가 오히려 탐색 공간을 가둡니다. 원문 표현으로는 「예시를 주는 것이 실제로는 특정한 탐색 공간으로 모델을 제약한다」입니다. 기준으로 주려던 것이 울타리가 되는 셈입니다.
그래서 새 방식은 설명을 줄이고 도구 자체가 말하게 만드는 것입니다. 원문이 든 예가 할 일 관리 도구입니다. 상태값을 pending, in_progress, completed 세 가지 열거형으로 정의해 두면, 그것만으로 이 도구를 어떻게 쓰는지가 드러납니다. 여기에 「진행 중은 하나만 유지하라」 한 줄을 더하면 원하는 동작까지 정의됩니다.
잘 만든 문손잡이는 설명서 없이도 당길지 밀지 알 수 있습니다. 설명서를 쓰는 데 쓰던 시간을 손잡이를 잘 만드는 데 쓰라는 이야기입니다.
규칙 셋 — 앞에 다 넣지 말고 필요할 때 꺼내게 한다
점진적 공개라고 부릅니다. 필요한 맥락을 필요한 시점에 불러오는 방식입니다.
Claude Code 자신이 그렇게 바뀌었습니다. 코드 리뷰와 검증 방법처럼 늘 필요하지는 않지만 필요할 때는 결정적인 정보를 시스템 프롬프트에서 빼내 각각의 스킬로 옮겼습니다. 도구도 마찬가지여서, 일부 도구는 정의 전체를 처음부터 싣지 않고 ToolSearch로 찾아야 쓸 수 있게 미뤄 둡니다. 그 덕에 도구 수를 늘려도 평소 컨텍스트를 차지하지 않습니다.
CLAUDE.md도 같은 방향입니다. 창고가 아니라 안내 데스크로 두는 것입니다. 이 저장소가 무엇인지 짧게 적고, 검증은 이 파일, 배포는 저 파일이라고 가리키기만 합니다. 세부는 별도 파일이나 스킬로 쪼개 두고 그 작업을 할 때만 열게 합니다.
그렇다면 CLAUDE.md에 남길 것은 무엇인가. 원문은 토큰의 대부분을 gotcha에 쓰라고 말합니다. 함정이라는 뜻입니다. 예를 들어 이 저장소는 타입을 전부 한 파일에만 모아 둔다 같은 것입니다. 반대로 파일 구조만 봐도 알 수 있는 자명한 내용은 적지 말라고 못 박습니다. 그건 모델이 이미 볼 수 있습니다.
규칙 넷·다섯 — 반복을 지우고 메모리는 맡긴다
예전 모델은 대화가 길어지면 앞을 잊었습니다. 그래서 중요한 지시는 여러 번 적는 것이 정석이었고, Anthropic도 같은 도구 사용법을 시스템 프롬프트와 도구 설명 두 곳에 적어 두고 있었습니다.
최신 모델은 한 번 말하면 압니다. 그래서 중복을 걷어내고 도구 사용법은 도구 설명에만 남겼습니다. 각자의 CLAUDE.md에서도 같은 규칙이 두 번 세 번 나오는 자리가 있을 텐데, 지우면 토큰이 줄고 성능이 오릅니다.
메모리도 손이 덜 갑니다. 예전에는 기억시킬 내용을 사람이 직접 저장했습니다. 채팅 창에 # 로 시작하는 줄을 쓰면 CLAUDE.md에 바로 적히는 단축키가 그 용도였습니다. 지금은 작업과 사용자에게 관련된 것을 모델이 알아서 저장합니다.
다만 자동이라는 말이 하나하나 챙길 필요가 없다는 뜻이지, 명시가 무의미하다는 뜻은 아닙니다. 정말 남겨야 하는 것은 여전히 분명하게 기억하라고 말해 주는 편이 확실합니다.
규칙 여섯 — 마크다운 대신 더 깊은 재료를 준다
지금까지 계획서와 명세와 설계 문서는 마크다운으로 쓰는 것이 표준이었습니다. 가볍고 간단하기 때문입니다.
그런데 최신 모델은 훨씬 복잡한 참조 자료를 다룹니다. 그렇다면 전달할 정보를 굳이 흐려서 줄 이유가 없습니다. 원문은 코드로 된 파일을 우선하라고 말합니다. 모델이 아주 잘 아는 언어라 지시가 선명하기 때문입니다.
구체적으로는 이렇습니다. 화면 요구는 「버튼은 파란색, 모서리는 둥글게」라고 마크다운에 쓰는 대신 HTML 목업을 건넵니다. 명세는 상세한 테스트 묶음으로 줄 수 있습니다. 이 테스트를 통과시키라는 것보다 분명한 요구는 없습니다. 다른 코드베이스의 함수를 그대로 포팅하라는 것도 명세가 됩니다.
루브릭도 참조의 한 형태입니다. 좋은 API 설계란 무엇인가 같은 기준표를 주면, 모델이 검증 에이전트를 띄워 그 기준으로 자기 결과를 채점합니다. 취향을 말로 설명하는 대신 채점표로 넘기는 방법입니다.
그래서 내 파일은 어떻게 정리하나
원문이 마지막에 네 자리로 나눠 정리합니다. 각 자리의 역할이 다릅니다.
시스템 프롬프트는 제품 맥락에 묶입니다. 모델이 지금 어떤 제품 안에서 무엇을 하고 있는지를 말해 주는 자리입니다. Claude Code를 쓰는 입장에서는 건드릴 일이 거의 없고, 자기 에이전트를 만든다면 여기에 시간을 많이 쓰라고 권합니다.
CLAUDE.md는 가볍게 둡니다. 저장소가 무엇을 하는 곳인지 짧게 적고, 토큰의 대부분은 함정에 씁니다. 검증 방법이 여러 갈래로 복잡하면 검증 스킬을 따로 만들고 CLAUDE.md에서는 그 스킬을 가리키기만 합니다.
스킬은 필요할 때 정보를 찾아가는 가벼운 안내서로 봅니다. 아주 중요한 영역이 아니라면 과하게 제약하지 않습니다. 스킬이 길어지면 여러 파일로 쪼개 점진적 공개를 적용합니다. 스킬이 가장 값어치를 하는 때는 나와 우리 팀과 우리 제품에만 있는 의견과 노하우를 담을 때입니다.
참조는 파일을 @로 불러 붙입니다. 명세 파일, 목업, 심지어 코드베이스 전체까지 올 수 있습니다. 가능하면 코드로 된 파일을 우선합니다.
손으로 다 고치지 않아도 된다
여기까지 읽고 나면 내 파일을 어디부터 손대야 하나 싶어집니다. 그런데 Anthropic이 이 모범 사례를 도구에 넣어 두었습니다.
Claude Code를 최신 버전으로 올린 다음 /doctor 를 치면 됩니다. 스킬과 CLAUDE.md 파일을 이 기준에 맞게 적정 규모로 줄여 줍니다. 원문의 표현은 rightsize, 즉 알맞은 크기로 맞춘다는 말입니다.
정리하면 여섯 줄입니다. 규칙을 줄이고 판단에 맡긴다. 예시 대신 인터페이스를 설계한다. 앞에 다 넣지 말고 필요할 때 꺼내게 한다. 같은 말을 반복하지 않는다. 메모리는 자동에 맡긴다. 마크다운 대신 코드와 HTML과 테스트로 준다.
관통하는 메시지는 하나입니다. 모델은 경력자가 됐는데 우리는 아직 신입 매뉴얼을 쥐여 주고 있었다는 것입니다. 오늘 당장 할 수 있는 일은 CLAUDE.md를 열어 「절대 하지 마라」와 중복된 문단을 지우는 것이고, 그다음이 /doctor 입니다.