앞서 저는 최신 Claude 5 모델에 프롬프트를 쓰는 가장 좋은 방법과, 만들고 싶은 것을 찾아가며 모델과 함께 반복 작업하는 방법을 쓴 적이 있습니다.
그런데 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의 족쇄 풀기
전체적으로 저희는 시스템 프롬프트에서도, CLAUDE.md 파일과 스킬에서도 Claude Code를 지나치게 제약하고 있었습니다.
예를 들어 사내에서 Claude Code를 쓴 기록을 읽어 보면, 한 요청 안에 서로 부딪히는 메시지가 여러 개 보입니다. "문서는 적절히 남겨라"와 시스템 프롬프트의 "주석을 달지 마라"처럼, 시스템 프롬프트와 스킬과 사용자 요청이 서로 충돌합니다.
보통 Claude는 사용자의 의도를 읽어서 맞는 답을 찾아냅니다. 다만 이렇게 겹치고 충돌하는 메시지를 두고 무엇을 할지 정하기 전에 더 오래 생각해야 합니다.
이런 제약은 한때 최악의 상황을 피하려고 필요했지만, 지금은 상당수를 지우고 Claude가 주변 컨텍스트와 판단력을 쓰게 해도 된다는 것을 알게 됐습니다.
게다가 Claude Code에는 이제 도구가 훨씬 많습니다. 예전에는 Claude가 기억과 정보와 지침을 CLAUDE.md에 기댔습니다. 지금은 메모리, Artifacts, 스킬이 있어서 Claude가 세션을 넘나들며 컨텍스트를 불러오고 공유하는 새로운 방법을 직접 만들 수 있습니다.
예전과 지금
예전의 컨텍스트 엔지니어링 모범 사례 가운데 이제는 미신이 된 것들이 있습니다.
예전: Claude에게 규칙을 준다 / 지금: Claude가 판단하게 둔다
Claude Code를 처음 내놨을 때는 파일을 지우는 것 같은 최악의 상황을 Claude가 피하도록 확실히 해야 했습니다. 그래서 늘 맞지는 않는 아주 강한 지침을 줬습니다. 예를 들어 시스템 프롬프트에 이렇게 적었습니다.
코드에서는 기본적으로 주석을 쓰지 마라. 여러 문단짜리 독스트링이나 여러 줄 주석 블록은 절대 쓰지 마라. 짧게 한 줄이면 충분하다. 사용자가 요청하지 않으면 계획, 결정, 분석 문서를 만들지 마라. 중간 파일이 아니라 대화 컨텍스트에서 작업하라.
그런데 어떤 프롬프트에서는 이 지침이 틀렸습니다. 문서화만 해도 사용자마다 선호가 다르고, 아주 복잡한 코드의 어떤 부분은 여러 줄 주석 블록이 필요할 수 있습니다.
그래도 예전 모델에서는 이런 가드레일이 없으면 Claude가 쓰는 주석이 여러 경우에 틀렸기 때문에, 저희는 그 대가를 받아들여야 했습니다. 하지만 새 모델은 판단력이 더 좋아서 명시적인 규칙 없이도 이런 결정을 잘 해냅니다.
새 시스템 프롬프트에는 이렇게 적었습니다. 주변 코드처럼 읽히는 코드를 써라. 주석 밀도, 이름 짓기, 관용적인 표현을 주변에 맞춰라.
예전: Claude에게 예시를 준다 / 지금: 인터페이스를 설계한다
도구 사용의 첫 번째 규칙은 쓰는 법을 예시로 보여 주는 것이었습니다. 최신 모델에서는 예시가 오히려 모델을 특정 탐색 범위에 가둔다는 것을 확인했습니다.
예시를 쓰는 대신 도구와 스크립트와 파일의 설계를 더 고민하세요. Claude가 쓸 수 있는 파라미터는 무엇이고, 어떻게 하면 더 잘 드러낼 수 있을까요?
예를 들어 Todo 도구에서는 상태를 pending, in_progress, completed라는 열거형으로 두기만 해도 Claude에게 쓰는 법을 알려 줍니다. 한 번에 하나만 in_progress로 두라는 지침이 저희가 원하는 동작을 정해 줍니다.
예전: 전부 앞에 넣는다 / 지금: 점진적 공개를 쓴다
Claude Code가 코딩에 집중했기 때문에, 저희 시스템 프롬프트에는 코드 리뷰와 검증을 어떻게 하는지 자세히 들어 있었습니다. 늘 필요하지는 않았지만 필요할 때는 아주 중요한 정보였습니다.
그 뒤로 Claude Code는 점진적 공개, 그러니까 알맞은 때에 알맞은 컨텍스트를 불러오는 일을 아주 잘하게 됐습니다. 예를 들어 검증과 코드 리뷰를 각각 스킬로 옮겨서 Claude Code가 필요할 때만 부르도록 했습니다.
점진적 공개는 스킬에만 쓰는 것이 아닙니다. 도구에도 씁니다. 저희 도구 가운데 일부는 '지연 로딩'이라, 에이전트가 쓰기 전에 ToolSearch로 전체 정의를 찾아야 합니다. 덕분에 Task 도구 같은 도구를 더 많이 두면서도 필요할 때까지 컨텍스트를 차지하지 않습니다.
같은 방식을 여러분의 CLAUDE.md와 Skill.md 파일에도 쓸 수 있습니다. 흔한 미신은 이 파일들을 마주칠 만한 모든 관행을 모아 둔 중앙 저장소로 만들어야 한다는 것입니다. 그러지 않으면 Claude가 못 찾는다고 보기 때문입니다. 대신 알맞은 때에 불러올 수 있는 파일 트리를 두는 쪽을 고려하세요.
예전: 반복해서 말한다 / 지금: 단순한 도구 설명
예전 Claude 모델은 지침을 반복해 줘야 할 때가 있었고, 컨텍스트 창의 앞쪽보다 뒤쪽에 있는 지침을 더 잘 따르는 편이었습니다. 그래서 저희 시스템 프롬프트는 도구 이야기를 본문에도 넣고 도구 설명에도 지침을 넣곤 했습니다.
이제는 이렇게 반복하는 예시를 지우고, 도구 쓰는 법은 시스템 프롬프트가 아니라 도구 설명에 넣을 수 있다는 것을 확인했습니다.
예전: CLAUDE.md에 기억을 담는다 / 지금: 자동 메모리
예전에는 # 단축키로 CLAUDE.md에 자동으로 적어서 Claude의 메모리에 저장하라고 권했습니다. 지금은 Claude가 작업과 사용자와 관련 있는 기억을 알아서 저장합니다.
예전: 단순한 스펙 / 지금: 풍부한 참조
플랜 모드에서 Claude Code는 계획을 담은 마크다운 파일에 많이 기댔습니다. 계획을 파일로 저장해 두면 Claude가 필요할 때 참조하기 좋았습니다. 비슷한 모범 사례로, 긴 프로젝트를 진행하는 동안 Claude가 참조하도록 스펙을 코드베이스에 저장하는 방법도 있었습니다.
그런데 Claude가 점점 더 복잡한 참조를 다룰 수 있게 됐습니다. 단순한 마크다운 파일 대신, 새 Artifacts 기능으로 만든 HTML 아티팩트(Artifact)를 참조할 수 있습니다.
코드 형태로 참조를 줄 수도 있습니다. 자세한 테스트 스위트가 스펙이 될 수 있고, Claude가 그대로 가져다 쓸 다른 코드베이스의 함수도 스펙이 될 수 있습니다.
평가 기준도 참조의 한 형태입니다. 평가 기준이 있으면 Claude가 Dynamic Workflows를 쓰고 그 평가 기준을 적용하는 검증 에이전트를 띄워서, 특정 분야에서 여러분의 취향(예: 좋은 API 설계란 무엇인가)을 확인해 볼 수 있습니다.
내 컨텍스트에 적용하기
지금까지 이야기를 모으면, 컨텍스트를 조립할 때 어떤 모습이 될까요?
시스템 프롬프트 시스템 프롬프트는 제품 맥락과 아주 밀접합니다. Claude에게 어떤 제품 안에서 무슨 일을 하고 있는지 알려 줍니다. Claude Code에서는 이 부분을 고칠 일이 거의 없겠지만, 직접 에이전트 하네스를 만든다면 여기에 시간을 많이 써야 합니다.
CLAUDE.md CLAUDE.md는 가볍게 두고 저장소가 무엇을 위한 것인지 짧게 적으세요. 대신 토큰의 대부분은 코드베이스 안의 함정에 쓰세요. 예를 들어 타입을 한 파일에만 모아 두고 다른 곳에는 두지 않는 식으로 코드를 구성했을 수 있습니다. Claude가 파일 시스템이나 저장소만 봐도 아는 '뻔한' 내용은 적지 마세요.
더 자세한 내용은 점진적 공개를 쓰세요. 예를 들어 작업을 검증하는 고유한 지침이 여럿이라면 검증 스킬을 만들고 CLAUDE.md에서 그것을 가리키세요.
스킬 스킬은 Claude가 필요할 때 정보를 찾아가도록 돕는 가벼운 안내서라고 생각하세요. 아주 중요한 영역이 아니라면 지나치게 제약하지 마세요.
긴 스킬은 점진적 공개를 최대한 쓰세요. 여러 파일로 나누세요.
스킬은 여러분이나 팀, 제품에만 있는 의견이나 지식, 모범 사례를 담을 때 가장 좋습니다.
참조 파일을 @로 멘션해서 참조로 넣을 수 있습니다. 참조가 있으면 Claude가 지금 계획을 깊이 들여다볼 수 있습니다.
스펙 파일이나 목업, 심지어 코드베이스 전체가 참조가 될 수 있습니다. 대체로 코드에 있는 파일을 쓰는 편이 좋습니다. Claude가 아주 잘 아는 언어로 명확하고 정확한 지시를 주기 때문입니다. 예를 들어 디자인을 설명한 글이나 스크린샷보다 HTML 목업이 대체로 더 좋은 결과를 냅니다.
단순하게 만들어 보세요
시스템 프롬프트와 스킬과 CLAUDE.md 파일 전반에서, 여러분도 저희처럼 단순하게 만들어야 할 수 있습니다. 이 일을 자동으로 돕는 claude doctor라는 새 명령도 내놨습니다. 더 발전한 모델에 프롬프트를 쓰는 법이 궁금하다면 Fable 필드 가이드를 보세요.
Deep Dive
2026-07-25
"줄여라"가 아니라 "무엇에 쓸지 바꿔라"
이 글을 처음 읽으면 분량을 줄이라는 말로 읽힌다. 80%를 지웠다는 숫자가 앞에 나오기 때문이다. 그런데 글이 실제로 지우라는 대상은 구체적이다. 서로 충돌하는 규칙, 모델을 좁은 탐색 범위에 가두는 예시, 시스템 프롬프트와 도구 설명에 중복으로 적은 지침, 판단으로 대체 가능한 강한 금지 조항이다.
반대로 늘리라는 것도 같이 나온다. CLAUDE.md에서는 토큰의 대부분을 코드베이스 안의 함정에 쓰라고 하고, 스펙은 마크다운 대신 테스트 스위트나 HTML 목업 같은 더 무거운 참조를 쓰라고 한다.
그리고 지운 것 상당수는 사라진 게 아니라 옮긴 것이다. 코드 리뷰와 검증은 별도 스킬로 나갔고, 도구 정의는 ToolSearch로 찾는 지연 로딩이 됐다. 필요할 때는 여전히 다 들어온다. 항상 들어오지 않을 뿐이다.
넣을지 말지를 가르는 세 질문
이 글의 기준을 실제로 쓰려면 판별 질문이 필요하다.
- 이 줄을 지우면 모델이 다르게 행동하는가? 아니면 뺀다.
- 다르게 행동한다면 틀렸을 때 누가 잡아주는가? 검사기가 잡아준다면 줄이거나 뺀다. 다만 실패 왕복 비용이 크면 한 줄은 값을 한다.
- 아무도 안 잡아주고 결과가 조용히 잘못되는가? 그러면 넣고, 이유를 같이 쓴다.
"하나쯤 넣어도 손해 없다"가 틀린 이유는 한계비용이 0이 아니기 때문이다. 지침이 늘면 충돌 확률이 오르고, 뻔한 지침이 중요한 지침의 신호를 덮고, 중복된 지침은 반드시 갈라진다.
판단하는 쪽과 실행하는 쪽의 정보 조건이 다르다
이 글을 실제 레포에 적용하면서 글에 없는 함정을 만났다. "모델이 알아서 할 수 있다"는 판단을 누가 내리느냐의 문제다.
그 판단은 풀 컨텍스트를 쥔 세션이 규칙 원문을 방금 읽은 상태에서 내린다. 정작 그 지침을 쓰는 쪽은 상위 설정을 상속받지 않는 격리된 워커, 도구셋이 다른 다른 CLI, 몇 달 뒤의 냉간 세션이다. 최적 관측 조건에서 "알아낼 수 있다"고 판정한 것이 최악 조건에서도 안전하다는 보장은 없다.
그래서 삭제 후보 중 넷을 남겼다. 비밀값을 설정 파일에 쓰지 말라는 절대 규칙(위반해도 아무도 안 잡고 되돌릴 수 없다), 외부 콘텐츠를 신뢰하지 말라는 경고(인젝션 방어는 페이로드 양쪽에 사본이 필요하다), 워커에게 넘기는 프롬프트(새 컨텍스트는 본문을 못 본다), 도구 부재라는 비대칭을 설명하는 문단(유추가 불가능하다).
예외를 넓혀야 참이 되는 규칙은 규칙이 아니다
작업 중에 자기 레포를 위반하는 규칙을 찾았다. 설정 파일은 전부 영어로 쓰라고 했는데 그 아래 두 파일이 한국어였다. 처음에는 예외를 넓혀서 맞췄다. 그런데 예외를 넓히고 나니 남는 제약이 거의 없었다. 결국 규칙 자체를 지웠다.
규칙이 현실과 어긋날 때 예외를 붙여 살리려는 반응이 먼저 나오는데, 예외를 넓혀야 참이 되는 규칙은 애초에 규칙이 아니었다는 신호로 읽는 편이 낫다.
Key Insight
지침의 값은 길이가 아니라 관측 비대칭에서 나온다. 모델이 스스로 관측할 수 있는 것은 빼고, 나만 알거나 틀렸을 때 아무도 못 잡는 것만 남긴다. 그 판정은 정보가 가장 많은 관측자가 내리지만 적용은 정보가 가장 적은 실행자가 받는다는 것을 잊지 말 것.