발신: TLDR 2026-07-27 | 원문: Anthropic Claude Blog (2026-07-24, 5분 분량)
전문 번역
Claude에 메시지를 보낼 때, 프롬프트는 Claude가 받는 컨텍스트의 아주 작은 일부일 뿐이다. 컨텍스트의 대부분은 시스템 프롬프트, Skills, CLAUDE.md 파일, 메모리, 그 밖의 소스로부터 조립된다. Anthropic은 이것을 "컨텍스트 엔지니어링(context engineering)"이라 부르며, 이것이 Claude Code를 쓰거나 자신만의 에이전트를 만들 때 결과물에 큰 영향을 준다.
프롬프트와 달리 컨텍스트는 여러 요청에 걸쳐 일반적으로 사용되기 때문에 그만큼 구체적일 수 없다. 유저의 프롬프트가 무엇일지 모르는 상태에서 Claude를 위한 이런 일반적 프롬프트와 가이드를 어떻게 만들 것인가?
Claude 자체의 역량이 진화하면서 이 질문은 놀랄 만큼 까다로워질 수 있다. 최근 Anthropic은 최신 세대 Claude 모델을 프롬프팅하는 방식에서 큰 도약을 발견했다. Claude Opus 5, Claude Fable 5 같은 모델의 경우 Claude Code 시스템 프롬프트의 80% 이상을 제거했는데도, 코딩 평가에서 측정 가능한 성능 손실이 없었다.
이번 최신 모델 세대를 프롬프팅하며 배운 것, 그리고 이를 바탕으로 컨텍스트 엔지니어링을 업데이트하는 방법을 소개한다. 이 모범 사례들은 claude doctor;에 반영되어 있으며, Claude Code에서 /doctor 명령으로 스킬과 CLAUDE.md 파일의 크기를 적정화할 수 있다.
Claude의 족쇄 풀기 (Unhobbling Claude)
전반적으로 Anthropic은 시스템 프롬프트뿐 아니라 CLAUDE.md 파일과 스킬을 통해서도 Claude Code를 과도하게 제약해왔다는 것을 발견했다.
예를 들어 Claude Code의 실제 사용 기록을 살펴보면, 시스템 프롬프트·스킬·유저 요청이 서로 충돌하는 메시지들을 볼 수 있다. "적절하게 문서를 남겨라"와 "절대 주석을 달지 마라" 같은 지시가 한 요청 안에서 동시에 존재하는 식이다.
일반적으로 Claude는 이런 충돌하는 메시지들 속에서도 유저의 의도를 해석해 올바른 답에 도달할 수 있지만, 어떻게 할지 결정하기 전에 이 겹치고 상충하는 메시지들에 대해 더 신중하게 생각해야만 한다.
이런 제약들은 한때 최악의 시나리오를 피하기 위해 필요했지만, 이제는 그 상당수를 삭제하고 모델이 주변 컨텍스트와 판단력을 활용하도록 둘 수 있다는 것을 발견했다.
또한 Claude Code는 이제 훨씬 많은 도구를 갖고 있다. 예전에는 Claude가 메모리·정보·가이드의 원천으로 CLAUDE.md에 의존했지만, 지금은 메모리·아티팩트·스킬이 있어서 세션 간 컨텍스트를 불러오고 공유하는 새로운 방식을 Claude 스스로 만들어낼 수 있다.
그때와 지금 (Then and Now)
이전의 여러 컨텍스트 엔지니어링 모범 사례들이 이제는 "신화"가 되어버렸다.
그때: Claude에게 규칙을 줘라 / 지금: Claude가 판단력을 쓰게 하라
Claude Code를 처음 출시했을 때는 파일 삭제 같은 최악의 시나리오를 확실히 피해야 했다. 그래서 항상 옳지는 않더라도 특히 강한 가이드를 줬다. 예를 들어 시스템 프롬프트에는 이런 문구가 있었다.
"코드에서는 기본적으로 주석을 달지 않는다. 여러 문단짜리 독스트링이나 여러 줄짜리 주석 블록은 절대 쓰지 마라 — 한 줄이 최대다. 유저가 요청하지 않는 한 계획·결정·분석 문서를 만들지 마라 — 대화 맥락에서 작업하고, 중간 파일을 만들지 마라."
하지만 일부 프롬프트 부류에서는 이 가이드가 틀린 것으로 드러났다. 문서화의 경우 유저가 자신만의 선호가 있을 수 있고, 매우 복잡한 코드의 특정 부분은 여러 줄짜리 주석 블록이 필요할 수도 있다.
그럼에도 이런 가드레일 없이는 예전 모델이 작성하는 주석이 많은 경우 부정확했기 때문에 이 트레이드오프를 감수해야 했다. 하지만 최신 모델들은 더 나은 판단력을 갖고 있어서 명시적 규칙 없이도 이런 결정들을 잘 처리할 수 있다.
새 시스템 프롬프트에서는 이렇게 말한다: "주변 코드처럼 읽히는 코드를 작성하라: 주석 밀도, 네이밍, 관용구를 맞춰라."
그때: Claude에게 예시를 줘라 / 지금: 인터페이스를 설계하라
도구 사용의 첫 번째 규칙은 Claude에게 도구 사용법 예시를 주는 것이었다. 하지만 최신 모델에서는 예시를 주는 것이 오히려 탐색 공간을 특정 범위로 제약한다는 것을 발견했다.
예시를 쓰는 대신, 도구·스크립트·파일의 설계 자체를 더 고민하라 — Claude가 가진 파라미터가 무엇이고 어떻게 하면 더 표현력 있게 만들 수 있는가?
예를 들어 Todo 도구에서 상태를 pending, in_progress, completed로 나열하는 열거형(enumeration)만으로도 Claude에게 사용법을 힌트로 준다. "한 번에 하나의 항목만 in_progress로 두라"는 지시가 원하는 동작을 정의하는 데 도움이 된다.
그때: 모든 걸 처음에 다 넣어라 / 지금: 점진적 공개(progressive disclosure)를 사용하라
Claude Code는 코딩에 집중해왔기 때문에 시스템 프롬프트에 코드 리뷰·검증 방법에 대한 상세 정보가 포함돼 있었다. 항상 필요한 건 아니었지만, 필요할 때는 결정적인 정보였다.
이후 Claude Code는 점진적 공개 — 적절한 시점에 적절한 컨텍스트를 불러오는 것 — 에 매우 능숙해졌다. 예를 들어 검증과 코드 리뷰를 별도의 스킬로 옮겨서 Claude Code가 선택적으로 호출할 수 있게 했다.
점진적 공개는 스킬만을 위한 것이 아니라 도구에도 적용된다. 일부 도구는 '지연 로딩(deferred loading)'되어, 에이전트가 사용하기 전에 ToolSearch로 전체 정의를 검색해야 한다. 이 덕분에 필요할 때까지 컨텍스트를 차지하지 않는 도구(예: Task 도구)를 더 많이 둘 수 있다.
같은 원리를 CLAUDE.md와 Skill.md 파일에도 적용할 수 있다. 흔한 오해는, 그러지 않으면 Claude가 찾지 못할 것이므로 마주칠 수도 있는 모든 관행을 담은 중앙 저장소로 만들어야 한다는 것이다. 대신, 적절한 시점에 로드될 수 있는 파일들의 트리를 갖추는 것을 고려하라.
그때: 반복해서 말하라 / 지금: 간단한 도구 설명
예전 Claude 모델은 반복된 지시가 필요하거나, 컨텍스트 윈도우 시작보다 끝에 있는 지시를 더 잘 따르는 경향이 있었다. 그래서 시스템 프롬프트에는 메인 시스템 프롬프트와 도구 설명 양쪽에 걸쳐 도구에 대한 참조가 중복으로 들어가곤 했다.
이제는 이런 반복 예시를 삭제하고, 도구 사용법에 대한 지시를 시스템 프롬프트가 아닌 도구 설명 자체에 넣을 수 있다는 것을 발견했다.
그때: CLAUDE.md 파일에 메모리를 남겨라 / 지금: 오토메모리(Auto-memory)
예전에는 유저에게 # 단축키를 이용해 CLAUDE.md에 자동으로 기록하는 방식으로 Claude의 메모리에 저장하라고 권장했다. 지금은 Claude가 작업 및 사용자와 관련된 내용을 자동으로 메모리에 저장한다.
그때: 단순한 스펙 / 지금: 풍부한 참조 자료
플랜 모드에서 Claude Code는 계획을 담은 마크다운 파일에 크게 의존해왔다. 이런 파일을 계획으로 저장해두면 Claude가 필요할 때 참조하는 데 도움이 됐다. 비슷한 모범 사례로, 긴 프로젝트를 진행하는 동안 Claude가 참조할 수 있도록 코드베이스에 스펙을 저장하는 방법도 있었다.
(원문은 이 지점에서 다음 섹션으로 이어지지만, 웹 발췌 길이 제한으로 이후 내용은 생략됨. 전체 원문은 위 URL 참조.)
핵심 요약 (20줄)
- Claude에 보내는 메시지에서 프롬프트는 전체 컨텍스트의 작은 일부일 뿐이며, 나머지는 시스템 프롬프트·Skills·CLAUDE.md·메모리 등에서 조립된다.
- Anthropic은 이를 "컨텍스트 엔지니어링"이라 부르며 Claude Code와 자체 에이전트 구축 결과에 큰 영향을 준다고 설명한다.
- Claude Opus 5·Fable 5 등 최신 모델에서 Claude Code 시스템 프롬프트의 80% 이상을 삭제했는데도 코딩 평가 성능 손실이 없었다.
- 핵심 발견: 그동안 시스템 프롬프트·CLAUDE.md·스킬을 통해 Claude Code를 과도하게 제약해왔다는 것.
- 실제 사용 기록에서 "적절히 문서화하라"와 "절대 주석 달지 마라" 같은 상충하는 지시가 동시에 존재하는 문제가 발견됐다.
- 예전엔 최악의 시나리오(파일 삭제 등)를 막기 위해 강한 규칙이 필요했지만, 최신 모델은 판단력이 좋아 규칙 없이도 잘 처리한다.
- 새 시스템 프롬프트는 "주변 코드처럼 읽히는 코드를 작성하라"는 식으로, 규칙 대신 판단 기준을 제시한다.
- 도구 사용 예시를 주는 것은 오히려 Claude의 탐색 범위를 좁힌다는 것이 발견돼, 예시 대신 도구·인터페이스 설계 자체를 정교하게 하는 방향으로 전환했다.
- Todo 도구의 상태값을 pending/in_progress/completed로 제한한 것 자체가 사용법에 대한 암묵적 힌트가 된다.
- 예전엔 코드 리뷰·검증 정보를 시스템 프롬프트에 전부 미리 넣었지만, 이제는 점진적 공개(progressive disclosure)로 필요할 때만 불러온다.
- 검증과 코드 리뷰는 별도 스킬로 분리되어 Claude Code가 선택적으로 호출한다.
- 일부 도구는 '지연 로딩'되어 ToolSearch로 검색해야 전체 정의가 로드되며, 이 덕분에 미사용 시 컨텍스트를 차지하지 않는다.
- CLAUDE.md·Skill.md도 모든 걸 담은 저장소가 아니라 필요할 때 로드되는 파일 트리 구조로 만드는 것이 권장된다.
- 예전 모델은 반복 지시가 필요하거나 컨텍스트 끝쪽 지시를 더 잘 따랐지만, 최신 모델은 도구 설명 자체에 지시를 넣는 것만으로 충분하다.
- 시스템 프롬프트와 도구 설명에 중복으로 넣던 예시·지시는 삭제 가능해졌다.
- 예전엔 유저가 # 단축키로 CLAUDE.md에 수동으로 메모리를 남기도록 권장했지만, 지금은 Claude가 관련 내용을 자동으로 메모리에 저장하는 "오토메모리"를 사용한다.
- 플랜 모드에서는 마크다운 계획 파일에 크게 의존해왔고, 긴 프로젝트에는 코드베이스에 스펙을 저장해 참조하는 관행이 있었다.
- 전체적인 방향은 "규칙으로 통제"에서 "판단력을 신뢰"하는 쪽으로, "모든 걸 미리 제공"에서 "필요할 때 불러오기"로 이동하는 것이다.
- 이 모범 사례들은 Claude Code의
/doctor명령(claude doctor;)에 반영돼 있어 스킬·CLAUDE.md 크기를 적정화하는 데 쓸 수 있다. - 토니의 CLAUDE.md/AGENTS.md/SOUL.md 운영 방식과 직결되는 내용으로, 과도한 규칙 나열보다 판단 기준 제시+ 점진적 공개 구조가 최신 Claude 모델에 더 잘 맞는다는 시사점을 준다.