06. 설정·컨텍스트 관리

이 섹션부터 이어지는 원칙들은 주간 70시간 이상 코딩 에이전트를 사용하면서 얻은 경험에서 나왔어요. 밥 먹을 때, 씻을 때, 자다 일어나서, 회사에서 하루종일, 이동 중에, 화장실에서까지 — 그렇게 몸으로 검증한 패턴들이에요.

원칙 1: 1세션 = 1작업

세션이 길어질수록 관련 없는 컨텍스트가 뒤섞이고, Compaction이 중요한 내용을 날려요. 컨텍스트가 오염됐다 싶으면 새 세션을 여는 게 나아요.

/clear   # 또는 새 세션 시작

한 번 꼬인 컨텍스트는 수습하려 할수록 더 커져요. 얽힌 실타래를 풀려고 더 잡아당기면 매듭만 굵어져요. 일찍 리셋하는 게 빨라요.

컨텍스트 오염의 주요 원인 — 세션 내 중구난방 요청. 하나의 세션에서 "이것도 해줘, 저것도 해줘"를 섞으면, 서로 무관한 파일 읽기·실행 결과·대화 흐름이 전부 동적 레이어에 쌓여요. LLM 입장에서는 이 모든 정보를 고려하며 응답해야 하므로, 판단 품질이 점점 떨어져요. 트랜스포머 구조상 Attention이 컨텍스트 전체를 참조하기 때문에, 이는 "집중력 저하"에 그치지 않고 연산 비용과 세션 재개 지연으로도 이어져요. → 트랜스포머 추론의 두 단계: Prefill과 Decode

이 문제를 다루는 컨텍스트 관리용 슬래시 커맨드는 대부분의 코딩 에이전트가 제공해요. 아래는 Claude Code 사례예요.

/btw — 진행 중에 문득 떠오른 곁가지 질문을 처리할 때 써요. 메인 작업 흐름을 건드리지 않고 짧게 답변만 받을 수 있어요.

/branch — 현재까지의 컨텍스트를 공유하면서 다른 방향으로 탐색할 때 써요. 예를 들어, 같은 버그를 두 가지 접근 방식으로 각각 살펴보고 싶을 때 분기점에서 /branch를 치면 메인 컨텍스트를 오염시키지 않고 실험할 수 있어요.

컨텍스트 사용량 모니터링: 언제 리셋할지 직관으로 판단하면 너무 늦는 경우가 많아요. 에이전트 상태표시줄(statusline)을 설정하면 사용량을 수치로 실시간 확인할 수 있어요.

Claude Code 기준으로는 ~/.claude/settings.json에 statusLine 커맨드를 등록하면 돼요. 예시는 아래처럼 생겼어요.

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"CTX \\(.context.used_percentage)%\"'"
  }
}

위 예시는 개념 스케치예요. statusLine 커맨드가 stdin으로 받는 JSON 스키마(필드명)는 에이전트 버전마다 달라질 수 있으니, 정확한 필드는 공식 문서로 확인하고 적용하세요. 가장 안전한 방법은 자연어로 요청해 에이전트가 직접 스크립트를 작성하게 하는 거예요.

/statusline CTX 24K / 200K (12%) 형태로 보여줘

표시 예: CTX 12% → CTX 67% → CTX 89%

판단 기준:

~30% 이하: 여유
60% 이상: 작업 마무리 고려
80% 이상: Compaction 직전 — 새 세션 전환 적극 고려

(구체적인 Claude Code 설정 디테일은 Claude Code 3대 설정 축, Codex 쪽은 Codex 사용 가이드 참조.)

원칙 2: 의존성 경량화

에이전트가 실행 중 로드하는 모든 것 — Python 패키지, 파일, 도구 출력 — 이 동적 레이어에 쌓여요. 불필요하게 큰 출력을 파이프로 다 집어넣거나, 거대한 종속성을 통째로 읽히는 건 메모리 낭비예요.

pip3 의존성은 실제로 필요한 것만
파일 읽기는 필요한 부분만 지정해서
셸 출력은 필요한 필드만 grep해서 넘기기

컨텍스트에 들어오는 정보량을 줄이는 것이 곧 LLM이 집중할 수 있는 유효 공간을 늘리는 일이에요.

원칙 3: 메타 최적화에 먼저 투자하라

큰 프로젝트일수록 설정을 먼저 다듬는 게 ROI가 압도적으로 높아요.

시스템 프롬프트 파일(Claude Code의 CLAUDE.md, Codex의 AGENTS.md)에 규칙 한 줄 추가로 해결되는 문제를 프롬프트에서 매번 설명하고 있다면, 수십 번의 반복 비용을 지불하고 있는 거예요. 에이전트와 일하기 전에 "이 에이전트를 어떻게 세팅할 것인가"에 시간을 써보세요.

언제 적용할까요: 같은 지시·정정·교정을 두 번 이상 반복하고 있다면, 그건 곧 메타 최적화 후보예요. 같은 설명을 매 세션마다 다시 적고 있다면 더 강한 신호예요. 시스템 프롬프트 파일 규칙 한 줄이 수십 번의 반복 지시를 대체해요. 초반에 설정에 투자하는 시간이 이후 작업 전체의 품질과 속도를 결정해요.

언제 안 할까요: 일회성 작업, 또는 실험 단계라 규칙이 자주 바뀔 게 뻔한 시점에 메타 최적화에 시간을 쏟는 건 낭비예요. 규칙은 안정된 다음에 박아요.

원칙 4: 임시방편(Ad-hoc Patch)을 거부하라

에러가 났을 때 시스템 프롬프트 파일에 "만약 X 에러가 나면 무시해"를 추가하고 싶은 유혹이 와요. 하지 말아요.

땜빵 규칙이 누적되면 LLM이 모순된 지침 사이에서 충돌을 일으켜요
최악의 경우 환각(hallucination)을 유발해요
근본 원인을 찾아 고치세요 — 지침은 얇을수록 좋아요

비유로 풀면 — 일정한 신호등을 가린 임시 표지판과 같아요. "이 표지판은 무시하세요"가 늘어날수록 운전자(LLM)는 매 교차로에서 결정을 머뭇거려요. 땜빵은 빚이에요. 두꺼운 지침은 LLM이 어떤 규칙을 따라야 할지 충돌을 일으켜요.

원칙 5: 시스템 프롬프트 파일은 얇게 — 트리거로 지식을 지연 로드하라

시스템 프롬프트 파일(Claude Code의 CLAUDE.md, Codex의 AGENTS.md)은 매 세션 컨텍스트에 통째로 올라가요. 파일이 길어질수록 관련 없는 작업에도 항상 무거운 정적 레이어를 얹게 돼요.

해법은 트리거(trigger) 예요. 모든 지식을 시스템 프롬프트 파일에 직접 쓰는 대신, "이 상황이 오면 이 파일을 읽어라"는 조건부 참조 지시만 남겨요. 실제 내용은 별도 파일에 두고 필요한 순간에만 로드돼요.

비유로 풀면 — 시스템 프롬프트 파일은 사전이 아니라 목차예요. 두꺼운 사전을 통째로 들고 다닐 필요 없이, "어떤 단어가 어느 페이지에 있는지"만 적어두면 돼요. 필요한 페이지는 그때 펼쳐요.

트리거 예시 (Claude Code의 CLAUDE.md 또는 Codex의 AGENTS.md 안에 작성):

## 트리거 참조
- API 엔드포인트 작업 시: 반드시 `docs/api-conventions.md`를 먼저 읽어라
- DB 스키마 변경 전: `docs/db-migration-checklist.md` 참조 필수
- 테스트 추가·수정 시: `docs/testing-guide.md` 확인

이 방식이 동작하는 이유: LLM은 시스템 프롬프트 지침을 실제로 준수해요. "이 상황에서는 반드시 이걸 참조하라"는 문장은 해당 상황이 왔을 때 Read 도구 호출을 유발해요. 그 지식은 필요한 세션의 동적 레이어에만 들어오고, 무관한 세션에서는 전혀 로드되지 않아요.

슬림화 원칙:

시스템 프롬프트 파일에는 조건·트리거·파일 참조만 남기세요
절차나 규칙의 구체적 내용은 별도 파일(api-conventions.md, testing-guide.md 등)에 위임하세요
지식 파일도 짧고 집중적으로 — 불필요한 내용을 트리거 파일에 쏟아붓지 마세요

시스템 프롬프트 파일이 두꺼워질 것 같으면, 그 내용을 별도 파일로 빼고 트리거만 남기세요. 지침 파일이 얇을수록 LLM이 판단에 집중할 수 있는 실효 컨텍스트가 늘어나요.