Claude 5 세대의 컨텍스트 엔지니어링 새 규칙

1. 이 글은 무엇에 관한 글인가?

한 줄로 요약하면 이렇습니다.

"AI에게 규칙을 더 많이 적어줄수록 잘한다"는 상식이 뒤집혔습니다. Anthropic은 Claude Code의 시스템 프롬프트에서 80% 이상을 삭제 했고, 코딩 평가 점수는 떨어지지 않았습니다.

지난 글들에서 저는 하네스를 잘 만드는 법(Frontend 하네스 엔지니어링)과 스스로 고치게 만드는 법(자가치유 하네스)을 다뤘습니다. 이번 글은 방향이 반대입니다. 하네스에서 무엇을 덜어낼 것인가 입니다.

지금까지 우리가 하던 일

하네스를 다뤄본 사람이라면 대부분 이 경로를 밟습니다.

AI가 실수함
   → CLAUDE.md에 "이렇게 하지 마" 한 줄 추가
   → 또 실수함
   → SKILL.md에도 같은 말 한 번 더 추가
   → 툴 설명에도 혹시 모르니 한 번 더
   → ...그렇게 3개월 뒤, CLAUDE.md는 400줄이 됨

규칙을 늘리는 건 즉각적인 안정감을 줍니다. "적어뒀으니 이제 안 틀리겠지." 그런데 규칙이 늘어날수록 서로 부딪히는 문장 도 같이 늘어납니다. Anthropic이 실제로 발견한 사례가 이렇습니다.

두 문장 모두 각각은 합리적입니다. 그런데 동시에 읽히면 모델은 "지금은 어느 쪽이지?"를 매번 계산해야 합니다. 그 계산이 곧 비용입니다.

무엇이 바뀌었나

핵심은 모델이 좋아졌다 는 것입니다. Claude 5 세대(Opus 5, Fable 5)는 주변 맥락을 보고 스스로 판단할 수 있습니다. 그래서 "정답을 미리 다 적어두는" 방식이 오히려 발목을 잡습니다.

실제로 바뀐 문장을 보면 감이 옵니다.

이전 (규칙으로 못 박기):

"코드에는 기본적으로 주석을 쓰지 마라. 여러 문단짜리 docstring이나 여러 줄 주석 블록은 절대 쓰지 마라 — 최대 한 줄."

이후 (판단에 맡기기):

"주변 코드처럼 읽히는 코드를 써라. 주석 밀도, 네이밍, 관용구를 주변에 맞춰라."

뒤쪽이 더 짧은데 더 많은 상황을 커버합니다. 앞쪽은 "주석이 촘촘한 레거시 파일을 고칠 때"라는 예외를 처리하지 못하지만, 뒤쪽은 알아서 처리합니다.

2. 6가지 규칙이 뒤집혔다

Anthropic이 정리한 변화는 6개입니다. 하나씩 보겠습니다.

규칙 1 — "지시" 대신 "판단"

규칙을 적을지 말지 판단하는 기준은 간단합니다.

• 모델이 주변을 보고 알 수 있는 것 → 적지 마세요. (예: 들여쓰기 폭, 주석 스타일)
• 주변을 봐도 알 수 없는 것 → 적으세요. (예: "이 저장소는 정적 익스포트라 서버 API를 못 쓴다")

전자를 적으면 노이즈가 되고, 후자를 안 적으면 사고가 납니다.

규칙 2 — "예시" 대신 "인터페이스"

예전엔 툴 설명에 사용 예시를 잔뜩 붙였습니다. 지금은 파라미터 이름과 설명을 잘 짓는 것 이 더 효과적입니다. 특히 선택지를 열거해주는 것(enum)이 예시 열 개보다 낫습니다.

[ 예시 방식 ]                      [ 인터페이스 방식 ]
"이렇게 쓰세요:                     depth: 'shallow' | 'medium' | 'deep'
  search(q, 'deep')                       ↳ 얼마나 깊게 탐색할지
  search(q, 'shallow')
  ... (예시 8개 더)"                한 줄인데 가능한 값이 전부 보임

예시는 "이런 경우엔?"이라는 질문을 남기지만, 열거는 남기지 않습니다.

규칙 3 — 다 넣지 말고, 필요할 때 꺼내게

점진적 공개(progressive disclosure) 는 이번 변화의 중심 개념입니다. 모든 정보를 처음부터 컨텍스트에 밀어 넣는 대신, 필요해진 순간에 로드 합니다.

여기서 자연스럽게 나오는 실무 규칙이 하나 있습니다. "거의 매번 필요한 것만 CLAUDE.md에 두고, 가끔 필요한 건 Skill로 빼라."

규칙 4 — 반복하지 마라

예전엔 중요한 지시를 시스템 프롬프트에도, 툴 설명에도, CLAUDE.md에도 적었습니다. 안전장치라고 생각했으니까요. 그런데 반복은 두 가지 문제를 만듭니다.

1. 토큰을 세 번 낸다 — 같은 문장을 세 곳에서 읽습니다.
2. 고칠 때 하나를 빼먹는다 → 그 순간 모순 이 생깁니다.

지금 권장은 "툴 설명에만 적어라" 입니다. 그 툴을 쓸 때 반드시 읽히는 자리니까요.

규칙 5 — CLAUDE.md는 메모장이 아니다

예전엔 # 단축키로 "이거 기억해"라고 CLAUDE.md에 적었습니다. 지금은 자동 메모리 가 맥락에 맞는 것을 알아서 저장합니다. 그래서 CLAUDE.md의 역할이 좁아졌습니다.

규칙 6 — 계획서보다 실행 가능한 것

"무엇을 만들지"를 마크다운 산문으로 적는 대신, 더 정확한 형식 으로 남기라는 이야기입니다.

• 테스트 스위트 → 통과/실패가 명확
• 코드로 쓴 명세(타입, 시그니처) → 해석의 여지가 적음
• 채점 기준(rubric) → 품질 판정 기준이 명시적
• HTML 아티팩트 → 화면을 말로 설명할 필요 없음

산문은 읽는 사람마다 다르게 해석되지만, 타입과 테스트는 그렇지 않습니다.

3. 그래서 어디에 무엇을 적나

이제 정리해봅시다. 컨텍스트를 구성하는 4개의 자리가 있고, 각자 역할이 다릅니다.

┌─ 시스템 프롬프트 ─── 제품 자체의 맥락. 사용자는 거의 안 건드림
│                      (커스텀 에이전트를 만든다면 여기가 핵심)
│
├─ CLAUDE.md ───────── 이 저장소의 "함정"만. 가볍게.
│                      길어지는 검증 절차는 Skill로 분리
│
├─ Skill ───────────── 팀의 의견·노하우. 관련 작업일 때만 로드
│                      길면 내부에서 또 점진적 공개
│
└─ 레퍼런스 ────────── @멘션으로 깊은 자료 연결
                       설명문보다 코드 기반 명세를 우선

CLAUDE.md 다이어트 체크리스트

제 블로그 저장소의 CLAUDE.md를 이 기준으로 다시 읽어보니, 지울 후보가 바로 보였습니다.

판단 기준은 한 문장으로 줄어듭니다. "이걸 안 적으면 AI가 틀리나?" 아니라면 지워도 됩니다.

자동으로 진단받기 — /doctor

직접 판단하기 부담스럽다면 도구가 있습니다. Claude Code의 /doctor(CLI로는 claude doctor)가 Skill·CLAUDE.md·시스템 프롬프트의 크기를 점검하고 적정선을 잡아줍니다. 앞선 글에서 다룬 자가치유 하네스가 "실수를 보고 규칙을 더한다"였다면, /doctor는 반대 방향 — 덜어내는 쪽 의 자동화입니다.

4. 오해하기 쉬운 지점

이 글의 메시지가 "하네스를 없애라" 로 읽히면 곤란합니다. 몇 가지를 명확히 해두겠습니다.

오해 1 — "그럼 CLAUDE.md 지워도 되나?"

아닙니다. 줄이라는 것이지 없애라는 것이 아닙니다. 저장소 고유의 함정은 모델이 아무리 좋아져도 알 수 없습니다. .nojekyll이 왜 필요한지는 파일을 다 읽어도 안 나옵니다.

오해 2 — "강제해야 하는 것도 판단에 맡기나?"

이건 지난 글에서도 짚었던 구분입니다. 판단에 맡길 것과 기계적으로 막을 것은 다릅니다.

"규칙을 줄여라"는 세 번째 줄에 대한 이야기가 아닙니다. 강제력은 원래부터 문서가 아니라 hook에서 나왔습니다.

오해 3 — "모든 모델에 해당되나?"

아닙니다. Anthropic이 삭제한 것은 Claude Opus 5, Fable 5 같은 상위 모델용 시스템 프롬프트입니다. 더 작은 모델을 쓴다면 명시적 지시가 여전히 유효합니다. 하네스는 모델에 맞춰 조정되는 것 이지, 한 번 쓰고 영원히 두는 것이 아닙니다.

5. 실제로 적용해보기

제 저장소에 적용한다면 순서는 이렇습니다.

① 모순 찾기      같은 주제를 두 곳에서 다르게 말하는 문장 쌍을 찾는다
                 → 발견하면 무조건 하나로 합친다 (최우선)
 
② 자명한 것 삭제  "파일을 열면 알 수 있는 사실"을 지운다
 
③ 가끔 쓰는 것 분리  배포·커밋·릴리스처럼 특정 순간에만 필요한 절차를
                     Skill로 옮긴다
 
④ 규칙 → 원리     "X 하지 마" 여러 줄을 "주변에 맞춰라" 한 줄로 바꾼다
 
⑤ 검증           평소 작업 몇 개를 돌려보고 품질이 유지되는지 본다
                 → 나빠지면 그 항목만 되돌린다

⑤가 중요합니다. 덜어내기도 검증이 필요합니다. 지난 글의 자가치유 하네스가 수정안을 채택하기 전에 정합성·본문 비용·트리거 정확도·일반화를 동시에 확인했던 것과 같은 이유입니다. 짧아졌는데 나빠졌다면 그건 개선이 아닙니다.

덜어냈는지 확인하는 질문

6. 정리 — 하네스는 어디로 가나

지난 두 글과 이어서 보면 흐름이 보입니다.

1·2단계는 하네스를 키우는 방향이었고, 3단계는 처음으로 반대 방향 입니다. 그리고 이 둘은 모순이 아니라 짝입니다. 더하기만 하는 시스템은 반드시 비대해지고, 비대해진 하네스는 모순을 낳기 때문 입니다. 자가치유가 규칙을 더한다면, /doctor류의 정리가 주기적으로 덜어내야 균형이 잡힙니다.

핵심 메시지는 하나입니다.

하네스의 목적은 "모델을 통제하는 것"이 아니라 "모델이 모르는 것만 알려주는 것"이다.

모델이 좋아질수록 "모델이 모르는 것"의 범위는 줄어듭니다. 그러면 하네스도 같이 줄어야 합니다. 늘어나기만 하는 하네스는, 사실 모델이 아니라 우리의 불안 을 담고 있는 것일지도 모릅니다.

참고 문서

• Anthropic, The New Rules of Context Engineering for Claude 5 Generation Models (2026)
• Anthropic, Effective Context Engineering for AI Agents (2025)
• Anthropic, Agent Skills (2025)
• 이전 글 — Frontend 하네스 엔지니어링 · 자가치유 하네스 엔지니어링