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

이 문서는 The new rules of context engineering for Claude 5 generation models의 한글 번역입니다.

목차

핵심 요약

원문 작성일: 2026년 7월 24일 (금)

작성자: Thariq Shihipar (Anthropic, Member of Technical Staff)

이미지: 본문 도식 4개는 원문의 그림을 한국어로 다시 그린 것입니다. 원본 이미지는 원문 글에서 볼 수 있습니다.

저는 Claude 5세대 최신 모델에 프롬프트하는 가장 좋은 방법과, 무엇을 만들고 싶은지 찾아가며 반복적으로 협업하는 방법을 이전에 다룬 적이 있습니다.

하지만 Claude에게 메시지를 보낼 때 프롬프트는 Claude가 받는 컨텍스트의 아주 일부에 지나지 않습니다. 컨텍스트의 상당 부분은 시스템 프롬프트, 스킬, CLAUDE.md 파일, 메모리 등 다양한 출처에서 조합됩니다. 저희는 이를 컨텍스트 엔지니어링이라고 부릅니다. 컨텍스트 엔지니어링은 Claude Code를 사용하거나 여러분만의 에이전트를 구축할 때 얻는 결과물에 큰 영향을 미칩니다.

프롬프트와 달리 컨텍스트는 여러 요청에 걸쳐 범용적으로 쓰이기 때문에 프롬프트만큼 구체적일 수 없습니다. 특히 사용자가 어떤 프롬프트를 입력할지 알 수 없는 상황에서, Claude를 위한 이런 범용적인 프롬프트와 가이드는 어떻게 만들어야 할까요?

Claude 자체 역량이 발전하면서 이 작업은 의외로 어려워질 수 있습니다. 최근 저희는 최신 세대 Claude 모델에 프롬프트하는 방식이 크게 도약했음을 알게 됐습니다. Claude Opus 5, Claude Fable 5 같은 모델을 위해 Claude Code의 시스템 프롬프트를 80% 넘게 걷어냈는데도, 코딩 평가 결과에서 측정 가능한 성능 저하는 없었습니다.

이 글에서는 이 새로운 부류의 모델에 프롬프트하며 배운 점과, 이를 바탕으로 여러분의 컨텍스트 엔지니어링을 개선할 수 있는 방법을 소개합니다. 이런 모범 사례는 claude doctor에 담았습니다. Claude Code에서 /doctor 명령어를 실행하면 스킬과 CLAUDE.md 파일을 적정 크기로 다듬을 수 있습니다.

Claude의 발목 풀어주기 (Unhobbling)

전반적으로 저희 시스템 프롬프트뿐 아니라 CLAUDE.md 파일과 스킬을 통해서도 Claude Code를 과도하게 제약해왔다는 점을 깨달았습니다.

예를 들어 저희가 Claude Code를 내부에서 쓴 기록을 보면, 시스템 프롬프트와 스킬, 사용자 요청이 서로 부딪히곤 합니다. 그 결과 “적절히 문서화를 남겨라”와 “절대 주석을 추가하지 마라”처럼 상충하는 메시지가 한 요청 안에 여러 개 섞여 있는 게 보입니다.

대체로 Claude는 사용자의 의도를 해석해 올바른 답에 도달할 수 있습니다. 하지만 이렇게 겹치고 충돌하는 메시지 앞에서는 무엇을 할지 결정하기 전에 더 신중하게 생각해야 합니다.

이런 제약은 한때 최악의 상황을 피하려고 필요했지만, 저희는 이제 그중 상당수를 걷어내고 모델이 주변 컨텍스트와 스스로의 판단력을 쓰도록 맡길 수 있다는 결론에 이르렀습니다.

게다가 이제 Claude Code는 훨씬 더 많은 도구를 갖췄습니다. 예전에는 Claude가 메모리, 정보, 가이드를 얻는 원천으로 CLAUDE.md에 의존했습니다. 지금은 저희가 메모리, 아티팩트, 스킬까지 갖추고 있어서, Claude는 이를 써서 세션을 넘나들며 컨텍스트를 불러오고 공유하는 새로운 방식을 만들어낼 수 있습니다.

그때와 지금

그동안 컨텍스트 엔지니어링의 모범 사례로 통했지만 이제는 낡은 오해로 밀려난 것들이 여럿 있습니다. 예를 들면 다음과 같습니다.

그때: Claude에게 규칙을 줬습니다

지금: Claude의 판단에 맡깁니다

처음 Claude Code를 출시했을 때, 저희는 Claude가 파일을 삭제하는 등 최악의 상황만은 피하도록 확실히 해둬야 했습니다. 그래서 항상 옳지는 않더라도 특히 강한 가이드를 주곤 했습니다. 예를 들어 예전 시스템 프롬프트에는 이런 내용이 담겨 있었습니다.

코드에서는 기본적으로 주석을 쓰지 않는다. 여러 문단짜리 docstring이나 여러 줄짜리 주석 블록은 절대 작성하지 않는다 — 짧은 한 줄이 최대다. 사용자가 요청하지 않는 한 계획, 결정, 분석 문서를 만들지 않는다 — 중간 파일이 아니라 대화 맥락을 바탕으로 작업한다.

하지만 어떤 유형의 프롬프트에서는 이 지침이 맞지 않습니다. 문서화는 사용자마다 원하는 방식이 다를 수 있고, 아주 복잡한 코드의 특정 부분은 여러 줄짜리 주석 블록이 필요할 수도 있습니다.

그럼에도 예전 모델에서는 이런 가드레일이 없으면 Claude가 쓰는 주석이 틀리는 일이 많았기 때문에, 저희는 이 트레이드오프를 받아들여야 했습니다. 반면 최신 모델은 판단력이 뛰어나 명시적인 규칙 없이도 이런 결정을 잘 처리할 수 있습니다.

새 시스템 프롬프트에서는 이렇게 말합니다.

주변 코드처럼 읽히는 코드를 작성한다: 주석 밀도, 네이밍, 표현 방식을 맞춘다.

그때: Claude에게 예시를 보여줬습니다

지금: 인터페이스를 설계합니다

도구 사용에서 가장 우선했던 원칙은 Claude에게 사용법 예시를 보여주는 것이었습니다. 그런데 최신 모델에서는 예시를 주는 행위 자체가 오히려 Claude의 탐색 범위를 특정 영역으로 가둔다는 사실을 저희가 발견했습니다.

예시를 쓰는 대신, 도구와 스크립트, 파일 자체의 설계를 더 고민해보세요. Claude가 쓸 수 있는 파라미터는 무엇이며, 그 파라미터가 어떻게 하면 더 풍부한 표현력을 가질 수 있을까요?

예를 들어 Todo 도구에서는 상태 값을 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가 참고하도록 코드베이스에 스펙을 저장해두는 방식이었습니다.

하지만 저희는 Claude가 점점 더 복잡한 레퍼런스도 다룰 수 있음을 알게 됐습니다. 단순한 마크다운 파일 대신, Claude는 새로운 아티팩트 기능으로 만든 HTML 아티팩트를 레퍼런스로 참조할 수 있습니다.

코드 형태로 Claude에게 레퍼런스를 건네는 방법도 있습니다. 스펙이 상세한 테스트 모음이거나, Claude가 이식할 만한 다른 코드베이스의 함수일 수도 있습니다.

루브릭(rubric)도 레퍼런스의 한 형태입니다. 루브릭을 쓰면 Claude가 다이내믹 워크플로우로 그 루브릭을 적용한 검증 에이전트를 띄워서, 특정 분야에서 여러분의 안목(예: 좋은 API 설계란 무엇인가)이 어떤지 직접 검증해보게 할 수 있습니다.

여러분의 컨텍스트에 적용하기

지금까지 다룬 내용을 종합하면, 실제로 컨텍스트를 조립할 때는 어떤 모습이 될까요?

시스템 프롬프트

시스템 프롬프트는 제품 맥락과 깊이 얽혀 있습니다. Claude에게 지금 어떤 제품 안에서 무엇을 하고 있는지 알려주는 역할이죠. Claude Code를 쓴다면 이 부분을 직접 수정할 일은 거의 없겠지만, 여러분만의 에이전트 하네스(agent harness)를 구축한다면 많은 시간을 들여야 할 곳이 바로 여기입니다.

CLAUDE.md

CLAUDE.md는 가볍게 유지하세요. 저장소가 무엇을 위한 것인지는 짧게만 설명하고, 대부분의 토큰은 코드베이스 안의 함정 요소(gotcha)를 설명하는 데 쓰세요. 예를 들어 타입을 하나의 거대한 파일에만 모아두고 다른 곳에는 두지 않는 식으로 코드를 구성했을 수 있습니다. Claude가 파일 시스템이나 저장소만 봐도 알 수 있는 ‘뻔한’ 내용은 굳이 적지 마세요.

점진적 공개를 적극적으로 쓰세요. 예를 들어 작업을 검증하는 고유한 지시사항이 여러 개 있다면, 검증 스킬을 따로 만들고 CLAUDE.md에서 참조하도록 하세요.

스킬

스킬은 Claude가 필요할 때 정보를 찾아볼 수 있게 해주는 가벼운 가이드라고 생각하세요. 아주 중요한 영역이 아니라면 과도하게 제약하지 마세요.

스킬이 길어지면 점진적 공개를 최대한 살리세요. 여러 파일로 나눠 쪼개두면 됩니다.

스킬은 여러분이나 팀, 제품에 고유한 방침, 지식, 모범 사례를 담아낼 때 가장 빛을 발합니다.

레퍼런스

파일을 @로 멘션해서 레퍼런스로 포함할 수 있습니다. 레퍼런스는 Claude가 현재 플랜의 심도 있는 정보를 참조하도록 해줍니다.

스펙 파일이나 목업, 심지어 코드베이스 전체가 레퍼런스가 될 수도 있습니다. 일반적으로는 코드 형태의 파일을 우선하는 게 좋습니다. 코드 파일은 Claude가 아주 잘 아는 언어로 명확하고 정밀한 지시를 전달해주기 때문입니다. 예를 들어 디자인을 설명한 글이나 스크린샷보다, HTML로 만든 디자인 목업 쪽이 대체로 더 좋은 결과를 냅니다.

단순화를 시도해보세요

시스템 프롬프트, 스킬, CLAUDE.md 파일 전반에 걸쳐, 여러분도 저희처럼 단순화가 필요할지 모릅니다. 이 작업을 자동으로 도와주는 claude doctor라는 새 명령어도 선보였습니다. 더 발전된 모델에 프롬프트하는 방법을 구체적으로 더 알고 싶다면 Fable 필드 가이드를 확인해보세요.

참고 자료

• The new rules of context engineering for Claude 5 generation models (원문)
• A field guide to Claude Fable: finding your unknowns
• Effective context engineering for AI agents
• A harness for every task: dynamic workflows in Claude Code