• Claude Opus 5와 Claude Fable 5에서는 Claude Code의
  시스템 프롬프트를 80% 이상 줄이고도 코딩 평가에서 측정 가능한 성능 저하가 없었음
• 과거 모델의 최악 상황을 막던 세부 규칙은 시스템 프롬프트·Skills·CLAUDE.md·사용자 요청 사이에서 충돌할 수 있어, 최신 모델에는
  주변 맥락과 자체 판단을 활용하게 하는 편이 나음
• 모든 지침과 도구 예시를 미리 제공하는 대신, 표현력 있는 인터페이스와 필요한 시점에 정보·도구를 불러오는
  점진적 공개(progressive disclosure) 를 적용함
• CLAUDE.md에는 저장소의 함정만 간결하게 기록하고 긴 지침은 Skills로 분리하며, 명세·테스트 스위트·HTML 모형·코드·평가 기준표 같은
  풍부한 참조 자료를 활용하는 구성이 권장됨
  /doctor

와 claude doctor

로 Skills와 CLAUDE.md의 크기를 조정할 수 있으며, 최신 모델의 컨텍스트는 반복과 과도한 제약을 줄이고 필요할 때 관련 정보를 찾도록 구성해야 함

프롬프트를 넘어선 컨텍스트 엔지니어링

• Claude가 메시지를 처리할 때 사용자 프롬프트는 전체 컨텍스트의 일부이며, 나머지는
  시스템 프롬프트, Skills, CLAUDE.md, 메모리 등에서 조립됨
• 컨텍스트 엔지니어링은 여러 요청에 공통으로 적용되므로 개별 프롬프트처럼 구체적으로 작성하기 어렵지만, Claude Code와 자체 에이전트의 결과에 큰 영향을 줌
• 사용자 요청을 미리 알 수 없는 상태에서 일반적인 프롬프트와 지침을 설계해야 하며, Claude의 능력이 발전할수록 적합한 방식도 달라짐
• Claude Opus 5와 Claude Fable 5에서는 Claude Code 시스템 프롬프트의
  80% 이상을 삭제해도 코딩 평가에서 측정 가능한 성능 저하가 없었음
• 이 모범 사례는
  claude doctor

에 반영됐으며, Claude Code에서는 /doctor

로 Skills와 CLAUDE.md를 적정한 크기로 조정할 수 있음

과도한 제약에서 모델 풀어주기

• 기존 Claude Code는 시스템 프롬프트뿐 아니라 CLAUDE.md와 Skills에서도
  지나치게 많은 제약을 받았음

• 한 요청에서 “적절한 문서를 남겨라”와 “주석을 추가하지 마라” 같은 지침이 시스템 프롬프트·Skills·사용자 요청을 통해 충돌할 수 있음

• Claude가 사용자 의도를 해석할 수 있어도, 겹치거나 충돌하는 지침 때문에 행동을 정하기 전에 더 신중하게 사고해야 함

• 과거에는 최악의 상황을 피하려고 이런 제약이 필요했지만, 최신 모델은 여러 제약을 삭제하고
  주변 컨텍스트와 자체 판단을 활용하게 할 수 있음

• Claude Code가 활용할 수 있는 도구도 늘어남

• 과거에는 CLAUDE.md가 메모리·정보·지침의 주요 저장소였음

• 현재는 메모리, 아티팩트, Skills를 통해 세션 사이에서 컨텍스트를 불러오고 공유할 수 있음

고정 규칙보다 맥락 기반 판단 활용

• 초기 Claude Code에는 파일 삭제 같은 최악의 상황을 막기 위해 항상 적절하지는 않은 강한 지침을 넣었음

• 이전 시스템 프롬프트는 코드에 기본적으로 주석을 작성하지 않고, 여러 문단의 docstring이나 여러 줄 주석을 금지하며, 사용자가 요청하지 않으면 계획·의사결정·분석 문서를 만들지 않도록 요구했음

• 이런 규칙은 일부 요청에서 부적절할 수 있음

• 사용자가 별도의 문서화 선호를 가질 수 있음

• 복잡한 코드의 특정 부분에는
  여러 줄 주석이 필요할 수 있음

• 구형 모델은 보호 장치가 없으면 잘못된 주석을 작성하는 경우가 많아 이런 절충이 필요했지만, 최신 모델은 명시적 규칙 없이도 관련 결정을 더 잘 처리함

• 새로운 시스템 프롬프트는 “주변 코드처럼 읽히는 코드를 작성하고, 주석 밀도·이름 짓기·관용 표현을 맞추라”는
  맥락 기반 지침을 사용함

예시보다 표현력 있는 인터페이스 설계

• 과거 도구 사용의 핵심 규칙은 Claude에게
  사용 예시를 제공하는 것이었음
• 최신 모델에서는 예시가 탐색 범위를 특정 영역으로 제한할 수 있으므로, 도구·스크립트·파일의 인터페이스와 매개변수 표현력을 우선해야 함
• Todo 도구의
  status

를 pending

, in_progress

, completed

열거형으로 정의하면 사용법을 자연스럽게 암시할 수 있음

• 한 항목만
  in_progress

로 유지하라는 지침은 요청된 동작을 인터페이스 수준에서 구체화함

필요한 순간에 정보를 여는 점진적 공개

• Claude Code가 코딩에 집중하던 초기에는 코드 검토와 검증 방법을 시스템 프롬프트에 상세히 넣었음
• 이런 정보는 항상 필요하지 않았지만 특정 작업에서는 중요했음
• 현재는 필요한 시점에 적절한 컨텍스트를 불러오는
  점진적 공개를 활용할 수 있음
• 검증과 코드 검토 지침을 각각 별도의 Skill로 옮겨 Claude Code가 선택적으로 호출하게 함
• 일부 도구는 지연 로딩되며, 에이전트가 사용 전에
  ToolSearch

로 전체 정의를 검색해야 함

• Task 도구처럼 많은 도구를 제공하면서도 필요하기 전에는 컨텍스트를 차지하지 않게 할 수 있음

• CLAUDE.md와 Skill.md를 가능한 모든 관행의 중앙 저장소로 만들 필요는 없음

• 대신 필요할 때 불러오는
  파일 트리로 구성할 수 있으며, 이 접근법은 작업별 동적 워크플로 하네스에서도 다룸

반복 지침을 단순한 도구 설명으로 통합

• 이전 Claude 모델은 같은 지침을 반복해야 할 때가 있었고, 컨텍스트 시작 부분보다 끝부분의 지침을 더 잘 따르기도 했음
• 이 때문에 시스템 프롬프트 본문과 도구 설명 양쪽에 같은 도구 사용 지침이나 예시를 넣었음
• 최신 모델에서는 반복 예시를 삭제하고
  도구 사용법을 도구 설명에만 배치할 수 있음

CLAUDE.md에서 자동 메모리로 전환

• 과거에는
  #

단축키로 정보를 CLAUDE.md에 자동 작성해 사용자가 Claude의 메모리를 직접 저장하도록 권장했음

• 현재 Claude는 작업과 사용자에게 관련된 정보를
  자동으로 메모리화함

단순 명세를 넘어선 풍부한 참조 자료

• 계획 모드의 Claude Code는 필요할 때 다시 참조하도록 Markdown 계획 파일에 크게 의존했으며, 장기 프로젝트에서는 코드베이스 안에 명세를 저장하기도 했음

• 최신 Claude는 더 복잡한 형식의
  참조 자료를 처리할 수 있음

• 새로운 아티팩트 기능으로 생성한 HTML 아티팩트

• 다른 코드베이스에서 이식할 함수 같은 코드

• 상세한 테스트 스위트로 표현한 명세

• 평가 기준표(rubric)는 특정 분야의 취향이나 품질 기준을 Claude가 시도하고 검증하게 하는 또 다른 참조 형식임

• 좋은 API 설계가 무엇인지 같은 기준을 정의할 수 있음

• 동적 워크플로를 통해 해당 평가 기준표를 사용하는
  검증 에이전트를 생성할 수 있음

컨텍스트 구성 요소별 역할

시스템 프롬프트

• 제품 컨텍스트와 밀접하게 연결되며, Claude가 어떤 제품 안에서 무슨 작업을 하는지 알려줌

• Claude Code 사용자가 수정할 일은 거의 없지만, 자체
  에이전트 하네스를 만든다면 많은 시간을 들여야 하는 영역임

CLAUDE.md

• 가볍게 유지하고 저장소의 용도를 짧게 기술하되, 대부분의 토큰은 코드베이스 안의
  주의할 함정을 기록하는 데 사용해야 함

• 모든 타입을 하나의 단일 파일에만 두는 저장소 규칙은 기록할 가치가 있음

• 파일 시스템이나 저장소를 살펴보면 Claude가 알 수 있는 자명한 정보는 피해야 함

• 작업 검증에 여러 고유 지침이 있다면 검증 Skill을 만들고 CLAUDE.md에서 참조하는 방식으로 점진적 공개를 적용함

Skills

• Claude가 필요할 때 정보를 찾도록 돕는
  가벼운 안내서로 구성함

• 매우 중요한 영역이 아니라면 지나친 제약을 피해야 함

• 긴 Skill은 여러 파일로 나눠 점진적으로 불러오게 하는 편이 나음

• 개인·팀·제품에 특화된 견해, 지식, 모범 사례를 담을 때 가장 유용함

참조 자료

@

로 파일을 멘션하면 현재 계획과 관련된 상세 정보를 Claude가 확인할 수 있음

• 명세 파일, 모형, 전체 코드베이스도 참조 자료가 될 수 있음
• 코드는 Claude가 잘 아는 언어로 명확하고 충실한 지침을 제공하므로 일반적으로
  코드 형태의 파일을 우선하는 편이 나음
• 디자인 설명이나 스크린샷보다 HTML 디자인 모형이 일반적으로 더 나은 결과를 만듦

기존 컨텍스트 단순화

• 시스템 프롬프트, Skills, CLAUDE.md 전반에서 불필요한 규칙·반복·정보를 삭제해
  컨텍스트를 단순화해야 함
  claude doctor

명령은 이 단순화 작업을 자동으로 지원함

• 고급 모델의 프롬프트 작성법은 Claude Fable 현장 가이드에서 추가로 확인할 수 있음

댓글과 토론