Claude 5 모델을 위한 컨텍스트 엔지니어링 규칙

판단 능력이 향상된 Claude 모델을 효과적으로 사용하려면 프롬프트 한 문장을 다듬는 것만으로는 부족하다. 모델이 한 번의 추론에서 보게 될 시스템 지침, 프로젝트 파일, 도구, 메모리, 대화 기록과 실행 결과를 하나의 정보 환경으로 설계해야 한다.

핵심 원칙은 단순하다.

모든 행동을 미리 규정하기보다 명확한 목적, 안전 경계, 표현력 있는 인터페이스와 신뢰할 수 있는 참조 자료를 제공하고 세부 판단은 모델에 맡긴다.

이 글에서 Claude 5는 제공된 자료가 지칭하는 차세대 고성능 Claude 모델 환경을 뜻한다. 구체적인 제품 사양이나 출시 상태가 아니라, 판단 능력이 향상된 모델에 적용할 수 있는 컨텍스트 설계 원칙에 초점을 맞춘다.

프롬프트 엔지니어링과 컨텍스트 엔지니어링

프롬프트 엔지니어링

프롬프트 엔지니어링은 현재 요청을 어떻게 표현할지 설계하는 작업이다. 일반적으로 다음 항목을 다룬다.

• 작업 목표
• 수행 범위
• 제약 조건
• 출력 형식
• 성공 기준
• 필요한 예시

예를 들면 다음과 같다.

Next.js API Route에 결제 취소 기능을 구현한다.
기존 서비스 계층을 재사용하고 테스트를 추가한다.
공개 API 계약은 변경하지 말고 변경 이유를 설명한다.

컨텍스트 엔지니어링

컨텍스트 엔지니어링은 모델의 추론에 들어가는 전체 정보 집합을 선별하고 유지하는 작업이다. Claude Code와 같은 코딩 에이전트에서는 대략 다음 요소가 컨텍스트를 구성한다.

사용자의 현재 요청
+ 시스템 지침
+ CLAUDE.md와 프로젝트 지침
+ Skills
+ 자동 메모리
+ 코드·명세·테스트·문서
+ 도구 정의와 MCP 리소스
+ 대화 기록
+ 도구 실행 결과와 오류 로그

따라서 좋은 프롬프트도 오래된 메모리, 중복된 프로젝트 규칙 또는 방대한 로그와 함께 제공되면 효과가 약해질 수 있다. 반대로 짧은 요청도 관련 코드와 테스트, 명확한 도구가 함께 주어지면 충분히 정확하게 실행될 수 있다.

컨텍스트가 많을수록 항상 좋지 않은 이유

LLM의 컨텍스트 창이 커져도 작업에 사용할 수 있는 주의력은 무제한이 아니다. 관련성이 낮은 토큰이 늘어나면 다음 문제가 생길 수 있다.

1. 중요한 요구사항이 장황한 설명 속에 묻힌다.
2. 서로 다른 위치의 유사한 지침이 미묘하게 충돌한다.
3. 오래된 결정이나 실패한 시도가 현재 작업에 영향을 준다.
4. 예시가 정답처럼 작용해 다른 해결 경로를 제한한다.
5. 로그와 도구 출력이 코드, 명세, 테스트에 필요한 공간을 차지한다.
6. 모델이 실제 작업보다 지침의 우선순위를 해석하는 데 추론을 소비한다.

Anthropic는 긴 컨텍스트에서 정보의 활용 효율이 저하되는 현상을 설명하며, 에이전트가 필요한 정보를 적시에 검색하고 오래된 기록을 압축하도록 설계할 것을 권한다. 중요한 것은 최대 토큰 수를 채우는 것이 아니라 결과에 영향을 주는 고신호 토큰의 비율을 높이는 것이다.

시스템 프롬프트 축소 사례가 의미하는 것

제공된 Anthropic 사례에서는 Claude Code의 내부 지침을 검토한 뒤 시스템 프롬프트를 80% 이상 축소했다고 설명한다. 이 수치는 모든 애플리케이션의 프롬프트를 같은 비율로 줄여야 한다는 규칙이 아니다. 특정 시스템에서 중복되고 지나치게 세부적인 행동 지침을 정리한 사례로 이해해야 한다.

예를 들어 다음 지침이 한 요청에 동시에 들어갈 수 있다.

시스템 지침: 상황에 맞는 문서를 남긴다.
Skill 지침: 주석을 추가하지 않는다.
사용자 요청: 기존 버전처럼 작동하게 만든다.

각 문장은 개별적으로는 타당할 수 있지만 함께 놓이면 여러 해석 문제가 발생한다.

• 문서와 코드 주석은 같은 범주인가?
• 주석 금지는 예외 없는 규칙인가?
• 기존 버전의 동작에는 주석이나 문서 구조도 포함되는가?
• 현재 요청과 재사용 가능한 Skill 중 어느 쪽이 우선하는가?

이 경우 실패 원인은 모델의 코딩 능력만이 아니다. 사람이 구성한 정보 환경이 불필요한 모순을 포함하고 있다는 점도 원인이다.

여섯 가지 새로운 컨텍스트 설계 규칙

1. 세부 금지 목록을 맥락 기반 원칙으로 바꾼다

과거 모델의 반복적인 실수를 막기 위해 다음과 같은 규칙을 길게 나열하는 경우가 있었다.

• 주석을 작성하지 않는다.
• 여러 문단의 docstring을 만들지 않는다.
• 요청하지 않은 계획 문서를 생성하지 않는다.
• 중간 분석 파일을 저장하지 않는다.

이런 규칙은 특정 실패를 방지하지만 모든 상황에 적용되는 절대 원칙은 아니다. 복잡한 보안 검증이나 동시성 코드에는 설명이 필요할 수 있고, 자명한 CRUD 코드에는 주석이 오히려 소음을 만들 수 있다.

다음처럼 판단 기준을 제시하는 편이 낫다.

주변 코드와 같은 방식으로 읽히는 코드를 작성한다.
기존 파일의 이름 규칙, 관용 표현과 주석 밀도를 따른다.
설명 없이는 안전성이나 의도가 불분명한 로직에만 필요한 문서를 추가한다.

다만 모든 규칙을 약하게 바꾸어서는 안 된다. 다음 항목은 명시적인 제약이나 도구 수준의 통제로 유지해야 한다.

• 운영 환경 배포와 데이터 삭제 승인
• 개인정보와 기밀정보 처리 제한
• 인증·인가 검증
• 금전 거래의 멱등성과 감사 기록
• 데이터베이스 마이그레이션 정책
• 법률, 라이선스와 규제 준수
• 변경할 수 없는 공개 API 계약

2. 많은 예시보다 표현력 있는 도구를 설계한다

도구 설명에 정상·비정상 호출 사례를 계속 추가하면 컨텍스트가 커지고 모델이 예시의 표면 형태를 모방할 수 있다. 더 나은 방법은 도구 이름, 입력 필드와 상태 전이가 사용법을 드러내도록 만드는 것이다.

TodoWrite
목적: 현재 세션의 작업 목록 생성 및 갱신

status:
- pending
- in_progress
- completed

제약:
- 동시에 하나의 작업만 in_progress일 수 있음

좋은 에이전트 도구는 다음 특성을 갖는다.

• 이름만으로 행동과 대상이 드러난다.
• 필수 필드와 선택 필드가 구분된다.
• 열거형으로 허용 값을 제한한다.
• 읽기와 쓰기, 미리보기와 실행을 분리한다.
• 오류가 원인과 복구 방법을 구조적으로 반환한다.
• 위험한 작업은 확인 토큰이나 승인 단계를 요구한다.
• 결과가 지나치게 길면 요약과 페이지 탐색 기능을 제공한다.

예시는 인터페이스로 표현하기 어려운 예외나 모호한 입력을 설명할 때만 추가하는 것이 좋다.

3. 모든 정보를 처음부터 넣지 말고 점진적으로 공개한다

에이전트가 작업에 필요할 가능성이 있다는 이유만으로 저장소 전체, 모든 정책과 긴 로그를 처음부터 주입해서는 안 된다. 먼저 탐색에 필요한 최소 정보를 주고, 작업이 구체화될 때 관련 자료를 읽게 한다.

권장 흐름은 다음과 같다.

1. 목표, 성공 기준과 안전 경계를 제공한다.
2. 저장소 구조나 검색 도구를 통해 관련 위치를 찾는다.
3. 필요한 파일과 명세만 읽는다.
4. 구현 후 관련 테스트와 정적 분석을 실행한다.
5. 실패한 경우 해당 오류와 주변 코드만 추가로 가져온다.
6. 완료 후 오래된 로그와 중간 추론을 압축하거나 제거한다.

점진적 공개는 정보를 숨기는 것이 아니다. 필요한 정보를 모델이 발견할 수 있도록 검색 경로와 명확한 파일 구조를 제공하는 방식이다.

4. 중복 지침을 제거하고 권위 있는 위치를 정한다

같은 규칙을 시스템 프롬프트, CLAUDE.md, Skill과 도구 설명에 복제하면 시간이 지나면서 문구가 달라질 수 있다. 지침의 종류별로 하나의 권위 있는 저장 위치를 정해야 한다.

중복이 불가피하다면 내용을 복사하지 말고 권위 있는 위치를 가리키거나 자동 생성하는 편이 안전하다.

5. CLAUDE.md와 자동 메모리의 역할을 분리한다

CLAUDE.md는 프로젝트 구성원이 검토하고 버전 관리할 수 있는 지속적인 지침에 적합하다.

• 표준 빌드와 테스트 명령
• 저장소 구조의 핵심 설명
• 팀이 합의한 변경 금지 영역
• 프로젝트 고유의 검증 절차
• 일반적인 도구로 추론하기 어려운 규칙

반면 다음 정보는 자동 메모리나 세션 상태에 더 적합하다.

• 반복 작업에서 발견한 개인화된 선호
• 최근 작업에서 유용했던 탐색 경로
• 일시적인 개발 환경 특성
• 현재 세션의 진행 상황

자동 메모리는 항상 정확하거나 영구적이라고 가정해서는 안 된다. 오래된 항목을 수정하거나 제거할 수 있어야 하며, 보안 정책과 공개 계약의 유일한 저장소로 사용하면 안 된다.

6. 설명 문서보다 실행 가능한 참조 자료를 우선한다

자연어 명세는 의도를 설명하는 데 유용하지만 실제 동작을 완전히 표현하지 못할 수 있다. 가능하면 다음 자료를 함께 제공한다.

• 현재 코드와 유사한 기존 구현
• 단위 테스트와 통합 테스트
• API 스키마와 타입 정의
• 실제 HTML 또는 디자인 산출물
• 데이터베이스 마이그레이션 파일
• 입력·출력 예제 데이터
• 평가표와 자동 채점 기준

참조 자료 사이에도 충돌이 생길 수 있으므로 우선순위를 명시해야 한다. 예를 들어 계약 테스트가 공개 API의 권위 있는 기준이고, README는 설명 자료라고 정할 수 있다.

실무용 컨텍스트 구성 템플릿

다음 구조는 코딩 작업에 필요한 정보를 간결하게 정리하는 예시다.

목표
- 결제 취소 API를 추가한다.

성공 기준
- 기존 결제 서비스 계층을 재사용한다.
- 중복 요청에도 한 번만 취소된다.
- 관련 계약 테스트가 통과한다.

강한 제약
- 공개 응답 스키마를 변경하지 않는다.
- 운영 데이터에 접근하지 않는다.

참조 자료
- src/payments/capture.ts
- tests/contracts/payment-cancel.test.ts
- openapi/payments.yaml

판단 원칙
- 주변 결제 코드의 오류 처리와 이름 규칙을 따른다.
- 안전하지 않은 가정이 있으면 구현 전에 질문한다.

검증
- 대상 단위 테스트
- 계약 테스트
- 타입 검사

이 형식은 모든 상황을 미리 나열하지 않는다. 대신 목표, 성공 조건, 변하지 않는 경계, 권위 있는 자료와 검증 방법을 분리한다.

기존 컨텍스트를 정리하는 절차

1단계: 모든 지침의 출처를 목록화한다

시스템 프롬프트, CLAUDE.md, Skills, 자동 메모리, 도구 설명과 CI 설정을 함께 확인한다. 한 문서만 살펴보면 실제 충돌을 발견하기 어렵다.

2단계: 각 지침에 분류표를 붙인다

• 안전 또는 법률상 필수
• 제품 계약상 필수
• 팀의 지속적인 관례
• 특정 도구에만 필요한 설명
• 과거 모델의 실수를 막기 위한 임시 규칙
• 현재는 근거가 불분명한 규칙

3단계: 중복과 충돌을 찾는다

동일한 행동을 다르게 표현한 문장을 묶는다. 특히 항상, 절대, 반드시, 하지 마라 같은 표현을 우선 검토한다.

4단계: 규칙을 테스트나 권한으로 옮긴다

자연어 경고보다 자동 검증이 확실한 항목은 다음 계층으로 이동한다.

• 테스트와 린터
• 타입 시스템과 스키마
• 최소 권한 도구
• 승인 절차
• 샌드박스
• CI 정책

5단계: 실제 작업으로 평가한다

프롬프트 길이만 측정해서는 안 된다. 대표 작업 집합에서 다음 지표를 비교해야 한다.

• 성공률과 테스트 통과율
• 불필요한 파일 변경 수
• 사용자 수정 횟수
• 도구 호출 실패율
• 완료까지 걸린 시간과 토큰
• 안전 정책 위반 여부

6단계: 실패 원인만 최소한으로 보완한다

실패가 발생했다고 곧바로 새 금지 규칙을 추가하지 않는다. 원인이 모호한 목표인지, 부족한 참조 자료인지, 잘못된 도구 스키마인지 먼저 구분한다.

삭제하면 안 되는 지침

간결화는 무조건적인 삭제가 아니다. 다음 질문 중 하나라도 예라면 지침을 유지하거나 더 강한 통제로 옮겨야 한다.

• 위반 시 데이터 손실이나 금전 피해가 발생하는가?
• 법률, 개인정보 또는 라이선스 의무와 관련되는가?
• 모델이 코드만 보고는 알 수 없는 조직 정책인가?
• 공개 API나 데이터 형식의 호환성을 결정하는가?
• 작업 실행 전에 사람의 승인이 필요한가?
• 자동 테스트만으로 위반을 완전히 탐지하기 어려운가?

흔한 실패 패턴

모든 실패 뒤에 새 규칙 추가

한 번의 오류를 일반화해 영구 규칙으로 만들면 예외와 충돌이 누적된다. 먼저 평가 사례를 추가하고 반복되는 실패인지 확인해야 한다.

긴 예시를 사실상 템플릿으로 사용

예시가 너무 구체적이면 모델이 현재 코드베이스보다 예시를 우선할 수 있다. 예시는 원칙을 설명하는 최소 크기로 제한한다.

전체 로그를 그대로 보존

도구 출력과 빌드 로그는 빠르게 컨텍스트를 차지한다. 실패 원인, 관련 스택과 변경된 상태만 구조적으로 남기는 것이 좋다.

자동 메모리를 정책 저장소로 사용

자동 메모리는 편리하지만 검토·배포·감사 체계가 약할 수 있다. 조직의 강제 정책은 버전 관리되는 지침이나 권한 계층에 보관해야 한다.

컨텍스트 축소를 단순 토큰 절감으로 평가

짧은 컨텍스트가 항상 좋은 것은 아니다. 필요한 테스트, 안전 규칙 또는 명세를 제거하면 결과가 악화된다. 목표는 최소 토큰이 아니라 최소한의 고신호 토큰이다.

최종 점검표

• 현재 요청의 목표와 성공 기준이 분리되어 있는가?
• 안전 규칙과 스타일 선호가 구분되어 있는가?
• 같은 지침이 여러 위치에 복제되어 있지 않은가?
• 도구 스키마가 긴 예시 없이도 사용법을 설명하는가?
• 관련 파일을 필요할 때 검색할 수 있는가?
• 오래된 메모리와 실행 로그를 제거할 방법이 있는가?
• 자연어 규칙을 테스트나 권한으로 강제할 수 있는가?
• 참조 자료 사이의 우선순위가 명확한가?
• 지침 변경 전후를 비교할 평가 작업이 있는가?

결론

고성능 Claude 모델을 위한 컨텍스트 엔지니어링은 지침을 무조건 줄이는 기술이 아니다. 모델이 현재 작업을 판단하는 데 필요한 목적, 안전 경계와 근거를 선명하게 만들고, 관련 없는 정보와 충돌하는 규칙을 제거하는 정보 설계다.

가장 실용적인 원칙은 다음과 같이 요약할 수 있다.

보안과 계약은 강하게 강제하고, 스타일은 맥락에 맡기며, 정보는 필요한 시점에 제공하고, 결과는 실행 가능한 테스트로 검증한다.