시리즈 홈
SEMINAR · 2026.11 · CONTEXT

컨텍스트 —
AI 에이전트의
작업 책상

AI 에이전트가 아는 건 이 상자 안에 든 것뿐입니다.
무엇을 올리고 무엇을 치울지가 결과를 정합니다.

← 바이브 코딩이란 무엇인가?  ·  시리즈 전체 보기

1M tokensCONTEXT WINDOW

에이전트의 작업 책상

3분 요약 · TL;DR

결론부터 — 이 세 줄이면 됩니다

AI 에이전트가 아는 건 지금 "상자(컨텍스트 창)" 안에 든 것뿐입니다. 상자는 1M으로 커졌지만, 쌓일수록 흐려집니다.

  1. 1
    상자가 커져도, 넘치기 전에 먼저 흐려집니다1M 상자는 좀처럼 넘치지 않지만, 쌓인 잡음에 핵심이 묻힙니다. /context로 확인하고, 작업 하나가 끝나면 비우세요 (/compact · /clear).
  2. 2
    넣을 건 목표·완료 기준·정확한 위치, 뺄 건 긴 로그 전체로그는 마지막 에러 + 한 줄 맥락이면 충분합니다. 한 세션에는 한 가지 일.
  3. 3
    오래 갈 결정은 파일로 — 상자는 지워지고, 파일은 남습니다NOTES.md · PLAN.md에 적어 두면 압축·초기화 뒤에도 이어집니다. 무거운 탐색은 서브에이전트에게 맡깁니다.
지금 바로 써 보는 프롬프트
지금까지 결정한 것, 남은 할 일, 버린 방향을 NOTES.md에 정리해줘.
그다음 이 파일만 보고도 새 세션에서 이어서 할 수 있는지 스스로 확인해줘.
이럴 때 이 덱을 다시 펼치세요
  • 대화가 길어질수록 AI가 앞에서 한 말을 잊을 때
  • 이미 버린 방법을 AI가 자꾸 다시 꺼낼 때
  • 토큰·사용량이 생각보다 빨리 닳을 때
CH 1 · 상자의 정체
→ 키로 한 단계씩

AI는 이 상자 밖을 볼 수 없습니다

🗂 지난 세션✕ 보이지 않음
📁 안 읽은 파일✕ 보이지 않음
💭 당신의 의도✕ 보이지 않음
🌐 회사 위키✕ 보이지 않음
CONTEXT WINDOW
📐 설계서 💻 현재 코드 🧨 에러 로그 🗞 오래된 문서 💬 무관한 대화 📜 중복 로그

상자 밖의 것은 AI에게 보이지 않습니다

✅ 필요한 것만 올라오면 — 똑똑하게 일합니다

❌ 잡음이 섞이면 — 좋은 모델도 헷갈립니다

상자에 없는 정보 = 세상에 없는 정보

CH 1 · 상자의 정체

상자 크기는 1M 토큰 — 크지만 정해져 있습니다

1M

📖 책 몇 권 분량

두꺼운 책 여러 권이 통째로 들어가는 크기 — 최신 Claude 모델 기준

📄 코드 수만 줄

중형 프로젝트 하나가 거의 통째로 들어가는 크기

⚠️ 넘치기 전에 흐려집니다

문제는 크기가 아니라 쌓인 양 — 들어간다고 다 잘 보지는 않습니다

EN Fix the login bug and run the tests. 9 tok
KO 로그인 버그를 고치고 테스트를 실행해줘. ~15 tok

같은 뜻이라도 한국어는 영어의 약 1.5–2배 토큰을 씁니다 — 그만큼 체감 용량이 줄어듭니다.

※ 이 덱의 숫자는 감을 잡기 위한 어림값입니다. 모델·도구·요금제마다 다르니 내 상자는 /context로 직접 확인하세요.

CH 1 · 상자의 정체

상자를 가장 많이 채우는 건 파일·도구 결과입니다

92K / 1M
시스템 지시 · 도구 정의 (하네스가 자동으로 넣음)~24K
프로젝트 지침 · 메모리 (CLAUDE.md 등)~4K
내 요청 + 대화 기록~20K
검색 · 파일 · 도구 결과 (코드·로그·테스트)~36K
에이전트의 중간 계획 (할 일·판단)~8K
남은 공간~908K
에이전트는 매 턴 이 상자 전체를 다시 읽고 다음 행동을 정합니다.
CH 1 · 상자의 정체
→ 키로 한 단계씩

'System' 칸은 하네스가 채웁니다

예: Claude Code = 하네스
🧠모델
Claude
⇄
context
System

'Claude Code'를 설치하면 — 모델 Claude를 감싼 이 프로그램이 깔리는 것

같은 구조 ▸ Codex × GPT Antigravity CLI × Gemini opencode × 선택 모델

우리가 설치하는 건 모델이 아니라 모델을 감싼 프로그램, 하네스입니다. 하네스가 하는 일 세 가지:

  • 🖊 System 프롬프트 · 도구 정의를 자동 주입주입
  • 🔧 모델이 요청한 도구를 실행하고 결과를 추가실행
  • 🗜 상자가 차면 자동 압축 — 요약으로 교체압축

같은 모델 + 다른 하네스 = 다른 에이전트

CH 1 · 상자의 정체

정보에는 우선순위가 있고, 낡은 정보는 혼란을 만듭니다

1시스템 규칙절대 기준
2개발자 · 도구 · 보안 규칙강한 제약
3프로젝트 지침CLAUDE.md 등
4사용자 요청지금 할 일
5현재 작업 관련 파일 · 문서근거
6실행 결과 · 로그증거
7이전 대화 요약배경

충돌하면 어떻게 될까?

지침 "테스트 없는 수정은 하지 말 것"

요청 "그냥 빨리 고쳐줘"

→ 대개 지침이 이겨 "수정 후 테스트까지" 합니다.

낡은 정보가 남아 있으면

예전 결정: SQLite 사용 · 현재 결정: DuckDB 사용

둘 다 상자에 남아 있으면 에이전트는 어느 쪽을 따를지 흔들립니다.

CH 2 · 상자는 어떻게 차오르는가
→ 키로 한 단계씩

첫 인사를 하기도 전에 이미 27K가 차 있습니다

27K / 1M세션 시작 직후
  • 🔌 세션 시작 — 상자는 비어 있음0K
  • 🖊 시스템 프롬프트 주입+3K
  • 🧰 도구 정의 수십 개 — 이름·설명·사용법+21K
  • 📝 CLAUDE.md · 메모리 — 매 세션 자동 로드+3K

여기 든 글자는 매 턴 다시 읽히는 상주 비용입니다 — 길수록 느려지고, 비싸지고, 핵심이 묻힙니다.

CH 2 · 상자는 어떻게 차오르는가
→ 키로 한 단계씩

에이전트는 한 바퀴 돌 때마다 상자를 조금씩 채웁니다

STEP 1🎯 목표 이해
STEP 2🔍 필요 정보 확인
STEP 3🔧 도구 호출
STEP 4📥 결과를 상자에 추가
STEP 5✅ 검증 · 요약 ↺
AGENT LOOP ↺
  • 세션 시작27K
  • ↺ 1바퀴 — 관련 파일 읽기+9K
  • ↺ 2바퀴 — 테스트 실행 로그+15K
  • ↺ 3바퀴 — 수정 diff · 재검증+12K

파일을 미리 다 읽지 않고, 필요한 것만 그때그때 가져옵니다. 대신 가져온 건 상자에 남습니다.

63K / 1M

루프마다 조금씩 ↑

CH 2 · 상자는 어떻게 차오르는가
→ 키로 한 단계씩

버그 하나 고친 세션 — 166K가 쌓였지만 핵심은 몇 줄

  • 💬 세션 시작 — 시스템 + 도구 + CLAUDE.md27K
  • 🙋 "로그인 버그 고쳐줘" + 계획 수립+4K
  • 📂 auth.py · login_service.py · test_auth.py 읽기+35K
  • ✏️ 원인 추정 · 코드 수정 · diff 출력+18K
  • 🧪 테스트 실행 — 장황한 로그가 통째로+40K
  • 🔁 재수정 왕복 ×6 + 중간 판단+42K
  • 상자는 겨우 17% — 그런데 166K 중 지금 필요한 건 몇 줄뿐.
    넘칠 걱정보다 묻힐 걱정이 먼저입니다.
166K / 1M
파일 · 로그
CH 2 · 상자는 어떻게 차오르는가
→ 키로 한 단계씩

길어질수록 핵심 한 줄이 묻힙니다

🔑 "토큰 만료는 UTC 기준으로 계산할 것"
↑ 중간에 낀 핵심부터 놓칩니다 (lost in the middle)
🎯 잡음에 주의를 뺏긴다
🧟 버린 결정을 다시 따른다— SQLite? DuckDB?
💸 느려지고 비싸진다
📉 판단이 흐려진다
🔁 같은 파일을 또 읽는다
많이가 아니라, 지금 필요한 것만.
CH 2 · 상자는 어떻게 차오르는가

가득 차기 한참 전부터 품질이 떨어집니다

~920K / 1M
대화 히스토리
파일 · 로그

92% — 하루 종일 끌고 온 세션

끝까지 가면 자동 압축 — 지난 대화가 요약본으로 바뀌고 세부 결정·이유·예외가 사라집니다.

한계선보다 훨씬 앞에서 응답 품질 context 사용량 →

하지만 그 전에 이미 나빠집니다 — context rot(맥락 부패).
1M 상자에선 압축보다 이쪽을 먼저 만납니다.

CH 2 · 상자는 어떻게 차오르는가
→ 키로 한 단계씩

압축은 zip이 아니라 "요약해서 갈아끼우기"입니다

LLM이 쓴 요약문으로 원문 히스토리를 통째로 교체합니다 — zip과 달리 복원 불가.

BEFORE — 원문 히스토리 141K

🙋 "로그인 버그 고쳐줘"
🤖 auth.py 읽기 — 812줄 전체          36K
🧪 pytest 로그 3,200줄 · 실패 2건     40K
🤖 원인: exp를 로컬 시간으로 계산해
   UTC 서버와 1시간 어긋남
🙋 "refresh token 로직은 건드리지 마"
🤖 수정 diff · 재테스트 통과 …

AFTER — 모델이 새로 쓴 요약 6K

"로그인 버그를 수정했다.
원인은 토큰 만료 시간 계산 오류였고,
auth.py를 고쳐 테스트가 통과했다."
요약에서 사라진 것 ↓ UTC vs 로컬 — 구체 원인 "refresh token 금지" 제약 코드 · 로그 원문
요약은 복원 불가이고, 무엇을 남길지는 요약 모델의 추측입니다.
그래서 /compact "auth 버그 수정 내용 위주로 남겨줘"처럼 남길 것을 직접 지시할 수 있습니다.
CH 3 · 왜 관리인가

성능은 곱셈 — 컨텍스트 하나가 낮으면 전체가 무너집니다

모델 능력0.95
×
context 품질0.30
×
도구 품질0.90
×
검증 루프0.85
=
체감 성능0.22

상자가 엉망이면 좋은 모델도 엉뚱하게 일합니다. (숫자는 비유)

# ❌ 에이전트에게 불리한 요청
"이거 고쳐줘. 이전에 말한 방식으로."

# '이전 방식'이 상자에서 밀려났다면
# 에이전트는 그것을 모릅니다
# ✅ 핵심 context가 명확한 요청
"이 버그를 고쳐줘. 단, 전역 상태는 추가하지 말고
auth_service.py 안에서 처리해줘.
수정 후 test_auth.py를 실행해서 확인해줘."
CH 3 · 왜 관리인가
→ 키로 한 단계씩

넣을 건 목표·제약·에러 끝부분, 나머지는 치웁니다

✅ 상자로

context
🎯 목표 · 완료 기준 🚧 제약 · 금지 사항 🧨 에러 로그 tail 20줄

이번 작업의 재료들

🎯 목표 — "속도 개선, 동작 유지" 📜 빌드 로그 30,000줄 전체 🚧 제약 — "스키마 변경 금지" 🗞 폐기된 요구사항 v1 🧨 최근 에러 로그 tail 🗂 "참고용" 문서 뭉치 · 사내 규정 전문

❌ 치운다

🗑
📜 전체 로그 — tail이면 충분 🗞 폐기된 요구사항 🗂 참고용 문서 뭉치
전부가 아니라 이번 판단에 필요한 것만.
CH 4 · 실전 패턴 ①

목표·완료 기준·위치를 콕 집으면 탐색이 줄어듭니다

# ❌ 나쁜 예
"이 코드 개선해줘."

# 무엇이 '개선'인지 에이전트가 탐색으로
# 알아내야 함 → 탐색 20~60K 토큰
# ✅ 좋은 예
"이 함수의 속도를 개선해줘.
동작은 바꾸지 말고, 기존 테스트는 모두 통과해야 해.
가능하면 복잡한 의존성 추가 없이 수정해줘."
72%
vs
31%

파일과 함수를 콕 집어 주면 찾아 헤매는 비용이 사라집니다.
"찾아서 고쳐줘" 대신 "src/auth/login.ts의 validateToken()을 고쳐줘"
→ 요청 문장 다듬기는 프롬프트 엔지니어링 덱

CH 4 · 실전 패턴 ②

로그는 통째로 말고 마지막 에러 + 한 줄 맥락만

# ❌ 나쁜 예
빌드 로그 30,000줄 전체 붙여넣기

# 한 번에 수십만 토큰이 잡음으로 채워짐
# 정작 중요한 한 줄은 중간에 묻힘
# ✅ 좋은 예
"마지막 에러는 아래와 같아.
ImportError: cannot import name 'X'
  from 'module_y'

관련 변경은 module_y.py에서
함수명을 변경한 뒤 발생했어."
61%
→
25%

판단에 필요한 건 마지막 에러 + "무엇을 바꾼 뒤부터" 한 줄입니다. 전체 로그는 파일로 두고 필요하면 AI가 직접 읽게 하세요.
→ 같은 에러가 반복될 때는 디버깅 덱

CH 4 · 실전 패턴 ③

반복 지침은 파일로 — 단, 매 턴 읽히는 비용입니다

매번 설명하던 규칙을 CLAUDE.md에 두면 에이전트가 세션마다 같은 기준으로 시작합니다.

대신 이 파일은 매 세션 자동으로 상자에 들어갑니다 — 한 줄 한 줄이 매 턴 다시 읽힙니다.

그래서 두 가지만 지킵니다

① 늘 참인 것만, 짧게 — 폴더 구조·금지 사항·확인 방법

② 가끔 필요한 긴 절차는 스킬로 — 평소엔 이름만 상주 (CH 5)

긴 지침
지침
→
짧은 지침

노란 칸 = 매 턴 다시 읽히는 지침

무엇을 어떻게 쓰나 → 내 노하우를 AI에게 물려주는 법
CH 4 · 실전 패턴 ④

결정은 파일로 — 상자는 지워지고, 파일은 남습니다

상자는 화이트보드, 파일은 공책입니다.

💬 말로만 남긴 기억

대화 "포트는 8081을 쓰기로 했어"

→ 한참 뒤 자동 압축 → 요약에서 빠짐 →
에이전트가 다시 8080으로 되돌립니다

📝 파일로 남긴 기억

"이번에 정한 규칙과 이유를
 docs/decisions.md에 기록해줘"
──── /clear · 다음 날 새 세션 ────
"docs/decisions.md 읽고 이어가줘"

압축 · 초기화 후에도 그대로 복구

📋 PLAN.md

긴 작업의 체크리스트. 단계마다 갱신하면 "어디까지 했나"가 남습니다

📓 NOTES.md

조사 결과·중간 발견·버린 방향. 다음 세션이 그대로 이어받습니다

🗃 자동 메모리

하네스가 스스로 적어 두는 기억 파일 — Claude Code의 auto memory 등

CH 4 · 실전 패턴 ⑤

작업 하나 끝나면 비우세요 — 이어갈 땐 /compact

📝 중간 요약

현재까지 결정된 것:
- 인증 로직은 auth_service.py
- DB 스키마는 변경하지 않음
- 원인: token 만료 계산 오류
다음 단계: test_auth_expiry 실행

내가 시킨 요약이 자동 압축보다 정확합니다

/compact

85%
→
35%

같은 일을 이어갈 때 — 대화를 요약본으로 교체

/clear · 새 세션

85%
→
~3%

새 일을 시작할 때 — 작업 하나 = 세션 하나

이어갈 이유가 없다면 비우는 쪽이 이득입니다. 남길 결정은 먼저 파일로.
CH 4 · 실전 패턴 ⑥
→ 키로 한 단계씩

"그건 버려"는 지우개가 아니라 덧쓰기입니다

append-only 히스토리
System · 도구
SQLite로 간다 (예전)
SQLite 폐기 · DuckDB 확정

옛 문장은 그대로 남습니다

대화 기록은 뒤에 덧붙기만 합니다 — "버려"라고 해도 옛 문장은 상자에 그대로 남습니다.

# ✅ 그래도 말하는 이유 — 더 최근의 분명한 지시가 이깁니다
"이전의 SQLite 기반 접근은 폐기하고,
이제부터는 DuckDB + Parquet 기준으로 진행해줘."
# 버릴 것과 새 기준을 한 문장에 함께 적는 게 요령

진짜로 상자에서 치우려면

① 유효한 결정을 파일에 남기고 /clear · 새 세션
② /compact "SQLite 논의는 버려줘" — 요약에서 빼기

CH 4 · 실전 패턴 ⑦

무거운 탐색은 서브에이전트의 상자에서 끝냅니다

85%
탐색 에이전트 다 쓰고 버려짐 ♻️
→결론만 +2K
22%메인은 가볍게
System · 도구
메인 에이전트
←요약만 +1.5K
78%
테스트 에이전트 다 쓰고 버려짐 ♻️

서브에이전트는 자기만의 새 상자에서 일합니다. 파일 수십 개 읽기·긴 테스트 로그는 그 안에서 끝나고, 메인 상자에는 결론 몇 K만 돌아옵니다.

팀장에게 조사 보고서 한 장만 올리는 것과 같습니다. → 서브에이전트와 오케스트레이션

CH 5 · 더 큰 그림

메모리·검색·스킬·MCP는 필요할 때만 상자에 들어옵니다

🧠 Memory사용자·프로젝트에 대한 장기 기억
🔎 RAG외부 문서에서 필요한 부분만 검색
🧰 Skill반복 절차·도구 사용법을 패키징
🔌 MCP외부 도구·데이터를 표준으로 연결
→→→→
context window지금 모델이 직접 보는 것
←←
🔧 Tool result파일 읽기·웹 검색·터미널 실행 결과
🗜 Summary긴 대화·작업 상태의 압축본
Memory·RAG·Skill·MCP는 상자 밖에 있다가, 필요할 때 상자 안으로 들어와야 실제 판단에 쓰입니다.
문서가 아무리 많아도 검색되어 들어오지 않으면 없는 것과 같습니다. → LLM에게 지식을 가르치는 법
CH 5 · 더 큰 그림
→ 키로 한 단계씩

MCP 서버를 꽂을수록 대화 전부터 상자가 찹니다

MCP(Model Context Protocol) — 하네스에 외부 도구(GitHub·Slack·사내 DB…)를 꽂는 공개 표준입니다. 여기서는 상자 비용만 봅니다. 실제 연결은 → 내 도구가 혼자 돌게

  • 🔧 기본 도구만 — 파일 · 터미널 · 검색24K
  • 🔀 + GitHub 서버 — 도구 35개의 이름·설명·파라미터+18K
  • 💬 + Slack 서버 — 도구 11개+12K
  • 📋 + Jira · 사내 DB 서버 …+18K
  • 첫 인사도 전에 72K — 도구의 설명서도 전부 상자에 들어갑니다.
    비슷한 도구가 수십 개면 고르다 헷갈리고, 매 턴 다시 읽혀 느려집니다. 안 쓰는 서버는 뺍니다. 최신 하네스는 도구 이름만 올려 두고 설명서는 필요할 때 불러오기도 합니다.
72K / 1M대화 시작 전
도구 정의
CH 5 · 더 큰 그림
→ 키로 한 단계씩

스킬은 평소엔 이름만, 필요할 때 본문을 펼칩니다

SKILL.md 전체 — deploy-check 스킬

---
name: deploy-check
description: 배포 전 점검 절차.
  배포·릴리스 요청 시 사용
---
YAML frontmatter — 이것만 항상 상주 · ~50 tok
# 절차 (본문 — 아무리 길어도 OK)
1. 테스트 전체 실행 · 커버리지 확인
2. CHANGELOG 갱신 · 버전 태그
3. 스테이징 배포 → 스모크 테스트
   … (500줄)
본문 · ~2K — 관련 작업이 감지된 순간에만
├─ reference.md   ← 37K짜리 상세 규칙
└─ scripts/check.sh ← 실행만, 코드는 상자 밖
부속 파일 · +α — 그 단계에 도달했을 때만

단계적 공개 (progressive disclosure)

1평소: 모든 스킬의 머리말만 상주~50 tok/스킬
2관련 작업 감지 → 그 SKILL.md 본문만 로드~2K
3필요할 때만 부속 파일 읽기 · 스크립트 실행+α
매뉴얼을 통째로 외우게 하지 않고,
목차만 들고 있다가 필요한 장을 펴게 한다.

본문이 길어도 평소 비용은 머리말 몇 줄. → 스킬 만드는 법

CH 5 · 더 큰 그림

같은 GitHub 작업도 연결법에 따라 상주 비용이 다릅니다

과제: "열린 PR을 확인하고 리뷰 코멘트를 남겨줘" — MCP 서버 vs 명령줄 도구(CLI) + 스킬

🔌 MCP 서버 직결

~18K상주
도구 정의

도구 35개의 이름·설명·스키마가 매 세션 로드 — 그날 안 써도

호출 결과(JSON)도 매번 상자를 통과

⌨️ CLI 도구 + Skill

~50 tok상주

상주는 머리말(frontmatter) 몇 줄뿐

필요할 때: SKILL.md ~2K 로드 → gh pr list 실행. 모델은 이미 git · gh 사용법에 익숙

쓰지 않는 날의 상주 비용: 약 18K vs 약 0.05K

⚖️ 단, MCP가 맞는 경우도 많습니다

🔐 로그인(OAuth)이 필요한 원격 서비스  ·  🚫 명령줄을 못 쓰는 환경(웹 챗 등)  ·  👥 여러 사람 권한·감사 기록이 필요할 때

기준은 하나: 자주 안 쓰는 도구를 상자에 상주시키지 않기. → 연결 설정은 automation 덱

CH 5 · 더 큰 그림

상자에 넣는 것 = 모델로 보내는 것입니다

고객명·수율·장비명·내부 주소가 로그나 파일에 섞여 무심코 함께 나갈 수 있습니다.

# ❌ 사외 도구에 원본 그대로
"Pixel ABC 프로젝트의 장비 X에서
wafer Y 수율이 72.3%로 떨어졌고…"
# ✅ 민감 정보를 걷어낸 질문
"제조 데이터 분석 파이프라인에서
특정 배치의 품질 지표가 급락했을 때,
원인 분석용 Python 구조를 어떻게 짜면 좋을까?"

🔒 보안 약속 — 시리즈 공통

① 회사 기밀·실데이터는 사내 승인 도구에서만 — 애매하면 넣지 않는다.

② API 키·비밀번호는 코드·대화·커밋에 남기지 않는다 — 새어 나갔다면 삭제가 아니라 재발급.

③ 회사 정책이 이 자료보다 우선한다.

이 덱에서 하나 더: 로그·파일을 통째로 붙이기 전에 무엇이 섞여 있는지 한 번 훑어보기.

→ 사내 환경에서의 AI — 보안과 거버넌스

REFERENCES

더 깊이 보기

📚 공식 문서

🛠 엔지니어링 블로그

🔬 연구 · 규약

CLOSING

좋은 사용자는
상자를 설계합니다

  1. 상자 밖은 AI에게 없는 것이다
  2. 상자는 넘치기 전에 흐려진다
  3. 파일 읽기·로그·도구 하나하나에 토큰 값이 있다
  4. 작업이 끝나면 — 결정은 파일로, 상자는 비우기
좋은 답을 요구하는 것이 아니라,
좋은 판단을 할 수 있는 작업 환경을 만들어주는 것.

다음으로 — 지식을 가르치는 법 · CLAUDE.md · 스킬 · 서브에이전트 · 디버깅

이 네모를 기억하세요
System · 도구
요청 · 대화
파일 · 결과

한정된 공간에 무엇을 올리고 무엇을 치울지 —
그 결정이 에이전트 활용의 품질을 좌우합니다.