출처
- source_url: https://x.com/trq212/status/2080710971228918066
- author: @trq212
- published: 2026-07-25
- raw: raw source:
web-2026-07-25-The new rules of context engineering for Claude 5 models - 비고: 원문 전문의 한국어 번역. 시스템 프롬프트 인용문과 명령어(
claude doctor,/doctor,ToolSearch)는 그대로 옮겨 적을 수 있도록 영어 원문을 함께 남겼다.
번역
앞서 최신 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)
종합해 보면, 시스템 프롬프트로도 CLAUDE.md 파일과 스킬로도 Claude Code를 지나치게 옥죄고 있었습니다.
예를 들어 사내에서 Claude Code를 쓴 기록을 읽어 보면, 한 요청 안에 “적절히 문서를 남길 것”, “주석을 절대 달지 말 것” 같은 상충하는 메시지가 여러 개 섞여 있습니다. 시스템 프롬프트와 스킬, 사용자 요청이 서로 부딪히는 것입니다.
대개 Claude는 사용자의 의도를 읽어 옳은 답에 도달합니다. 다만 무엇을 할지 정하기 전에, 이렇게 겹치고 충돌하는 메시지를 더 조심스럽게 따져야 합니다.
이런 제약은 한때 최악의 상황을 막기 위해 필요했지만, 이제는 상당수를 지우고 대신 모델이 주변 컨텍스트와 판단력을 쓰게 해도 된다는 것을 알게 됐습니다.
게다가 Claude Code에는 이제 도구가 훨씬 많습니다. 예전에는 Claude가 기억과 정보, 지침을 CLAUDE.md에 의존했습니다. 지금은 메모리와 아티팩트, 스킬이 있어서, Claude가 이것들로 세션을 넘나들며 컨텍스트를 불러오고 공유하는 새로운 방법을 스스로 만들어 냅니다.
예전과 지금 (Then and now)
예전에 통했던 컨텍스트 엔지니어링 모범 사례 중 여럿은 이제 근거 없는 통념이 됐습니다. 예를 들면 이런 것들입니다.
예전: Claude에게 규칙을 준다 → 지금: Claude가 판단하게 둔다
Claude Code를 처음 내놓았을 때는 파일 삭제 같은 최악의 상황을 Claude가 반드시 피하게 해야 했습니다. 그래서 늘 옳지는 않더라도 유난히 강한 지침을 주곤 했습니다. 예전 시스템 프롬프트에는 이런 문구가 있었습니다.
In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max. Don’t create planning, decision, or analysis documents unless the user asks for them — work from conversation context, not intermediate files.
(코드에서는 주석을 쓰지 않는 것을 기본으로 한다. 여러 문단짜리 독스트링이나 여러 줄짜리 주석 블록은 절대 쓰지 말고, 길어야 한 줄로 끝낸다. 사용자가 요청하지 않는 한 계획·결정·분석 문서를 만들지 말고, 중간 파일이 아니라 대화 컨텍스트에서 작업한다.)
하지만 일부 프롬프트에서는 이 지침이 틀립니다. 문서화만 해도 사용자에게 나름의 취향이 있을 수 있고, 아주 복잡한 코드의 특정 부분에는 여러 줄짜리 주석 블록이 필요할 수도 있습니다.
그래도 예전 모델에는 이런 가드레일이 없으면 Claude가 쓰는 주석이 틀리는 경우가 많았기에, 그 정도 손해는 감수해야 했습니다. 반면 최신 모델은 판단력이 좋아져서, 명시적인 규칙 없이도 이런 결정을 잘 해냅니다.
새 시스템 프롬프트에는 이렇게 적혀 있습니다.
Write code that reads like the surrounding code: match its comment density, naming, and idiom.
(주변 코드처럼 읽히는 코드를 써라. 주석 밀도와 이름 짓기, 관용 표현을 주변에 맞춰라.)
예전: Claude에게 예시를 준다 → 지금: 인터페이스를 설계한다
도구 사용에서 가장 중요한 규칙은 쓰는 법을 예시로 보여 주는 것이었습니다. 그런데 최신 모델에서는 예시를 주면 오히려 탐색 공간이 그 언저리로 좁아진다는 것을 확인했습니다.
예시를 넣는 대신, 도구와 스크립트와 파일을 어떻게 설계할지를 더 고민하세요. Claude가 쓸 수 있는 파라미터는 무엇이고, 그 파라미터가 더 많은 것을 표현하게 하려면 어떻게 해야 할까요?
예컨대 Todo 도구를 보면, status를 pending·in_progress·completed라는 열거형(enum)으로 늘어놓기만 해도 Claude는 쓰는 법을 짐작합니다. 한 번에 하나만 in_progress로 두라는 지시가 우리가 원하는 동작을 규정해 줍니다.
예전: 전부 앞에 몰아넣는다 → 지금: 점진적 공개를 쓴다
Claude Code가 코딩에 집중했던 만큼, 시스템 프롬프트에는 코드 리뷰와 검증을 어떻게 하는지가 자세히 들어 있었습니다. 늘 필요하지는 않았지만, 필요한 순간에는 결정적인 정보였습니다.
그 뒤로 Claude Code는 점진적 공개, 즉 알맞은 컨텍스트를 알맞은 때에 불러오는 일을 아주 잘하게 됐습니다. 그래서 검증과 코드 리뷰를 각각 별도 스킬로 빼내, 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 설계란 어떤 모습인지)를 맞춰 보고 검증할 수 있습니다.
내 컨텍스트에 적용하기 (Applying this to your context)
지금까지의 이야기를 모아 보면, 실제로 컨텍스트를 짤 때는 어떤 모습이어야 할까요?
시스템 프롬프트 — 시스템 프롬프트는 제품 맥락과 단단히 묶여 있습니다. Claude가 어떤 제품 안에서 무슨 일을 하고 있는지 알려 주는 자리입니다. Claude Code를 쓴다면 이것을 건드릴 일이 거의 없겠지만, 직접 에이전트 하네스를 만든다면 여기에 시간을 많이 들여야 합니다.
CLAUDE.md — CLAUDE.md는 가볍게 유지하세요. 저장소가 무엇을 위한 것인지는 짧게 적고, 토큰은 대부분 코드베이스 안의 함정에 쓰세요. 예를 들어 타입을 오직 한 파일에만 몰아 두는 구조라면 그런 것을 적습니다. 파일 시스템이나 저장소만 봐도 Claude가 알 수 있는 ‘뻔한’ 내용은 적지 마세요.
더 자세한 내용은 점진적 공개로 넘기세요. 작업을 검증하는 고유한 절차가 여럿이라면, 검증 스킬을 하나 만들고 CLAUDE.md에서 그것을 가리키면 됩니다.
스킬 — 스킬은 Claude가 필요할 때 정보를 찾아가도록 돕는 가벼운 안내서라고 생각하세요. 아주 중요한 영역이 아니라면 지나치게 옥죄지 마세요.
긴 스킬이라면 점진적 공개를 최대한 활용해, 여러 파일로 쪼개 두세요.
스킬은 여러분과 팀, 제품에만 해당하는 관점과 지식, 모범 사례를 담을 때 가장 좋습니다.
레퍼런스 — 파일을 @ 멘션하면 레퍼런스로 끌어올 수 있습니다. 레퍼런스가 있으면 Claude가 지금 계획에 관한 깊이 있는 정보를 참조합니다.
명세 파일이나 목업, 심지어 코드베이스 전체가 레퍼런스가 될 수 있습니다. 대체로 코드로 된 파일을 우선하세요. Claude가 아주 잘 아는 언어로 명확하고 충실한 지시를 전달하기 때문입니다. 예를 들어 디자인을 HTML 목업으로 주면, 말로 설명하거나 스크린샷을 주는 것보다 대체로 결과가 좋습니다.
단순하게 만들어 보세요 (Try simplifying)
시스템 프롬프트와 스킬, CLAUDE.md 전반에서 여러분도 우리처럼 단순화해야 할지 모릅니다. 이 작업을 자동으로 돕는 claude doctor 명령을 새로 내놓았습니다. 더 발전한 모델에 프롬프트를 주는 방법을 자세히 알고 싶다면 Fable 필드 가이드를 참고하세요.