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

고성능 모델을 대상으로 Claude Code의 시스템 프롬프트를 80% 넘게 줄였습니다. 이 과정에서 배운 점을 Claude Code와 자체 에이전트의 컨텍스트 엔지니어링에 적용하는 방법을 소개합니다.

이전 글에서는 최신 Claude 5 세대 모델에 효과적으로 프롬프트를 작성하는 방법과, 반복적으로 협업하면서 무엇을 만들지 구체화하는 방법을 다뤘습니다.

하지만 Claude에 메시지를 보낼 때 프롬프트는 Claude가 받는 컨텍스트의 일부에 불과합니다. 컨텍스트 대부분은 시스템 프롬프트, Skills, CLAUDE.md 파일, 메모리 등 여러 출처에서 조합됩니다. 이를 컨텍스트 엔지니어링이라고 부르며, Claude Code를 사용하거나 자체 에이전트를 만들 때 결과에 큰 영향을 미칩니다.

프롬프트와 달리 컨텍스트는 여러 요청에 공통으로 사용되므로 특정 요청에만 맞춰 구체적으로 작성할 수 없습니다. 사용자가 어떤 프롬프트를 입력할지 모르는 상태에서 Claude를 위한 범용 프롬프트와 지침을 어떻게 만들어야 할까요?

Claude의 역량이 발전하면서 이 작업은 예상보다 어려워질 수 있습니다. 최근에는 최신 Claude 모델 세대에 프롬프트를 작성하는 방식에 큰 변화가 필요하다는 사실을 발견했습니다. Claude Opus 5와 Claude Fable 5 같은 모델에 제공하던 Claude Code 시스템 프롬프트를 80% 이상 제거했지만, 코딩 평가에서 측정할 수 있는 성능 저하는 없었습니다.

이 새로운 모델군에 프롬프트를 작성하며 배운 점과 이를 컨텍스트 엔지니어링에 적용하는 방법을 소개합니다. 이런 권장 사항은 claude doctor;에도 반영했습니다. Claude Code에서 /doctor 명령을 사용하면 Skills와 CLAUDE.md 파일의 분량을 적절하게 조정할 수 있습니다.

Claude의 제약 풀기

전반적으로 살펴보니 시스템 프롬프트뿐 아니라 CLAUDE.md 파일과 Skills를 통해서도 Claude Code를 지나치게 제한하고 있었습니다.

예를 들어 사내에서 Claude Code를 사용한 대화 기록을 읽어 보면 하나의 요청 안에서 “필요에 따라 문서를 남겨라”와 “주석을 추가하지 마라”처럼 서로 충돌하는 메시지가 여러 개 나타납니다. 시스템 프롬프트와 Skills, 사용자 요청이 서로 부딪히기 때문입니다.

Claude는 대체로 사용자의 의도를 파악해 올바른 답에 도달할 수 있습니다. 하지만 지침이 겹치거나 충돌하면 무엇을 해야 할지 결정하기 전에 더 신중하게 판단해야 합니다.

이런 제약은 한때 최악의 결과를 막는 데 필요했습니다. 그러나 이제는 그중 상당수를 삭제하고 모델이 주변 컨텍스트와 자체 판단을 활용하게 해도 된다는 사실을 확인했습니다.

또한 Claude Code가 사용할 수 있는 도구도 크게 늘었습니다. 이전에는 Claude가 기억과 정보, 지침을 얻기 위해 CLAUDE.md에 의존했습니다. 이제는 메모리, 아티팩트, Skills를 활용해 세션 사이에서 컨텍스트를 불러오고 공유하는 새로운 방법을 만들 수 있습니다.

과거와 현재

이전에는 컨텍스트 엔지니어링의 모범 사례로 여겨졌지만 이제는 통념에 가까워진 원칙이 여럿 있습니다.

과거: Claude에 규칙을 제시한다

현재: Claude가 판단하게 한다

Claude Code를 처음 출시했을 때는 파일 삭제 같은 최악의 결과를 반드시 막아야 했습니다. 그래서 언제나 옳지는 않더라도 매우 강한 지침을 제공했습니다. 예를 들어 과거 시스템 프롬프트에는 다음과 같은 내용이 있었습니다.

코드를 작성할 때는 기본적으로 주석을 쓰지 마세요. 여러 문단으로 된 docstring이나 여러 줄의 주석 블록은 절대 작성하지 말고, 한 줄로 짧게 끝내세요. 사용자가 요청하지 않았다면 계획·결정·분석 문서를 만들지 말고, 중간 파일이 아니라 대화 컨텍스트를 바탕으로 작업하세요.

하지만 일부 프롬프트에서는 이 지침이 잘못된 결과를 낳습니다. 문서 작성 방식에 관한 사용자 고유의 선호가 있을 수 있고, 매우 복잡한 코드의 특정 부분에는 여러 줄의 주석 블록이 필요할 수도 있습니다.

그럼에도 구형 모델에는 이런 가드레일이 필요했습니다. 가드레일이 없으면 Claude가 작성한 주석이 많은 경우 부정확했기 때문에 이 절충을 받아들여야 했습니다. 반면 최신 모델은 판단력이 향상되어 명시적인 규칙 없이도 이런 결정을 잘 처리할 수 있습니다.

새 시스템 프롬프트에서는 이렇게 지시합니다. 주변 코드와 자연스럽게 어울리는 코드를 작성하세요. 주석의 밀도, 이름을 짓는 방식, 관용적인 표현을 기존 코드에 맞추세요.

과거: Claude에 예시를 제공한다

현재: 인터페이스를 설계한다

도구 사용에서 가장 중요한 원칙은 Claude에 사용 예시를 제공하는 것이었습니다. 하지만 최신 모델에서는 예시가 오히려 Claude의 탐색 범위를 특정 영역으로 제한한다는 사실을 확인했습니다.

예시를 제공하는 대신 도구와 스크립트, 파일의 설계를 더 깊이 고민해 보세요. Claude가 사용할 수 있는 매개변수는 무엇이며, 이를 어떻게 더 풍부하게 표현할 수 있을까요?

예를 들어 Todo 도구에서 상태를 pending, in_progress, completed 열거형으로 제시하기만 해도 Claude는 사용법을 짐작할 수 있습니다. 한 항목만 in_progress 상태로 유지하라는 지침은 원하는 동작을 더 명확히 규정합니다.

과거: 모든 내용을 처음부터 제공한다

현재: 점진적으로 공개한다

Claude Code는 코딩에 초점을 맞춘 제품이었기 때문에 시스템 프롬프트에 코드 리뷰와 검증 방법을 자세히 담았습니다. 늘 필요한 정보는 아니었지만, 필요할 때는 매우 중요했습니다.

이후 Claude Code는 적절한 시점에 필요한 컨텍스트를 불러오는 점진적 공개를 능숙하게 활용하게 됐습니다. 예를 들어 검증과 코드 리뷰 지침을 각각 별도의 Skill로 옮겨 Claude Code가 필요할 때 선택적으로 호출하도록 했습니다.

점진적 공개는 Skills에만 적용되지 않습니다. 도구에도 같은 방식을 사용합니다. 일부 도구는 ‘지연 로딩’ 방식으로 제공되며, 에이전트가 사용하기 전에 ToolSearch로 전체 정의를 검색해야 합니다. 덕분에 Task 도구처럼 당장 필요하지 않은 도구가 컨텍스트를 차지하지 않으면서도 더 많은 도구를 제공할 수 있습니다.

CLAUDE.md와 Skill.md 파일에도 같은 원칙을 적용할 수 있습니다. Claude가 아니면 정보를 찾지 못할 것이라는 생각 때문에, 언젠가 마주칠 수도 있는 모든 사례의 모범 사례를 이 파일들에 한데 모아야 한다는 통념이 있습니다. 그 대신 필요한 시점에 불러올 수 있는 파일 트리를 구성해 보세요.

과거: 같은 지침을 반복한다

현재: 도구 설명을 간결하게 작성한다

초기 Claude 모델에는 같은 지침을 여러 번 전달해야 할 때가 있었고, 컨텍스트 창 앞부분보다 끝부분의 지침을 따를 가능성이 더 높기도 했습니다. 이 때문에 기본 시스템 프롬프트에서 도구를 언급하고 도구 설명에도 같은 지침을 다시 넣곤 했습니다.

이제는 반복되는 예시를 삭제하고 도구 사용법을 시스템 프롬프트가 아닌 도구 설명에 넣어도 된다는 사실을 확인했습니다.

과거: CLAUDE.md 파일에 메모리를 저장한다

현재: 자동 메모리를 사용한다

이전에는 # 단축키를 사용해 CLAUDE.md에 내용을 자동으로 기록하면서 Claude의 메모리에 정보를 저장하도록 권장했습니다. 이제 Claude는 작업과 사용자에게 관련된 내용을 자동으로 메모리에 저장합니다.

과거: 간단한 명세를 제공한다

현재: 풍부한 참고 자료를 제공한다

Claude Code는 계획 모드에서 계획을 담은 Markdown 파일에 크게 의존해 왔습니다. 계획을 파일로 저장하면 필요할 때 다시 참조할 수 있었습니다. 장기 프로젝트를 진행하는 동안 Claude가 참고할 수 있도록 코드베이스에 명세를 저장하는 방법도 비슷한 모범 사례였습니다.

하지만 Claude는 갈수록 복잡한 참고 자료도 처리할 수 있습니다. 간단한 Markdown 파일뿐 아니라 새로운 아티팩트 기능으로 만든 HTML 아티팩트도 참고할 수 있습니다.

코드를 참고 자료로 제공할 수도 있습니다. 자세한 테스트 스위트가 명세 역할을 하거나, 다른 코드베이스에서 이식할 함수가 참고 자료가 될 수도 있습니다.

루브릭도 참고 자료의 한 형태입니다. Claude는 해당 루브릭을 사용하는 검증 에이전트를 실행하고 동적 워크플로를 활용해 특정 분야에서 사용자가 선호하는 기준을 시도하고 검증할 수 있습니다. 예를 들어 좋은 API 설계가 무엇인지 판단하는 기준을 루브릭으로 전달할 수 있습니다.

컨텍스트에 적용하기

지금까지의 내용을 종합하면 실제 컨텍스트는 어떻게 구성해야 할까요?

시스템 프롬프트

시스템 프롬프트는 제품 컨텍스트와 밀접하게 연결됩니다. Claude가 어떤 제품에서 작동하며 무슨 일을 하는지 알려 줍니다. Claude Code를 사용한다면 이를 수정할 일은 거의 없겠지만, 자체 에이전트 하네스를 구축한다면 많은 시간을 들여야 할 부분입니다.

CLAUDE.md

CLAUDE.md는 가볍게 유지하고 저장소의 용도를 간단히 설명하되, 대부분의 토큰은 코드베이스에서 주의해야 할 점에 사용하세요. 예를 들어 타입을 하나의 큰 파일에만 모으고 다른 곳에는 두지 않도록 코드를 구성했을 수 있습니다. Claude가 파일 시스템이나 저장소를 살펴보면 알 수 있는 ‘당연한 내용’은 적지 마세요.

점진적 공개를 적극적으로 활용하세요. 작업 검증 방법에 고유한 지침이 여러 개 있다면 검증 Skill을 만들고 CLAUDE.md에서 이를 참조할 수 있습니다.

Skills

Skills는 Claude가 필요할 때 정보를 찾도록 돕는 가벼운 안내서로 생각하세요. 매우 중요한 영역이 아니라면 지나치게 많은 제약을 넣지 마세요.

Skill이 길다면 점진적 공개를 최대한 활용하세요. 여러 파일로 나누고 내용을 분리하는 편이 좋습니다.

Skills에는 자신이나 팀, 제품에만 적용되는 구체적인 관점과 지식, 모범 사례를 담을 때 가장 효과적입니다.

참고 자료

파일을 @ 멘션해 참고 자료로 포함할 수 있습니다. Claude는 이를 통해 현재 계획과 관련된 상세 정보를 확인할 수 있습니다.

명세 파일이나 목업은 물론 코드베이스 전체를 참고 자료로 제공할 수도 있습니다. 일반적으로는 코드로 작성된 파일을 우선하는 편이 좋습니다. Claude가 잘 아는 언어로 명확하고 충실한 지침을 전달하기 때문입니다. 예를 들어 디자인을 설명하거나 스크린샷으로 보여 주는 것보다 HTML 목업을 제공할 때 대체로 더 좋은 결과를 얻습니다.

단순하게 줄여 보세요

시스템 프롬프트, Skills, CLAUDE.md 파일 전반을 우리처럼 단순화해야 할 수도 있습니다. 이 작업을 자동으로 돕는 claude doctor,라는 새 명령도 출시했습니다. 고성능 모델에 프롬프트를 작성하는 방법을 더 자세히 알아보려면 Fable 필드 가이드를 참고하세요.

^{source https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models}

HN에서는 복잡한 지침을 덜어내고 모델의 판단에 맡기자는 방향에는 대체로 수긍하면서도, 최신 모델이 실제로 그만한 재량을 감당하는지는 별개라고 봤다. 사람이 단계마다 결과를 확인하는 작업이라면 긴 설정 파일보다 분명한 의도와 필요한 도구만 주는 편이 낫다는 경험이 이어졌다. 사소한 오류는 직접 고치는 편이 이를 막기 위한 규칙을 계속 덧붙이는 것보다 빠르다는 판단도 같은 맥락이다.

하지만 장시간 자율 실행이나 중요한 작업에서는 지침 축소가 곧 품질 향상을 뜻하지 않았다. 새 모델이 파일을 잘못 삭제하거나 제한 장치를 우회하고, 잘못된 결정을 그럴듯한 설명으로 포장했다는 사례가 나왔다. 기존 코딩 평가에서 성능 저하가 없었다는 주장만으로는 부족하다는 지적도 컸다. 무엇을 삭제했으며 어떤 행동을 학습만으로 안정적으로 수행하는지 알아야 실무자가 설정을 다시 설계할 수 있기 때문이다.

자동 메모리 역시 불신을 키웠다. 무관한 과거 대화가 현재 작업의 전제로 끼어들면 판단 근거를 추적하기 어렵고, 폐기하려던 실험까지 이후 문맥을 오염시킬 수 있다. 이 때문에 메모리를 모델에 맡기기보다 사람이 작성한 파일과 규칙으로 저장 범위와 호출 시점을 통제하겠다는 반응이 나왔다. 문맥 관리가 공급자 전용 도구에 묶이면 이식성과 통제권이 약해진다는 우려도 겹쳤다.

결국 작업 방식과 실패 비용이 중요하다. 사람이 자주 검토할 수 있다면 의도 중심의 짧은 문맥과 점진적인 수정이 효율적이다. 반대로 되돌리기 어렵거나 실제 행동으로 이어지는 작업은 재량을 넓히기 전에 샌드박스와 검증 절차, 복구 수단을 갖춰야 한다. 기존 설정도 한꺼번에 지우기보다 실제 작업 결과를 확인하며 충돌하는 규칙과 과도한 예시부터 걷어내는 편이 현실적이다.