Claude Code 프롬프트를 가볍게 만드는 6가지 맥락 설계 규칙

Claude Code를 오래 사용할수록 프로젝트의 CLAUDE.md가 비대해지기 쉽습니다. 코딩 규칙, 테스트 방법, 커밋 형식, UI 가이드, 문서 작성법을 한 파일에 계속 추가하다 보면 매번 모든 내용이 대화 맥락에 들어갑니다. 작업에 필요하지 않은 지침까지 읽히면서 토큰을 소비하고, 정작 중요한 요구사항이 묻히는 문제도 생깁니다.

최근 소개된 맥락 설계 방식의 핵심은 프롬프트를 많이 쓰는 것이 아니라 필요한 정보를 적절한 시점에 연결하는 데 있습니다. 아래는 6가지 변경 방향을 Claude Code 프로젝트에 적용할 때 어떤 식으로 해석하면 되는지에 초점을 맞춘 내용입니다. 다만 Opus 5, Fable 5 같은 모델명이나 /calibrate와 같은 커스텀 스킬은 실제 제공 여부와 동작이 환경에 따라 달라질 수 있으므로, 공식 문서와 현재 설치 버전을 함께 확인해야 합니다.

기존 방식	바꾸는 방향
실수마다 금지문 추가	저장소 맥락을 읽고 같은 수준으로 맞추게 함
완성 예시를 여러 개 제시	디자인 시스템·인터페이스 규격만 제공
CLAUDE.md에 모든 규칙	공통 원칙 + 조건별 문서 라우팅
같은 지시를 여러 곳에 반복	전역·도구·업무 문서로 책임 분리
세션에서 배운 것이 사라짐	후보 규칙을 추출해 사람이 승인
모든 참조물을 텍스트로	시각 규격은 HTML, 개발 규칙은 텍스트

모든 실수를 규칙으로 막으려 하지 않기

예전에는 에이전트가 코드를 과하게 설명하거나 불필요한 주석을 넣지 않도록 강한 금지문을 넣는 경우가 많았습니다. 예를 들어 “주석을 절대 작성하지 마라”, “독스트링은 한 줄만 사용하라” 같은 문장입니다. 특정 출력 문제를 빠르게 억제하는 데는 효과가 있지만, 프로젝트의 기존 스타일과 예외 상황까지 함께 막아 버릴 수 있습니다.

대신 모델이 저장소의 맥락을 읽고 판단하도록 지시하는 편이 낫습니다. “기존 코드의 네이밍, 주석 밀도, 오류 처리 방식을 파악한 뒤 같은 수준으로 작성하라”는 식입니다. 이 방식은 규칙을 무조건 없애자는 뜻이 아닙니다. 보안상 반드시 지켜야 하는 조건, 데이터베이스 마이그레이션 순서, 실행하면 안 되는 명령처럼 실패 비용이 큰 항목은 여전히 명시해야 합니다. 표현 방식처럼 모델이 코드에서 충분히 추론할 수 있는 부분만 자율에 맡기는 것이 기준입니다.

예시를 쌓기보다 규격을 분리하기

프롬프트에 완성된 문장이나 화면 예시를 여러 개 넣는 few-shot 방식은 모델의 출력 스타일을 안정시키는 데 유용합니다. 하지만 예시가 많아지면 새로운 요구사항에도 기존 패턴을 반복하는 문제가 생깁니다. 특히 UI 작업에서는 예시 화면과 조금 다른 정보 구조가 필요해도 모델이 기존 배치를 그대로 따라갈 수 있습니다.

이때는 구체적인 결과물 예시 대신 디자인 시스템이나 인터페이스 규격을 제공하는 편이 낫습니다. 색상 팔레트, 폰트, 간격, 버튼 상태, 접근성 기준을 brandbook.html 같은 파일에 정의하고, 작업 목적에 맞는 레이아웃은 모델이 선택하게 하는 방식입니다.

예를 들어 다음처럼 역할을 나눌 수 있습니다.

출력 시 docs/brandbook.html의 색상과 폰트 규칙을 준수한다.
레이아웃은 현재 화면의 정보 우선순위와 사용 목적에 맞게 결정한다.

이렇게 하면 브랜드의 고정 요소와 작업마다 달라지는 표현을 분리할 수 있습니다. 다만 픽셀 단위로 동일한 결과가 필요하거나 이미 검증된 컴포넌트를 그대로 재사용해야 하는 작업이라면 예시와 컴포넌트 API를 함께 제시하는 편이 더 안전합니다.

CLAUDE.md를 지침서가 아닌 라우터로 바꾸기

가장 큰 변화는 CLAUDE.md의 역할입니다. 이 파일에 모든 업무 규칙을 넣는 대신, 프로젝트 전체에 공통으로 적용되는 최소한의 원칙과 관련 문서의 위치만 남깁니다. 세부 지침은 작업 종류별 파일로 이동합니다. 이를 점진적 노출(Progressive Disclosure)이라고 볼 수 있습니다.

구조는 다음처럼 단순하게 시작할 수 있습니다.

# CLAUDE.md
- 개발 작업: docs/dev_router.md
- UI 및 브랜드 규칙: docs/brandbook.html
- 연구·논문 작성: docs/research_guide.md
- 변경 전 테스트 명령과 금지된 작업은 이 파일의 공통 규칙을 따른다.

핵심은 경로만 적는 데서 끝나지 않는다는 점입니다. “프런트엔드 작업이면 docs/brandbook.html을 먼저 확인하고, 데이터베이스 변경이면 docs/dev_router.md의 마이그레이션 절차를 적용하라”처럼 어떤 조건에서 어떤 문서를 읽어야 하는지도 밝혀야 합니다. 그렇지 않으면 라우터가 단순한 문서 목록으로 남고, 에이전트가 필요한 파일을 놓칠 수 있습니다.

문서를 나눌 때는 팀이 실제로 구분해 사용하는 업무 단위를 기준으로 삼아야 합니다. 너무 잘게 쪼개면 파일을 찾는 비용이 늘고, 서로 충돌하는 규칙이 생깁니다. 반대로 한 파일에 다시 모든 내용을 넣으면 원래의 문제가 반복됩니다.

중복 지시를 줄여 토큰과 우선순위 관리하기

동일한 지침이 시스템 프롬프트, CLAUDE.md, 커스텀 스킬, 툴 설명에 반복되는 경우가 있습니다. 예를 들어 “테스트를 실행하라”는 말이 네 곳에 있으면 토큰만 늘어나는 것이 아니라, 서로 표현이 다른 지침이 충돌할 가능성도 커집니다.

규칙을 배치할 때는 한 가지 질문이 유용합니다. 이 지침은 모든 작업에 필요한가, 특정 도구를 사용할 때만 필요한가, 특정 업무 문서를 읽었을 때만 필요한가? 전역 규칙은 짧게 유지하고, 도구 사용법은 툴 설명에, 업무별 조건은 해당 문서에 두는 식으로 책임을 나누면 관리가 쉬워집니다.

삭제 전에는 실제로 어느 위치에서 필요한 규칙인지 확인해야 합니다. 중복처럼 보여도 보안이나 권한 제한처럼 여러 경로에서 반드시 적용되어야 하는 조건은 한 곳만 남기면 안 됩니다.

세션에서 나온 수정 사항을 다음 작업에 반영하기

한 세션에서 반복적으로 설명한 규칙이나 모델이 수정한 실수는 다음 작업에도 의미가 있을 수 있습니다. 대화가 끝날 때 /calibrate 같은 커스텀 스킬을 실행해 이런 내용을 메모리나 프로젝트 문서에 반영하는 방식이 있습니다.

다만 자동 축적은 신중해야 합니다. 일회성 요구사항, 특정 브랜치에서만 필요한 임시 우회책, 잘못된 모델의 추측까지 영구 규칙으로 저장하면 프로젝트가 빠르게 오염됩니다. 자동화한다면 다음 항목을 구분하는 검토 단계가 필요합니다.

• 여러 작업에서 반복된 규칙인지
• 특정 파일이나 브랜치에만 해당하는지
• 기존 지침과 충돌하지 않는지
• 사람이 확인한 뒤 저장할 것인지

따라서 /calibrate는 무조건 파일을 수정하는 명령보다, 세션에서 후보 규칙을 추출하고 사람이 승인할 내용을 보여주는 스킬로 설계하는 편이 안전합니다. 실제로 해당 명령이 기본 제공되는지는 Claude Code 버전에 따라 확인해야 합니다.

텍스트 문서와 HTML 참조물을 구분해 사용하기

개발 규칙은 마크다운이나 일반 텍스트가 적합하지만, 시각적 결과를 설명하는 자료는 HTML이 더 직관적일 수 있습니다. brandbook.html에 실제 색상 견본, 버튼 상태, 카드 간격, 타이포그래피 계층을 함께 표시하면 사람과 에이전트가 같은 기준을 확인하기 쉽습니다.

HTML을 사용한다고 해서 모델이 화면을 완벽히 이해하거나 브라우저 렌더링 결과를 항상 동일하게 재현하는 것은 아닙니다. 파일 경로를 명확히 지정하고, 필요한 경우 스크린샷·컴포넌트 코드·접근성 조건을 함께 제공해야 합니다. 색상 이름만 적는 것보다 CSS 변수와 사용 맥락을 함께 정의하는 것도 도움이 됩니다.

실제로 적용할 때의 순서

기존 CLAUDE.md를 한 번에 삭제하기보다 다음 순서로 옮기는 편이 문제를 추적하기 쉽습니다. 먼저 모든 규칙을 공통 규칙, 개발 규칙, 디자인 규칙, 문서 규칙으로 분류합니다. 그다음 테스트 명령, 보안 조건, 저장소 구조처럼 모든 작업에 필요한 내용만 메인 파일에 남깁니다. 나머지는 업무별 문서로 옮기고, 각 문서가 언제 호출되는지 라우팅 문장을 추가합니다.

이후 같은 작업을 짧은 프롬프트로 반복해 보면서 누락되는 규칙이 있는지 확인합니다. 코드 스타일처럼 모델이 기존 파일에서 충분히 파악할 수 있는 지침은 줄이고, 모델이 파일만 보고 알기 어려운 배포 절차나 금지 조건은 유지해야 합니다. 프롬프트를 줄이는 목적은 지시를 약하게 만드는 것이 아니라, 중요한 지시가 불필요한 설명 속에 묻히지 않게 만드는 데 있습니다.

특히 문서 라우팅은 편리하지만 컨텍스트를 자동으로 무한히 줄여 주는 기능은 아닙니다. 에이전트가 참조 파일을 실제로 읽었는지, 오래된 규칙을 사용하지 않았는지, 문서 간 충돌이 없는지 확인하는 테스트가 필요합니다. 현재 사용 중인 Claude Code의 스킬·훅·메모리 기능과 위에서 정리한 구성 요소가 같은지 확인한 뒤 단계적으로 적용하는 것이 안전합니다.