Claude 5 세대 모델을 위한 컨텍스트 엔지니어링의 새로운 규칙
TMThttps://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models
최신 Claude 5 세대 모델에 프롬프트를 잘 쓰는 방법과, 만들고 싶은 것을 모델과 함께 반복하며 찾아가는 방법은 이전 글에서 다룬 바 있습니다.
하지만 Claude에게 메시지를 보낼 때, 프롬프트는 모델이 받는 컨텍스트의 일부에 불과합니다. 컨텍스트의 상당 부분은 시스템 프롬프트, 스킬(Skills), CLAUDE.md 파일, 메모리 등 여러 출처에서 조립됩니다. 우리는 이것을 컨텍스트 엔지니어링이라고 부르는데, Claude Code를 쓸 때든 직접 에이전트를 만들 때든 결과물에 큰 영향을 줍니다.
프롬프트와 달리 컨텍스트는 수많은 요청에 두루 쓰이기 때문에 프롬프트만큼 구체적일 수 없습니다. 사용자가 어떤 프롬프트를 입력할지 알 수 없는 상황에서, 이런 범용 프롬프트와 지침을 어떻게 만들어야 할까요?
Claude 자체의 능력이 계속 발전하기 때문에 이 일은 의외로 어렵습니다. 최근 우리는 최신 세대 Claude 모델에 프롬프트를 쓰는 방식이 크게 달라졌다는 것을 확인했습니다. Claude Opus 5와 Claude Fable 5 같은 모델에서는 Claude Code 시스템 프롬프트의 80% 이상을 삭제했는데도 코딩 평가에서 측정 가능한 성능 저하가 전혀 없었습니다.
이 글에서는 이 새로운 급의 모델에 프롬프트를 쓰며 배운 것들과, 이를 여러분의 컨텍스트 엔지니어링에 반영하는 방법을 소개합니다. 이 모범 사례들은 claude doctor에 담아 두었으니, Claude Code에서 /doctor 명령을 실행하면 스킬과 CLAUDE.md 파일을 적정 크기로 다듬을 수 있습니다.
Claude의 족쇄 풀기
전반적으로 우리는 시스템 프롬프트뿐 아니라 CLAUDE.md 파일과 스킬을 통해서도 Claude Code를 과도하게 옭아매고 있었습니다.
예를 들어 사내에서 Claude Code를 쓴 대화 기록을 읽어 보면, 시스템 프롬프트와 스킬과 사용자 요청이 서로 부딪히면서 한 요청 안에 "적절히 문서를 남겨라", "절대 주석을 달지 마라" 같은 상충하는 메시지가 여럿 들어 있는 것이 보입니다.
대개 Claude는 사용자의 의도를 해석해 올바른 답에 도달할 수 있지만, 이렇게 겹치고 충돌하는 메시지가 있으면 무엇을 할지 결정하기 전에 더 신중하게 따져 봐야 합니다.
이 제약들은 한때 최악의 상황을 막기 위해 필요했지만, 이제는 상당수를 지우고 그 대신 모델이 주변 컨텍스트와 판단력을 활용하게 해도 된다는 것을 확인했습니다.
게다가 이제 Claude Code에는 도구가 훨씬 많아졌습니다. 예전에는 Claude가 메모리, 정보, 지침의 원천으로 CLAUDE.md에 의존했지만, 지금은 메모리, 아티팩트, 스킬이 있어서 세션을 넘나들며 컨텍스트를 불러오고 공유하는 새로운 방식을 만들 수 있습니다.
이전과 지금
과거의 컨텍스트 엔지니어링 모범 사례 중 상당수가 이제는 근거 없는 통념이 됐습니다. 예를 들면 다음과 같습니다.
지금: Claude가 스스로 판단하게 한다
이전: Claude에게 규칙을 준다
Claude Code를 처음 출시했을 때는 파일 삭제 같은 최악의 상황을 Claude가 반드시 피하게 만들어야 했습니다. 그래서 항상 옳지는 않더라도 유난히 강한 지침을 주곤 했습니다. 예를 들어 예전 시스템 프롬프트에는 이렇게 적혀 있었습니다.
코드에서는 기본적으로 주석을 쓰지 마라. 여러 단락짜리 docstring이나 여러 줄 주석 블록은 절대 쓰지 말고, 짧은 한 줄까지만 허용된다. 사용자가 요청하지 않는 한 계획, 결정, 분석 문서를 만들지 말고, 중간 산출 파일이 아니라 대화 컨텍스트를 바탕으로 작업하라.
하지만 일부 프롬프트에서는 이 지침이 오히려 틀린 답이 됩니다. 문서화라면 사용자마다 선호가 다를 수 있고, 아주 복잡한 코드의 특정 부분에는 여러 줄 주석 블록이 필요할 수도 있습니다.
그래도 예전 모델에서는 이런 가드레일이 없으면 Claude가 쓰는 주석이 틀리는 경우가 많아 이 트레이드오프를 감수할 수밖에 없었습니다. 하지만 최신 모델은 판단력이 좋아져서 명시적인 규칙 없이도 이런 결정을 잘 처리합니다.
새 시스템 프롬프트에는 이렇게 적었습니다. 주변 코드처럼 읽히는 코드를 써라. 주석 밀도, 네이밍, 관용 표현을 주변 코드에 맞춰라.
지금: 인터페이스를 설계한다
이전: Claude에게 예시를 준다
도구 사용의 제1원칙은 Claude에게 사용 예시를 보여 주는 것이었습니다. 그런데 최신 모델에서는 예시를 주면 오히려 모델의 탐색 범위가 특정 공간에 갇힌다는 사실을 발견했습니다.
예시를 주는 대신 도구, 스크립트, 파일의 설계를 더 고민하세요. Claude에게 어떤 파라미터가 주어지는지, 그것을 어떻게 더 표현력 있게 만들 수 있는지 생각해 보는 것입니다.
예를 들어 Todo 도구에서는 status를 pending, in_progress, completed의 열거형으로 정의해 두는 것만으로도 Claude에게 사용법에 대한 힌트가 됩니다. in_progress 항목을 하나만 유지하라는 지시는 우리가 원하는 동작을 정의하는 데 도움이 됩니다.
지금: 점진적 공개를 쓴다
이전: 전부 앞에 몰아넣는다
Claude Code는 코딩에 초점을 맞춘 제품이라, 시스템 프롬프트에 코드 리뷰와 검증 방법에 대한 상세한 정보가 들어 있었습니다. 늘 필요한 내용은 아니었지만, 필요한 순간에는 결정적인 정보였습니다.
그 뒤로 Claude Code는 점진적 공개(progressive disclosure), 즉 적절한 컨텍스트를 적절한 때에 불러오는 일에 매우 능숙해졌습니다. 예를 들어 검증과 코드 리뷰는 별도 스킬로 분리해서 Claude Code가 필요할 때만 골라 호출하게 했습니다.
점진적 공개는 스킬에만 쓰는 것이 아니라 도구에도 씁니다. 일부 도구는 '지연 로딩(deferred loading)' 방식이어서, 에이전트가 사용하기 전에 ToolSearch로 전체 정의를 찾아와야 합니다. 덕분에 (Task 도구처럼) 필요해지기 전까지는 컨텍스트를 차지하지 않는 도구를 더 많이 둘 수 있습니다.
여러분의 CLAUDE.md와 Skill.md 파일에도 같은 방식을 적용할 수 있습니다. 흔한 오해는, Claude가 스스로 찾지 못할 테니 언젠가 마주칠지도 모르는 모든 관행을 이 파일들에 다 모아 둬야 한다는 것입니다. 그 대신 적절한 때에 불러올 수 있는 파일 트리를 구성하는 방안을 고려해 보세요.
지금: 간결한 도구 설명
이전: 같은 말을 반복한다
예전 Claude 모델은 지시를 반복해 줘야 할 때가 있었고, 컨텍스트 윈도 앞쪽보다 끝쪽에 있는 지시를 더 잘 따르는 경향도 있었습니다. 그래서 도구 설명에 지시를 넣어 두고도 메인 시스템 프롬프트에서 그 도구를 다시 언급하곤 했습니다.
이제는 이런 중복 사례를 지우고, 도구 사용법 지시를 시스템 프롬프트가 아니라 도구 설명에만 넣어도 된다는 것을 확인했습니다.
지금: 자동 메모리
이전: CLAUDE.md 파일에 메모리를 담는다
예전에는 # 단축키로 CLAUDE.md에 자동 기록하는 방식으로 Claude의 메모리에 내용을 저장하라고 사용자에게 권했습니다. 이제는 Claude가 작업과 사용자에게 관련 있는 내용을 알아서 메모리에 저장합니다.
지금: 풍부한 레퍼런스
이전: 단순한 스펙
플랜 모드에서 Claude Code는 계획을 담은 마크다운 파일에 크게 의존해 왔습니다. 계획을 파일로 저장해 두면 Claude가 필요할 때 참조할 수 있었기 때문입니다. 긴 프로젝트를 진행하는 동안 참조할 스펙을 코드베이스에 저장해 두는 것도 비슷한 모범 사례였습니다.
하지만 Claude는 점점 더 복잡한 레퍼런스도 다룰 수 있게 됐습니다. 단순한 마크다운 파일 대신, 새 아티팩트 기능으로 만든 HTML 아티팩트를 참조할 수 있습니다.
코드 형태의 레퍼런스를 줄 수도 있습니다. 상세한 테스트 스위트가 스펙이 될 수도 있고, Claude가 포팅할 다른 코드베이스의 함수가 스펙이 될 수도 있습니다.
루브릭도 레퍼런스의 한 형태입니다. 루브릭을 쓰면 Claude가 동적 워크플로를 활용해 그 루브릭을 든 검증 에이전트들을 띄워서, 특정 분야에 대한 여러분의 취향(예: 좋은 API 설계란 어떤 모습인가)을 맞춰 보고 검증하게 할 수 있습니다.
여러분의 컨텍스트에 적용하기
지금까지의 내용을 모두 모아 컨텍스트를 조립하면 어떤 모습이 될까요?
시스템 프롬프트
시스템 프롬프트는 제품 컨텍스트와 밀접하게 묶여 있습니다. Claude가 어떤 제품 안에서 무엇을 하고 있는지 알려 주는 역할입니다. Claude Code를 쓴다면 이 부분을 직접 수정할 일은 거의 없겠지만, 자체 에이전트 하네스를 만들고 있다면 여기에 많은 시간을 들여야 합니다.
CLAUDE.md
CLAUDE.md는 가볍게 유지하면서 저장소의 용도를 간단히 설명하되, 토큰 대부분은 코드베이스 안의 함정(gotcha)에 쓰세요. 예를 들어 타입을 단 하나의 큰 파일에만 모아 두기로 코드를 조직했다면 그런 것이 여기에 해당합니다. 파일 시스템이나 저장소만 봐도 Claude가 알 수 있는 '뻔한' 내용은 적지 마세요.
점진적 공개를 적극적으로 활용하세요. 예를 들어 작업 검증 방법에 대한 고유한 지침이 여럿 있다면, 검증 스킬을 만들고 CLAUDE.md에서는 그 스킬을 참조만 하게 하세요.
스킬
스킬은 Claude가 필요할 때 정보를 찾게 해 주는 가벼운 안내서라고 생각하세요. 아주 중요한 영역이 아니라면 과도하게 제약을 걸지 마세요.
긴 스킬에는 점진적 공개를 최대한 활용하세요. 여러 파일로 나눠서 분리해 두는 것입니다.
스킬은 여러분 자신이나 팀이나 제품에 고유한 견해, 지식, 모범 사례를 담을 때 가장 효과적입니다.
레퍼런스
파일을 @로 멘션하면 레퍼런스로 포함할 수 있습니다. 레퍼런스가 있으면 Claude가 현재 계획에 대한 심층 정보를 참조할 수 있습니다.
스펙 파일일 수도 있고, 목업일 수도 있고, 심지어 코드베이스 전체일 수도 있습니다. 일반적으로는 코드로 된 파일을 선호하는 것이 좋습니다. Claude가 아주 잘 아는 언어로 명확하고 충실도 높은 지시를 전달할 수 있기 때문입니다. 예를 들어 디자인을 HTML 목업으로 주면, 디자인을 글로 설명하거나 스크린샷으로 주는 것보다 대체로 더 좋은 결과가 나옵니다.
단순화를 시도해 보세요
우리가 그랬듯이, 여러분의 시스템 프롬프트, 스킬, CLAUDE.md 파일 전반에도 단순화가 필요할 수 있습니다. 이를 자동으로 도와주는 새 명령어 claude doctor도 출시했습니다. 더 고급 모델에 프롬프트를 쓰는 방법이 궁금하다면 Fable 필드 가이드를 참고하세요.
이 글은 Anthropic 기술 스태프인 Thariq Shihipar가 작성했습니다.