좋은 컨텍스트 설계

어떻게 효과적으로 설계하고 전달할 것인가

컨텍스트의 네 가지 차원을 이해했다면, 다음 질문은 '어떻게 효과적으로 설계하고 전달할 것인가'이다. 좋은 컨텍스트 설계는 필요한 정보를 적절한 시점에, 적절한 양으로, 적절한 형태로 AI에게 전달하는 기술이다.

Progressive Disclosure 원칙

UI/UX 디자인에서 Progressive Disclosure는 사용자에게 처음부터 모든 정보를 보여주는 대신, 필요한 시점에 점진적으로 정보를 공개하는 원칙이다. 이 원칙은 AI에게 컨텍스트를 제공할 때도 그대로 적용된다.

AI의 컨텍스트 윈도우(Context Window)는 유한하다. 2025년 현재, 최신 모델들이 10만~20만 토큰의 컨텍스트를 지원하지만, 그렇다고 모든 정보를 한꺼번에 쏟아붓는 것은 효과적이지 않다. 정보가 너무 많으면 AI가 핵심을 놓칠 수 있고, 관련 없는 정보에 의해 결과가 왜곡될 수 있다.

Progressive Disclosure의 3단계 적용

1단계: 프로젝트 헌법 (항상 제공). 프로젝트의 정체성을 정의하는 핵심 문서다. CLAUDE.md나 README에 해당하며, 프로젝트의 목적, 기술 스택, 핵심 원칙 등을 담는다. 이 정보는 모든 대화에서 기본으로 제공된다.

2단계: 작업별 컨텍스트 (필요시 제공). 현재 작업과 직접 관련된 정보다. 예를 들어, UI 작업을 할 때는 Golden Sample 코드를, API 개발을 할 때는 API 스펙 문서를 제공한다. 이 정보는 작업 종류에 따라 달라진다.

3단계: 즉석 컨텍스트 (상황 발생 시 제공). 에러 메시지, 사용자 피드백, 새로운 요구사항 변경 등 실시간으로 발생하는 정보다. 이것은 대화 중에 필요에 따라 추가된다.

컨텍스트 계층 구조

컨텍스트를 효과적으로 관리하려면 정보의 계층 구조를 명확히 정의해야 한다. 필자가 사용하는 컨텍스트 계층은 피라미드 형태로 구성된다.

최상위: 불변 원칙(Immutable Principles). 프로젝트 전체에 걸쳐 변하지 않는 핵심 원칙이다. 예를 들어, '모든 API는 REST 규약을 따른다', '사용자 데이터는 암호화해서 저장한다', '한국어 UI를 기본으로 한다' 등이다. 이 원칙은 CLAUDE.md의 첫 번째 섹션에 명시한다.

중간층: 구조적 결정(Architectural Decisions). 프로젝트 초기에 내려지고 쉽게 바뀌지 않는 결정들이다. 3-Layer 아키텍처 사용, 데이터베이스 선택(PostgreSQL vs SQLite), 프론트엔드 프레임워크 선택(React vs Streamlit) 등이 해당한다. 이 정보는 README나 아키텍처 문서에 기록한다.

하위층: 구현 세부사항(Implementation Details). 일상적인 개발 과정에서 변경될 수 있는 세부사항이다. 특정 함수의 시그니처, UI 컴포넌트의 스타일, 에러 메시지 문구 등이 해당한다. 이 정보는 코드 자체와 인라인 주석으로 관리한다.

이 계층 구조의 핵심은 상위 계층이 하위 계층을 제약한다는 것이다. 불변 원칙에 '모든 코드에 한국어 주석을 작성한다'가 있으면, AI는 모든 코드 생성에서 이 원칙을 따른다. 구조적 결정에 'React + TypeScript'가 있으면, AI는 Vue.js 코드를 생성하지 않는다. 이것이 일관성을 보장하는 메커니즘이다.

메모리 관리 전략

AI와의 장기 프로젝트에서 가장 현실적인 도전은 메모리 관리다. AI의 컨텍스트 윈도우는 무한하지 않으며, 대화가 길어지면 초기에 제공한 정보가 '밀려나는' 현상이 발생한다. 이를 관리하기 위한 세 가지 전략을 소개한다.

전략 1: 앵커링(Anchoring). 가장 중요한 정보를 대화의 시작과 끝에 배치한다. AI 모델은 입력의 시작 부분과 끝 부분에 더 강한 주의(Attention)를 기울이는 경향이 있다(이를 'Primacy-Recency Effect'라 한다). CLAUDE.md가 항상 컨텍스트의 시작 부분에 로드되는 것은 이 원리를 활용한 것이다.

전략 2: 주기적 요약(Periodic Summarization). 긴 대화 세션에서는 중간중간 현재까지의 진행 상황을 요약하여 AI에게 제공한다. '지금까지 우리는 A를 완료했고, B에서 X 이슈가 있었으며, 현재 C를 진행 중이다'와 같은 요약은 AI가 전체 맥락을 유지하는 데 도움이 된다.

전략 3: 외부 메모리 활용. 대화 내부의 메모리에만 의존하지 않고, 파일 시스템을 외부 메모리로 활용한다. 중요한 결정 사항을 별도 파일에 기록하고, 필요할 때 AI에게 해당 파일을 참조하게 한다. Claude Code가 CLAUDE.md를 자동으로 읽는 것이 이 전략의 대표적인 예다.

컨텍스트 재사용 패턴

매 프로젝트, 매 대화에서 컨텍스트를 처음부터 구성하는 것은 비효율적이다. 경험이 쌓이면 재사용 가능한 컨텍스트 패턴이 만들어진다. 필자가 프로젝트들에서 축적한 주요 재사용 패턴을 소개한다.

패턴 1: 골든 샘플(Golden Sample) 패턴. 앞서 언급한 대로, 검증된 코드를 참고 자료로 제공하여 AI가 '모방'하게 하는 패턴이다. LayoutMaster에서 시작하여 필자의 거의 모든 프로젝트에서 활용하고 있다. 새 프로젝트를 시작할 때, 이전 프로젝트의 유사한 코드를 Golden Sample로 제공하면 프로젝트 시작 속도가 크게 빨라진다.

패턴 2: 프롬프트 템플릿(Prompt Template) 패턴. 반복되는 작업 유형에 대해 표준화된 프롬프트 템플릿을 만들어두는 패턴이다. 예를 들어, 'API 엔드포인트 추가' 작업에 대해 '어떤 엔드포인트인지, 입력/출력 형식, 인증 방식, 에러 처리 규칙'을 포함하는 템플릿을 미리 만들어두면, 매번 이 정보를 처음부터 작성할 필요가 없다.

패턴 3: 워크플로우 계획서(Workflow Plan) 패턴. 서울시 야경명소 프로젝트에서 사용한 4단계 워크플로우처럼, 프로젝트의 전체 진행 계획을 문서화하여 AI에게 제공하는 패턴이다. AI가 현재 작업이 전체 프로젝트에서 어떤 위치에 있는지를 이해하면, 더 맥락에 맞는 코드를 생성한다.

패턴 4: 에러 카탈로그(Error Catalog) 패턴. 프로젝트에서 자주 발생하는 에러와 해결 방법을 카탈로그로 정리해두는 패턴이다. AI에게 '이 에러가 발생했는데, 우리 프로젝트에서 이 에러는 보통 X가 원인이고 Y로 해결한다'는 정보를 제공하면, 디버깅 속도가 크게 빨라진다.

컨텍스트가 코드의 품질을 결정한다

이 장에서 우리는 프롬프트 엔지니어링을 넘어선 컨텍스트 엔지니어링의 세계를 탐구했다. 핵심 내용을 정리하면 다음과 같다.

프롬프트에서 컨텍스트로. 개별 질문의 품질(프롬프트 엔지니어링)보다, AI에게 제공하는 전체 맥락의 설계와 관리(컨텍스트 엔지니어링)가 프로젝트 수준의 AI 협업에서 더 중요하다. 이는 단발성 질문에서 지속적 협업으로의 전환에 따른 필연적 진화다.

4차원 프레임워크. 효과적인 컨텍스트는 Domain(무엇), Technical(어떻게), Project(언제/어디), Team(누가/왜)의 네 가지 차원으로 구성된다. 이 네 차원이 합쳐져야 AI가 완전한 그림을 그릴 수 있다.

Progressive Disclosure. 모든 정보를 한꺼번에 쏟아붓지 않고, 프로젝트 헌법(항상) → 작업별 컨텍스트(필요시) → 즉석 컨텍스트(상황 발생 시)의 3단계로 점진적으로 공개한다.

프로젝트 헌법. CLAUDE.md와 README는 프로젝트의 '헌법'이다. 모든 AI 생성 코드가 준수해야 하는 최고 규범으로서, 일관성과 품질을 보장하는 핵심 도구다.

재사용과 진화. 컨텍스트는 프로젝트를 거듭하며 축적되고 재사용된다. Golden Sample, Prompt Template, Workflow Plan, Error Catalog 등의 패턴을 통해 컨텍스트 자산이 쌓이고, 프로젝트 시작 속도가 점점 빨라진다.