에이전트가 규칙을 어기면 문서를 고칩니다. 문단을 하나 더 붙이고, 예외를 적고, 굵은 글씨를 씁니다. 그렇게 몇 번 반복하면 규칙 문서가 400 줄이 됩니다.

그리고 규칙은 더 안 지켜집니다.

원인은 단순합니다. 에이전트가 한 번에 실제로 붙들고 있는 양에는 한계가 있습니다. 그 안에서 규칙 문서, 읽은 파일들, 지금까지의 작업 내역, 도구 출력이 같은 자리를 나눠 씁니다. 문서를 길게 쓰는 건 규칙을 강화하는 게 아니라 다른 것들의 몫을 뺏는 것입니다.

1. 컨텍스트는 저장소가 아니라 예산이다

컨텍스트를 "정보를 넣어두는 공간"으로 생각하면 더 많이 넣는 게 항상 이득처럼 보입니다. 예산으로 보면 판단이 달라집니다.

한 번의 작업에서 자리를 나눠 쓰는 것들: 규칙·컨벤션 문서 읽어들인 소스 파일 지금까지 한 일 (대화·도구 호출 내역) 빌드 출력, 에러 메시지 지금 쓰고 있는 결과물

여기서 규칙 문서가 커지면 남은 넷 중 무언가가 줄어듭니다. 대개 줄어드는 건 "지금까지 한 일"입니다. 그런데 무인으로 긴 작업을 돌릴 때 가장 필요한 게 정확히 그것입니다.

문서를 늘리는 결정은 항상 무언가를 줄이는 결정입니다.

무엇이 줄어드는지 안 보일 뿐입니다. 그래서 규칙 문서는 계속 커집니다.

이 저장소를 읽는 데 드는 실제 비용

"안 보인다"는 걸 보이게 하려고 파일별로 값을 매겨봤습니다. 토큰 수는 토크나이저에 따라 달라지므로 정확한 값이 아니라 자릿수를 보기 위한 어림값입니다.

파일 크기 대략 토큰 언제 실리나 ───────────────────────────────────────────────────────────── CLAUDE.md (규칙 문서) 10.0KB ~6,000 항상 eleventy.config.mjs 4.5KB ~1,500 빌드를 고칠 때 posts.css 5.5KB ~1,500 스타일을 볼 때 layouts/post.njk 1.5KB ~500 레이아웃을 고칠 때 partials/head.njk 2.0KB ~700 메타를 고칠 때 vercel.json 1.5KB ~500 경로를 옮길 때 _data/staticPages.js 0.9KB ~300 페이지를 추가할 때 ───────────────────────────────────────────────────────────── 글 한 편 (ko, 보강 후) ~16KB ~9,000 그 글을 고칠 때 .content-queue.md 19.6KB ~11,000 회차 상태를 볼 때

첫 줄만 항상입니다. 나머지는 전부 조건부입니다. 그런데 규칙 문서 한 줄을 늘릴 때마다 그 비용은 모든 작업에 붙습니다 — 스타일만 만지는 작업에도, 리다이렉트만 고치는 작업에도요.

맨 아래 두 줄이 특히 눈에 띕니다. 글 한 편이 규칙 문서 하나보다 비쌉니다. 그래서 "글 몇 편을 한 번에 볼 수 있나"가 사실상의 작업 단위가 됩니다. 이 회차에서 한 번에 한 세트(ko+en)씩만 손대는 것도 그래서입니다.

2. 항상 읽히는 것과 필요할 때 읽는 것

이 저장소의 규칙 문서는 그래서 두 종류의 내용을 명확히 가릅니다.

항상 읽혀야 하는 것 — 모르면 첫 커밋부터 틀리는 것 ko/en 은 반드시 쌍으로 만든다 두 파일의 date 는 같아야 한다 본문은 마크다운이 아니라 HTML 이다 글 전용 스타일은 posts.css 를 쓴다 필요할 때 읽으면 되는 것 — 파일을 열면 나오는 것 front matter 필드 각각의 의미 레이아웃이 무엇을 자동으로 만드는지 리다이렉트 규칙의 전체 목록

가르는 기준은 "이걸 모른 채로 작업을 시작하면 되돌릴 수 없는가" 입니다.

ko 만 만들고 en 을 안 만들면 작업 방식 자체가 틀립니다. 나중에 알아도 이미 쓴 글 여덟 편을 다시 봐야 합니다. 반면 front matter 필드 하나의 의미는 기존 글을 열어보면 그 자리에서 알 수 있습니다. 미리 외우고 있을 이유가 없습니다.

3. 설명 열 줄보다 예시 한 개가 싸다

이 저장소의 새 글 작성 규칙은 이렇게 시작합니다.

기존 글을 복사해 front matter 를 채운다.

한 줄입니다. 이 한 줄이 필드 표 전체를 설명하는 것보다 정확합니다. 실제 파일에는 필드의 순서, 따옴표 처리, 날짜 형식, 본문에서 쓰는 클래스가 전부 함께 들어 있기 때문입니다. 설명으로 옮기면 반드시 무언가 빠집니다.

그리고 예시는 필요할 때만 자리를 차지합니다. 규칙 문서에 필드 표를 통째로 넣으면 글을 안 쓰는 작업에서도 계속 실려 다닙니다. "기존 글을 복사하라"는 지시만 항상 실리고 내용은 필요할 때 실립니다.

4. 상태는 대화가 아니라 저장소에 둔다

가장 비싼 것은 "지금까지 무엇을 했는가" 입니다. 이건 작업이 길어질수록 계속 늘어납니다.

그래서 이 저장소의 콘텐츠 작업은 진행 상태를 파일 하나에 둡니다.

| # | 발행일 | 갈래 | slug | 주제 | 완료 | | 1 | 2026-09-11 | A | url-migration-redirects | ... | [x] | | 2 | 2026-09-14 | B | unattended-agent-guardrails | ... | [x] | | 3 | 2026-09-16 | C | lifting-gear-belt-straps-guide | ... | [ ] |

이 표는 세 줄로 여덟 편짜리 작업의 현재 상태를 전부 표현합니다. 무엇이 끝났고 무엇이 남았는지 알기 위해 지난 작업 내역을 되짚을 필요가 없습니다.

효과는 두 갈래입니다. 재개 가능성은 그중 하나이고, 다른 하나가 컨텍스트 절약입니다. 상태를 외부에 두면 그 상태를 기억하기 위해 자리를 쓰지 않아도 됩니다.

5. 요약이 손실이 되는 지점

긴 작업에서는 앞부분이 요약되어 압축됩니다. 이때 무엇이 잘 압축되고 무엇이 압축되면 안 되는지가 갈립니다.

압축돼도 괜찮음: "글 3편을 썼고 빌드가 통과했다" 탐색 과정에서 읽었지만 안 쓴 파일들 중간에 실패했다가 고친 시도들 압축되면 곤란함: 아직 안 쓴 글의 정확한 slug 와 날짜 ko 와 en 의 date 가 같아야 한다는 제약 이미 다룬 주제 목록 (중복 방지의 근거)

아래 셋의 공통점은 정확한 값이 필요하다는 것입니다. "날짜를 맞춰야 한다"는 요약은 남지만 "9월 16일"이라는 값이 흐려지면 소용이 없습니다.

그래서 이런 값들은 기억이 아니라 파일에서 다시 읽습니다. 큐 파일을 다시 열면 정확한 값이 그대로 있습니다. 정확해야 하는 것은 저장하고, 흐려져도 되는 것만 기억에 맡기는 것이 실질적인 원칙입니다.

요약하지 말고 인덱스를 만든다

여기서 한 걸음 더 나갈 수 있습니다. 압축이 손실을 낸다면, 애초에 압축할 일이 없게 만드는 것이 낫습니다.

보강할 글을 고르려면 기존 글 27편을 봐야 합니다. 전부 열면 이렇습니다.

전부 읽기 27편 × 평균 12KB = 약 320KB ~180,000 토큰 → 들어가지도 않고, 들어가도 다른 게 다 밀린다 인덱스만 슬러그 · 날짜 · 제목 · 파일 크기 27줄 × 약 60자 = 약 1.6KB ~900 토큰 → 크기 순으로 4편을 고르는 데 이걸로 충분하다

200분의 1입니다. 그리고 고른 4편만 실제로 엽니다. 요약이 아니라 인덱스인 게 중요합니다 — 요약은 원본을 읽어야 만들 수 있지만, 인덱스는 파일 이름과 앞부분 몇 줄만으로 만들어집니다.

일반화하면 이렇습니다. "전부 훑어보고 몇 개를 고르는" 작업은 인덱스로 바꿀 수 있습니다. 고르는 데 필요한 필드가 무엇인지만 정하면, 나머지는 고른 뒤에 읽으면 됩니다. 이 저장소에서 그 필드는 크기·날짜·슬러그 셋뿐이었습니다.

줄여야 할 때 무엇부터 버리나

그래도 넘칠 때가 있습니다. 버리는 순서를 미리 정해두면 그때 헤매지 않습니다.

1. 탐색 중 읽었지만 안 쓴 파일 — 필요하면 다시 읽으면 된다 2. 성공한 도구 호출의 전체 출력 — "통과했다" 한 줄이면 된다 3. 이미 커밋된 작업의 상세 내역 — 결과가 저장소에 남아 있다 4. 지금 작업과 무관한 규칙 문단 — 조건부로 옮길 후보 ───────────────────────────────────────────────────────── 버리지 않는 것 아직 안 끝난 항목의 정확한 값 (슬러그·날짜) 실패한 시도와 그 이유 — 다시 밟게 된다 이번 작업에서 정한 결정과 근거 — 뒤에서 모순이 난다

2번이 의외로 큽니다. 빌드 출력 전체를 남겨두면 한 번에 수백 줄인데, 실제로 필요한 건 통과 여부와 실패 시의 에러 몇 줄뿐입니다. 성공한 명령의 출력은 거의 항상 버려도 됩니다.

반대로 아래 둘째 줄이 자주 잘못 버려집니다. 실패한 시도를 지우면 같은 실패를 다시 밟습니다. 성공보다 실패가 더 오래 남아 있어야 합니다.

6. 검증을 컨텍스트 밖에 두기

한 가지 더 있습니다. 검증은 컨텍스트를 거의 안 씁니다.

"ko 와 en 의 날짜가 같은지 확인하라"를 규칙으로 지키게 하려면 그 규칙이 계속 실려 있어야 하고, 그럼에도 놓칠 수 있습니다. 빌드가 검사하면 규칙은 실려 있지 않아도 되고, 틀리면 에러 메시지가 그때 딱 필요한 만큼만 들어옵니다.

규칙으로: 항상 실려 있어야 함 + 놓칠 수 있음 가드로: 평소 0 + 틀렸을 때만 몇 줄

이 관점에서 보면 가드를 만드는 건 안전장치일 뿐 아니라 컨텍스트 최적화이기도 합니다. 강제할 수 있는 규칙을 코드로 옮길수록 문서에 적어야 할 규칙이 줄어듭니다.

7. 문서를 줄이는 실제 방법

규칙 문서가 길어졌을 때 실제로 해본 것들입니다.

  • 강제 가능한 규칙은 코드로 옮기고 문서에서 지운다. 빌드가 검사하는 항목은 문서에서 한 줄로 줄어듭니다 — "빌드가 잡아준다".
  • 설명을 예시 위치로 바꾼다. "필드 X 는 …" 열 줄 대신 "기존 글을 복사한다" 한 줄.
  • 안 지켜진 규칙만 강화한다. 실제로 깨진 적 없는 규칙은 더 자세히 쓰지 않습니다. 대개 아무도 안 어긴 규칙이 제일 길게 적혀 있습니다.
  • 같은 말을 두 곳에 쓰지 않는다. 문서와 코드 주석이 같은 규칙을 설명하고 있으면 둘 중 하나만 남깁니다.

세 번째가 특히 효과적이었습니다. 문서는 과거에 무엇이 무서웠는지의 기록이라, 실제 사고 빈도와 서술 분량이 잘 안 맞습니다.

예산이 빠듯할 때 나타나는 증상

컨텍스트가 모자란다는 건 에러로 나타나지 않습니다. 작업 품질이 특정한 방식으로 무너지는 것으로 나타납니다. 증상마다 원인이 다르고, 그래서 대처도 다릅니다.

증상 실제 원인 대처 ────────────────────────────────────────────────────────────── 앞에서 정한 걸 다시 묻는다 상태가 대화에만 있다 상태를 파일로 뺀다 초반엔 규칙을 지키다 규칙이 요약에서 강제 가능한 건 후반에 어긴다 흐려졌다 가드로 옮긴다 같은 파일을 반복해서 읽은 내용이 밀려났다 인덱스만 남기고 다시 읽는다 필요할 때 연다 뒤의 결론이 앞의 결론과 판단 근거가 결정과 근거를 모순된다 압축됐다 파일에 적는다 지시를 절반만 수행한다 지시 자체가 길어 지시를 쪼개 뒤쪽이 묻혔다 단계로 준다

첫 줄과 넷째 줄은 겉으로 비슷해 보이지만 다릅니다. 다시 묻는 건 양호한 신호입니다 — 모른다는 걸 알고 있으니까요. 모순된 결론을 자신 있게 내놓는 쪽이 훨씬 나쁩니다. 근거가 흐려진 자리에는 흐려졌다는 표시가 남지 않기 때문입니다.

마지막 줄은 규칙 문서가 아니라 지시의 문제입니다. 길게 쓴 한 번의 지시보다 짧은 지시 여러 번이 실제로 더 잘 지켜졌습니다. 규칙 문서를 쓸 때와 같은 이유입니다 — 분량이 강조가 되지 않습니다.

자주 묻는 질문

컨텍스트 창이 계속 커지는데, 이 고민이 곧 사라지지 않나요?

한도가 늘어도 순서 문제는 남습니다. 실제로 겪은 손실은 "안 들어갔다"보다 "들어갔는데 흐려졌다"가 훨씬 많았습니다. 그리고 넣을 수 있는 양이 늘면 넣는 양도 같이 늡니다 — 규칙 문서가 400줄이 된 것도 한도가 부족해서가 아니었습니다. 고르는 문제는 용량 문제와 별개입니다.

규칙 문서는 몇 줄이 적당한가요?

줄 수보다 "항상 참인가"로 거릅니다. 특정 작업에서만 참인 문단이 하나라도 있으면 그건 길이와 무관하게 잘못 들어와 있는 겁니다. 이 저장소의 규칙 문서는 10KB 인데, 그중 절반은 표와 예시라 실제 규칙은 훨씬 짧습니다.

파일을 부분만 읽는 게 나은가요?

찾는 게 무엇인지 아는 상태면 부분이 낫고, 무엇을 찾는지 모르면 전체가 낫습니다. 애매하면 검색으로 위치를 먼저 좁힌 다음 그 근처만 읽습니다. 앞의 인덱스 이야기와 같은 구조입니다 — 좁히는 단계와 읽는 단계를 나누는 겁니다.

중간 요약을 직접 시키면 되지 않나요?

도움이 되지만 요약이 손실이라는 점은 그대로입니다. 요약을 만들 때 무엇을 남길지는 그 시점의 판단인데, 나중에 필요해지는 건 대개 그때 사소해 보였던 값입니다. 그래서 요약은 보조로 쓰고, 정확해야 하는 값은 요약과 무관하게 파일에 적습니다.

스킬로 빼면 컨텍스트가 절약되나요?

네, 그게 스킬의 실질적인 이점 중 하나입니다. 특정 작업에서만 필요한 절차를 규칙 문서에 두면 모든 작업이 비용을 내지만, 스킬에 두면 그 작업에서만 냅니다. 위 표의 "언제 실리나" 열을 항상에서 조건부로 옮기는 수단이라고 봐도 됩니다.

무인 실행에서는 뭐가 달라지나요?

사람이 없으니 "다시 물어보기"라는 복구 수단이 없습니다. 그래서 상태를 파일에 두는 게 선택이 아니라 전제가 됩니다. 그 위에 멈출 조건까지 정해두면, 예산이 빠듯해져 품질이 무너지는 구간에 들어가기 전에 작업을 끊을 수 있습니다.

8. 정리

  • 컨텍스트는 공간이 아니라 예산이다. 문서를 늘리는 건 다른 몫을 줄이는 것입니다.
  • 모르면 되돌릴 수 없는 것만 항상 읽힌다. 나머지는 파일을 열면 나옵니다.
  • 설명 대신 예시를 가리킨다. 지시는 항상, 내용은 필요할 때.
  • 진행 상태는 저장소에 둔다. 기억으로 유지하면 계속 자리를 씁니다.
  • 정확해야 하는 값은 저장하고 다시 읽는다. 요약은 값이 아니라 요지만 남깁니다.
  • 강제 가능한 규칙은 가드로. 평소 비용이 0 이 됩니다.

규칙이 안 지켜질 때 문서를 늘리는 건 대개 문제를 반대로 푸는 것입니다. 물어볼 질문은 "어떻게 더 자세히 쓸까"가 아니라 "이걸 문서 밖으로 뺄 수 있나" 입니다. 코드로 옮기든, 예시로 대체하든, 파일로 내보내든 — 문서에서 빠진 규칙이 가장 잘 지켜집니다.