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

이전 글에서 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를 지나치게 제약하고 있었다는 사실을 발견했습니다.

예를 들어, 내부 사용 트랜스크립트를 살펴보면 단일 요청 안에서 "적절한 수준으로 문서를 남겨라", "절대 주석을 추가하지 마라"처럼 서로 충돌하는 지시들이 섞여 있는 경우가 있었습니다. 시스템 프롬프트, Skills, 사용자 요청이 각각 다른 방향을 가리키며 충돌한 결과입니다.

대체로 Claude는 사용자의 의도를 파악해 올바른 답을 도출해낼 수 있습니다. 하지만 이처럼 중복되거나 충돌하는 지시들이 있으면, Claude는 무엇을 할지 결정하기 전에 훨씬 더 많은 추론 과정을 거쳐야 합니다.

이러한 제약들은 한때 최악의 시나리오를 막기 위해 필요했지만, 이제는 상당수를 삭제하고 모델이 주변 컨텍스트와 스스로의 판단력을 활용하도록 맡겨도 된다는 것을 확인했습니다.

또한 Claude Code에는 이제 훨씬 더 많은 도구가 추가되었습니다. 예전에는 CLAUDE.md가 메모리, 정보, 가이드라인의 주된 저장소 역할을 했지만, 지금은 메모리, 아티팩트(artifacts), Skills가 추가되어 Claude가 세션 간 컨텍스트를 불러오고 공유하는 새로운 방식을 활용할 수 있게 되었습니다.

과거와 현재

한때 모범 사례로 통하던 컨텍스트 엔지니어링 방식 중 일부는 이제 통념에 불과해졌습니다. 대표적인 사례를 살펴보겠습니다.

과거: Claude에게 규칙을 부여한다

현재: Claude의 판단력에 맡긴다

Claude Code를 처음 출시했을 때는 파일 삭제 같은 최악의 상황을 방지하기 위해, 항상 들어맞지는 않더라도 특히 강력한 지침을 제공해야 했습니다. 예를 들어, 과거 시스템 프롬프트에는 이런 내용이 담겨 있었습니다.

코드 작성 시 기본적으로 주석을 달지 않는다. 여러 단락에 걸친 독스트링이나 여러 줄로 이루어진 주석 블록은 절대 작성하지 않는다 — 짧은 한 줄이 최대다. 사용자가 요청하지 않는 한 계획, 결정, 분석 문서를 생성하지 않는다 — 중간 파일이 아닌 대화 컨텍스트를 기반으로 작업한다.

하지만 특정 프롬프트에서는 이런 지침이 오히려 잘못된 결과를 낳기도 했습니다. 문서화의 경우, 사용자가 자신만의 선호 방식을 갖고 있거나, 특히 복잡한 코드의 일부에는 여러 줄에 걸친 주석 블록이 반드시 필요할 수 있습니다.

그럼에도 구형 모델에서는 이러한 가드레일 없이는 Claude가 작성하는 주석이 많은 경우 부적절했고, 이 트레이드오프를 감수할 수밖에 없었습니다. 하지만 신형 모델은 판단력이 크게 향상되어 명시적인 규칙 없이도 이런 결정을 잘 처리합니다.

새 시스템 프롬프트에는 이렇게 적혀 있습니다. 주변 코드의 스타일에 맞춰 작성한다: 주석 밀도, 네이밍, 관용적 표현을 일치시킨다.

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

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

도구 사용에 관한 가장 중요한 원칙은 Claude에게 사용 예시를 제공하는 것이었습니다. 그런데 최신 모델에서는 예시를 제공하면 오히려 탐색 범위가 특정 공간으로 제한된다는 사실을 발견했습니다.

예시를 제공하는 대신, 도구·스크립트·파일의 설계 자체에 더 집중해 보세요. Claude가 사용할 수 있는 파라미터는 무엇이며, 어떻게 하면 더 표현력 있게 만들 수 있을지 고민해 보는 것입니다.

예를 들어 Todo 도구에서 상태(status)를 pending, in_progress, completed의 열거형으로 정의하는 것만으로도 Claude에게 사용 방식을 자연스럽게 암시할 수 있습니다. in_progress 항목을 하나만 유지하라는 지침은 원하는 동작 방식을 명확히 정의하는 역할을 합니다.

과거: 모든 정보를 처음부터 제공한다

현재: 점진적 공개(progressive disclosure)를 활용한다

Claude Code가 코딩에 집중하던 시절, 시스템 프롬프트에는 코드 리뷰와 검증 방법에 관한 상세한 정보가 포함되어 있었습니다. 항상 필요한 정보는 아니었지만, 필요한 순간에는 꼭 있어야 하는 정보였습니다.

이후 Claude Code는 점진적 공개를 매우 능숙하게 활용하게 되었습니다. 적절한 시점에 필요한 컨텍스트를 불러오는 방식입니다. 예를 들어, 검증과 코드 리뷰를 별도의 Skills로 분리하여 Claude Code가 필요할 때만 선택적으로 호출하도록 변경했습니다.

점진적 공개는 Skills에만 적용되는 개념이 아닙니다. 도구에도 동일하게 활용됩니다. 일부 도구는 '지연 로딩(deferred loading)' 방식으로 설계되어, 에이전트가 실제로 사용하기 전에 ToolSearch를 통해 전체 정의를 먼저 조회해야 합니다. 이를 통해 필요하지 않을 때는 컨텍스트를 차지하지 않는 도구(예: Task 도구)를 더 많이 운용할 수 있습니다.

이 원칙은 직접 작성하는 CLAUDE.md나 Skill.md 파일에도 동일하게 적용됩니다. 흔한 오해 중 하나는, Claude가 필요한 정보를 스스로 찾지 못하기 때문에 언제 마주칠지 모르는 모든 사례를 하나의 파일에 집약해야 한다는 생각입니다. 하지만 오히려 적절한 시점에 로드될 수 있는 파일 트리 구조를 고려하는 것이 더 효과적입니다.

과거: 반복해서 강조한다

현재: 도구 설명을 간결하게 유지한다

초기 Claude 모델은 지시를 반복해야 더 잘 따르거나, 컨텍스트 윈도우 앞부분보다 끝부분의 지시를 더 잘 따르는 경향이 있었습니다. 그래서 시스템 프롬프트 본문에 도구 관련 내용을 언급하고, 도구 설명에도 동일한 지시를 중복 기재하는 방식을 쓰기도 했습니다.

이제는 이러한 중복 예시들을 삭제하고, 도구 사용 지침을 시스템 프롬프트가 아닌 도구 설명 안에 집약할 수 있다는 것을 확인했습니다.

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

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

과거에는 # 단축키를 눌러 CLAUDE.md에 자동으로 내용을 기록하는 방식으로 사용자가 직접 메모리를 저장하도록 권장했습니다. 이제 Claude는 진행 중인 작업과 사용자와 관련된 중요한 정보를 스스로 판단하여 자동으로 저장합니다.

과거: 단순한 명세서(spec)

현재: 풍부한 참조 자료

계획 모드에서 Claude Code는 마크다운 형식의 계획 파일에 크게 의존해 왔습니다. 이 파일들을 계획서로 저장해두면 Claude가 필요할 때 참조할 수 있었습니다. 비슷한 맥락에서, 장기 프로젝트 진행 시 Claude가 참고할 수 있도록 코드베이스에 명세서를 저장해두는 방식도 모범 사례로 통했습니다.

그러나 이제 Claude는 점점 더 복잡한 참조 자료도 능숙하게 다룰 수 있습니다. 단순한 마크다운 파일뿐만 아니라, 새로운 아티팩트 기능으로 생성된 HTML 아티팩트도 참조 자료로 활용할 수 있습니다.

코드 형태의 참조 자료를 제공하는 것도 가능합니다. 명세서가 상세한 테스트 스위트가 될 수도 있고, Claude가 포팅할 다른 코드베이스의 함수가 될 수도 있습니다.

루브릭(rubric)도 또 하나의 참조 형태입니다. 루브릭을 활용하면 Claude가 특정 분야에서 여러분의 기준(예: 좋은 API 설계란 무엇인가)을 파악하고 검증하는 데 도움이 됩니다. 동적 워크플로(dynamic workflows)를 활용해 해당 루브릭을 기반으로 검증 에이전트를 실행하는 방식으로 구현할 수 있습니다.

직접 적용하기

지금까지 살펴본 내용을 바탕으로, 실제 컨텍스트를 조합할 때는 어떻게 적용하면 될까요?

시스템 프롬프트

시스템 프롬프트는 제품 컨텍스트와 밀접하게 연결됩니다. Claude가 어떤 제품 안에서 어떤 역할을 수행하는지 알려주는 역할을 합니다. Claude Code를 사용하는 경우라면 시스템 프롬프트를 수정할 일이 거의 없겠지만, 에이전트 하니스를 직접 구축하는 경우라면 이 부분에 가장 많은 공을 들여야 합니다.

CLAUDE.md

CLAUDE.md는 간결하게 유지하면서 저장소의 용도를 간략히 설명하되, 토큰의 대부분은 코드베이스 내부의 주의 사항을 기록하는 데 할애하세요. 예를 들어 타입을 단 하나의 모놀리식 파일에만 정의하는 방식으로 코드를 구성한다면, 그런 내용을 담으면 됩니다. 파일 시스템이나 저장소를 보면 Claude가 이미 알 수 있는 '당연한' 내용은 굳이 기재하지 마세요.

점진적 공개를 적극 활용하세요. 예를 들어, 작업 결과 검증에 관한 고유한 지침이 여러 가지 있다면, 별도의 검증 Skill을 만들고 CLAUDE.md에서 이를 참조하도록 구성하는 것이 좋습니다.

Skills

Skills는 Claude가 필요한 정보를 필요한 시점에 찾을 수 있도록 안내하는 가벼운 가이드로 생각하세요. 특히 중요한 영역이 아니라면, 지나치게 제약적으로 만들지 않도록 주의하세요.

내용이 긴 Skill은 가능한 한 점진적 공개를 적용하여 여러 파일로 분리하고 세분화하세요.

Skills는 여러분 개인이나 팀, 또는 제품만이 가진 특유의 관점, 지식, 모범 사례를 담을 때 가장 효과적입니다.

참조 자료

@ 멘션으로 파일을 참조 자료로 포함할 수 있습니다. 참조 자료를 통해 Claude는 현재 계획과 관련된 심층 정보를 필요할 때 확인할 수 있습니다.

참조 자료는 명세서 파일, 목업(mockup), 심지어 전체 코드베이스가 될 수도 있습니다. 일반적으로 코드 형태의 파일을 활용하는 것이 좋습니다. Claude가 잘 아는 언어로 작성된 명확하고 정밀한 지시를 제공할 수 있기 때문입니다. 예를 들어, 디자인을 설명하는 텍스트나 스크린샷보다 HTML 목업이 훨씬 더 나은 결과물을 만들어냅니다.

단순화 시도해보기

저희가 그랬듯, 시스템 프롬프트, Skills, CLAUDE.md 파일 전반을 단순화할 필요가 있을 수 있습니다. 이 작업을 자동으로 도와주는 `claude doctor;` 명령어도 새롭게 도입했습니다. 더 발전된 모델을 프롬프트하는 방법에 대한 자세한 내용은 Fable 필드 가이드를 참고하세요.

이 글은 Anthropic 기술 스태프 멤버 Thariq Shihipar가 작성했습니다.