Claude Code의 컨텍스트 엔지니어링: 최신 모델을 위한 베스트 프랙티스
저는 이전에 최신 Claude 5 모델을 효과적으로 프롬프트하는 방법과 이를 반복적으로 활용해 원하는 결과물을 만들어내는 방법에 대해 글을 쓴 적이 있습니다.
하지만 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 가 판단을 사용하도록 하기
**처음 Claude Code 를 출시했을 때는, 파일 삭제와 같은 최악의 시나리오를 피해야 했습니다. 이는 항상 참이 아닐 수 있는 매우 강력한 가이드를 제공해야 한다는 것을 의미했습니다. 예를 들어, 시스템 프롬프트에서 우리는 이렇게 말했습니다:
코드에서: 기본적으로 주석을 작성하지 않습니다. 여러 문단의 독스트링이나 여러 줄의 주석 블록을 작성하지 마세요 — 최대 한 줄로 제한합니다. 사용자가 요청하지 않는 한 계획, 결정, 분석 문서를 만들지 마세요 — 중간 파일이 아닌 대화 컨텍스트를 기반으로 작업합니다.
하지만 특정 프롬프트의 경우 이 가이드는 잘못된 것이었습니다. 문서화의 경우, 사용자는 자신만의 선호도를 가지고 있을 수 있으며, 매우 복잡한 코드의 특정 부분은 여러 줄의 주석 블록이 필요할 수 있습니다.
그럼에도 불구하고, 이전 모델에 이러한 보호 장치가 없으면 Claude 가 작성한 주석이 많은 경우에 부정확했고, 우리는 이러한 트레이드오프를 받아들여야 했습니다. 하지만 최신 모델은 더 나은 판단력을 가지고 있으며, 명시적인 규칙 없이도 이러한 결정을 잘 처리할 수 있습니다.
새로운 시스템 프롬프트에서는 이렇게 말합니다: 주변 코드와 같은 스타일의 코드를 작성하세요: 주석 밀도, 네이밍, 관용구를 일치시킵니다.
**그때: Claude 에게 예제 제공하기
지금: 인터페이스 설계하기
**도구 사용의 첫 번째 규칙은 Claude 에게 사용 방법에 대한 예제를 제공하는 것이었습니다. 최신 모델에서는 예제를 제공하는 것이 오히려 특정 탐색 공간으로 제약한다는 것을 발견했습니다.
예제를 사용하는 대신, 도구, 스크립트, 파일의 설계에 대해 더 고민해보세요 — Claude 가 어떤 매개변수를 가지고 있으며, 어떻게 더 표현력을 높일 수 있을까요?
예를 들어, Todo 도구 예제에서 상태를 pending, in_progress, completed 사이의 열거형으로 나열하는 것만으로도 Claude 에게 사용 방법을 암시합니다. 한 항목을 in_progress 로 유지하라는 지침은 요청된 동작을 정의하는 데 도움이 됩니다.
**그때: 모든 것을 앞에 배치하기
지금: 점진적 공개 사용하기**
Claude Code 가 코딩에 초점을 맞추고 있었기 때문에, 시스템 프롬프트에는 코드 리뷰 및 검증 방법에 대한 자세한 정보가 포함되어 있었습니다. 이것들은 항상 필요하지는 않았지만, 필요할 때는 중요한 정보였습니다.
그 이후로 Claude Code 는 점진적 공개(올바른 시점에 올바른 컨텍스트를 로드하는 것)를 매우 능숙하게 사용할 수 있게 되었습니다. 예를 들어, 검증과 코드 리뷰를 Claude Code 가 선택적으로 호출할 수 있는 별도의 Skills 로 이동했습니다.
하지만 점진적 공개는 Skills 에만 해당되는 것이 아닙니다. 우리는 도구에도 이를 사용합니다. 일부 도구는 '지연 로딩' 방식으로, 에이전트가 사용하기 전에 ToolSearch 를 사용하여 전체 정의를 검색해야 합니다. 이를 통해 필요할 때까지 컨텍스트를 차지하지 않는 더 많은 도구(예: Task 도구)를 가질 수 있습니다.
이는 여러분의 CLAUDE.md 및 Skill.md 파일에도 동일하게 적용될 수 있습니다. 일반적인 오해는 Claude 가 그렇지 않으면 찾을 수 없기 때문에, 발생할 수 있는 모든 알려진 관행을 위한 중앙 저장소를 만들어야 한다는 것입니다. 대신, 올바른 시점에 로드할 수 있는 파일 트리를 구성하는 것을 고려해보세요.
**그때: 반복하기
지금: 간단한 도구 설명**
이전 Claude 모델은 때때로 반복적인 지시가 필요하거나, 컨텍스트 창의 시작 부분보다 끝 부분에 있는 지시를 더 잘 따르는 경향이 있었습니다. 이는 시스템 프롬프트가 메인 시스템 프롬프트의 도구 참조와 도구 설명의 지시를 모두 포함해야 함을 의미했습니다.
우리는 이러한 반복 예제를 삭제하고, 도구 사용 방법에 대한 지침을 시스템 프롬프트가 아닌 도구 설명에 넣을 수 있다는 것을 발견했습니다.
**그때: CLAUDE.md 파일의 메모리
지금: 자동 메모리**
우리는 이전에 사용자들이 # 단축키를 사용하여 CLAUDE.md에 자동으로 작성함으로써 Claude 의 메모리에 정보를 저장하도록 권장했습니다. 이제는 Claude 가 작업과 사용자에게 관련된 메모리를 자동으로 저장합니다.
**그때: 간단한 스펙
지금: 풍부한 참조**
Plan 모드에서 Claude Code 는 계획이 포함된 마크다운 파일에 크게 의존해 왔습니다. 이러한 파일을 계획으로 저장하면 Claude 가 필요할 때 참조할 수 있었습니다. 또 다른 유사한 베스트 프랙티스는 긴 프로젝트에서 작업하는 동안 Claude 가 참조할 수 있도록 코드베이스에 스펙을 저장하는 것이었습니다.
하지만 우리는 Claude 가 점점 더 복잡한 참조를 처리할 수 있다는 것을 발견했습니다. 간단한 마크다운 파일 대신, Claude 는 새로운 아티팩트 기능으로 생성된 HTML 아티팩트를 참조할 수 있습니다.
또한 코드 형태의 참조를 Claude 에게 제공할 수도 있습니다. 스펙은 상세한 테스트 스위트이거나, Claude 가 포팅할 수 있는 다른 코드베이스의 함수일 수도 있습니다.
루브릭도 또 다른 형태의 참조입니다. 루브릭을 사용하면 Claude 가 동적 워크플로우를 사용하고 해당 루브릭을 가진 검증 에이전트를 실행하여 특정 분야에서의 사용자 취향(예: 좋은 API 디자인이란 무엇인가)을 시도하고 검증할 수 있습니다.
컨텍스트에 적용하기
이 모든 것을 종합하면, 컨텍스트를 조립할 때 실제로 어떻게 보일까요?
**시스템 프롬프트
**시스템 프롬프트는 제품 컨텍스트와 밀접하게 연결됩니다. 이는 Claude 에게 어떤 제품에서 작동 중이며 무엇을 하고 있는지 알려줍니다. Claude Code 의 경우, 이를 수정할 일은 거의 없겠지만, 자체 에이전트 하네스를 구축하는 경우라면 이 부분에 많은 시간을 투자해야 합니다.
**CLAUDE.md
**CLAUDE.md 는 가볍게 유지하고 리포지토리의 용도를 간략히 설명하되, 대부분의 토큰은 코드베이스 내의 함정(gotchas)에 사용하세요. 예를 들어, 코드를 구성할 때 타입을 하나의 모놀리식 파일에만 유지하고 다른 곳에는 두지 않는 방식으로 구성할 수 있습니다. Claude 가 파일 시스템이나 리포지토리를 보면 알 수 있는 '자명한' 내용은 언급하지 마세요.
더 자세한 내용은 점진적 공개를 사용하세요. 예를 들어, 작업 검증 방법에 대한 여러 고유한 지침이 있다면, 검증 Skill 을 만들고 CLAUDE.md 에서 이를 참조하세요.
**Skills
**Skills 는 Claude 가 필요할 때 정보를 찾을 수 있도록 하는 가벼운 가이드로 생각하세요. 매우 중요한 영역을 제외하고는 지나치게 제약하지 않도록 주의하세요.
긴 Skills 의 경우, 가능한 한 점진적 공개를 사용하세요 — 여러 파일로 나누고 분할하세요.
Skills 는 사용자, 팀, 또는 제품에 특화된 특정 의견, 지식, 또는 베스트 프랙티스를 인코딩할 때 가장 효과적입니다.
**참조
**파일을 @멘션하여 참조로 포함시킬 수 있습니다. 참조를 통해 Claude 는 현재 계획에 대한 심층 정보를 참조할 수 있습니다.
이는 스펙 파일, 목업, 또는 전체 코드베이스일 수도 있습니다. 일반적으로 Claude 가 잘 알고 있는 언어로 명확하고 충실도 높은 지침을 제공할 수 있으므로, 코드 형태의 파일을 선호해야 합니다. 예를 들어, 디자인의 HTML 목업은 일반적으로 디자인 설명이나 스크린샷보다 더 나은 결과를 생성합니다.
단순화 시도하기
시스템 프롬프트, Skills, CLAUDE.md 파일 전반에 걸쳐, 우리가 했던 것처럼 단순화가 필요할 수 있습니다. 우리는 claude doctor라는 새로운 명령어를 출시했으며, 이를 통해 자동으로 단순화를 수행할 수 있습니다. 보다 진보된 모델을 프롬프트하는 방법에 대한 자세한 내용은 Fable 필드 가이드를 확인하세요.
