에이전트의 머릿속엔, 딱 이 상자 하나뿐입니다.
무엇을 올려두고 무엇을 치울지가 결과를 좌우합니다.
agent의 작업 책상
▸ 상자에 무엇을 올리느냐가 전부입니다
✅ 필요한 것이 올라오면 — 똑똑하게 일합니다
❌ 잡음이 섞이면 — 최고의 모델도 헷갈립니다
상자에 없는 정보 = 세상에 없는 정보
소설 500쪽 분량의 텍스트가 통째로 들어가는 크기
웬만한 중형 프로젝트의 핵심 소스 전체
에이전트 세션에서는 파일·로그·대화가 쏟아져 들어와 생각보다 훨씬 빨리 소진됩니다
같은 의미라도 한국어는 영어의 ~1.5–2배 — 같은 200K여도 언어에 따라 체감 용량이 달라집니다. 그래서 긴 공통 지침은 영어로 쓰기도 합니다.
※ 이 발표의 모든 숫자는 감을 잡기 위한 대략치입니다. 모델·도구마다 다릅니다.
'Claude Code'를 설치하면 — 모델 Claude를 감싼 이 프로그램이 깔리는 것
설치해 쓰는 것은 모델이 아니라 모델을 감싼 프로그램 — 하네스. 하네스가 일하는 모습 ▾
같은 모델 + 다른 하네스 = 다른 에이전트
지침 "테스트 없는 수정은 하지 말 것"
요청 "그냥 빨리 고쳐줘"
→ 좋은 에이전트는 지침을 따라 "수정 후 테스트까지" 판단합니다.
예전 결정: SQLite 사용 · 현재 결정: DuckDB 사용
둘 다 상자에 남아 있으면 에이전트는 어느 쪽을 따를지 흔들립니다.
여기 넣은 글자는 매 턴 자리를 차지하는 상주 비용입니다.
모든 파일을 미리 읽지 않고, 필요한 것만 점진적으로 끌어옵니다.
루프마다 조금씩 ↑
92% — 한계 임박
한계선을 넘으면 자동 압축 — 과거 대화가 요약본으로 교체되고, 세부 결정·이유·예외가 사라집니다.
가득 차기 전에 이미 나빠집니다 — context rot
LLM이 쓴 요약문으로 원문 히스토리를 통째로 교체합니다 — zip과 달리 복원 불가.
BEFORE — 원문 히스토리 141K
🙋 "로그인 버그 고쳐줘" 🤖 auth.py 읽기 — 812줄 전체 36K 🧪 pytest 로그 3,200줄 · 실패 2건 40K 🤖 원인: exp를 로컬 시간으로 계산해 UTC 서버와 1시간 어긋남 🙋 "refresh token 로직은 건드리지 마" 🤖 수정 diff · 재테스트 통과 …
AFTER — 모델이 새로 쓴 요약 6K
"로그인 버그를 수정했다. 원인은 토큰 만료 시간 계산 오류였고, auth.py를 고쳐 테스트가 통과했다."
context 품질이 낮으면, 최고의 모델도 이상하게 행동합니다.
# ❌ 에이전트에게 불리한 요청 "이거 고쳐줘. 이전에 말한 방식으로." # '이전 방식'이 상자에서 밀려났다면 # 에이전트는 그것을 모릅니다
# ✅ 핵심 context가 명확한 요청 "이 버그를 고쳐줘. 단, 전역 상태는 추가하지 말고 auth_service.py 안에서 처리해줘. 수정 후 test_auth.py를 실행해서 확인해줘."
✅ 상자로
이번 작업의 재료들
🎯 목표 — "속도 개선, 동작 유지" 📜 빌드 로그 30,000줄 전체 🚧 제약 — "스키마 변경 금지" 🗞 폐기된 요구사항 v1 🧨 최근 에러 로그 tail 🗂 "참고용" 문서 뭉치 · 사내 규정 전문❌ 치운다
# ❌ 나쁜 예 "이 코드 개선해줘." # 무엇이 '개선'인지 에이전트가 탐색으로 # 알아내야 함 → 탐색 20~60K 토큰
# ✅ 좋은 예 "이 함수의 속도를 개선해줘. 동작은 바꾸지 말고, 기존 테스트는 모두 통과해야 해. 가능하면 복잡한 의존성 추가 없이 수정해줘."
파일과 함수를 콕 집어주면 에이전트의 탐색 비용이 사라집니다.
"찾아서 고쳐줘" 대신 "src/auth/login.ts의 validateToken()을 고쳐줘"
# ❌ 나쁜 예 빌드 로그 30,000줄 전체 붙여넣기 # 한 번에 상자의 20~25%가 소음으로 채워짐 # 정작 중요한 한 줄은 중간에 묻힘
# ✅ 좋은 예 "마지막 에러는 아래와 같아. ImportError: cannot import name 'X' from 'module_y' 관련 변경은 module_y.py에서 함수명을 변경한 뒤 발생했어."
같은 정보량이라도 에러의 마지막 부분 + 맥락 한 줄이면 충분합니다. 로그는 요약본이나 tail만 전달하세요.
매번 프롬프트에 쓰는 대신, 프로젝트에 두면 에이전트가 매 작업마다 같은 기준을 참고합니다.
AGENTS.md / CLAUDE.md / SKILL.md ├─ 코딩 스타일 · 컨벤션 ├─ 테스트 방법 ├─ 금지 사항 · 보안 규칙 ├─ 폴더 구조 └─ 배포 방식
이 파일은 매 세션 자동 로드되는 상주 비용 — 이력서처럼 쓰세요. 짧고, 늘 참인 것만.
컨텍스트는 RAM, 파일은 디스크입니다.
대화 "포트는 8081을 쓰기로 했어"
→ 30턴 뒤 자동 압축 → 요약에서 누락 →
에이전트가 다시 8080으로 되돌립니다
"이번에 정한 규칙과 이유를 docs/decisions.md에 기록해줘" ──── /clear · 다음 날 새 세션 ──── "docs/decisions.md 읽고 이어가줘"
압축 · 초기화 후에도 그대로 복구
긴 작업의 체크리스트를 파일로 두고 단계마다 갱신 — "어디까지 했나"가 압축을 견딥니다
대량 조사 결과·중간 발견을 노트 파일로. Claude가 공략 노트를 쓰며 포켓몬을 플레이한 것과 같은 원리
하네스가 기본 지원하는 파일 기반 장기 기억 — Claude Code의 auto memory, API의 memory tool
현재까지 결정된 것: - 인증 로직은 auth_service.py - DB 스키마는 변경하지 않음 - 원인: token 만료 계산 오류 다음 단계: test_auth_expiry 실행
긴 대화 전체보다 훨씬 유용한 압축본
이어가야 할 때 — 대화를 요약본으로 교체
작업 하나 = 세션 하나가 기본기
옛 문장은 그대로 남습니다
대화 히스토리는 덧붙기만(append-only) 합니다 — 폐기를 선언해도 옛 문장은 남습니다.
# ✅ 그래도 선언하는 이유 — 최신·명시적 신호가 이깁니다 "이전의 SQLite 기반 접근은 폐기하고, 이제부터는 DuckDB + Parquet 기준으로 진행해줘." # 옛 결정보다 더 최근 위치에, 더 명시적인 상위 지시가 # 추가되어 모델이 이를 따르게 됩니다
① /clear · 새 세션 — 유효한 결정은 파일에 남기고
② /compact "SQLite 논의는 버려줘" — 요약에 반영
③ API의 context editing — 오래된 도구 결과를 자동 삭제
서브에이전트는 자기만의 상자를 새로 받습니다. 대량 탐색·파일 읽기 같은 지저분한 소비는 그 안에서 끝나고, 본진 상자에는 결론 몇 K만 착륙합니다.
코드에서 함수를 분리하는 것과 같은 원리입니다.
Model Context Protocol — 하네스에 외부 도구·데이터 소스(GitHub·Slack·사내 DB…)를 연결하는 공개 표준. "AI 도구의 USB-C 포트"라고 불립니다.
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 — 단계적 공개 ▸
본문이 길어도, 부속 파일이 많아도 — 평소 비용은 frontmatter 몇 줄입니다.
과제: "열린 PR을 확인하고 리뷰 코멘트를 남겨줘" — GitHub에 연결하는 두 가지 방법
도구 35개의 이름·설명·스키마가 매 세션 로드 — 그날 안 써도
호출 결과(JSON)도 매번 상자를 통과
상주는 frontmatter 몇 줄뿐
필요할 때: SKILL.md ~2K 로드 → gh pr list 실행. 모델은 이미 git · gh 사용법에 익숙
쓰지 않는 날의 상주 비용: 18K vs 0.05K — 약 1/300
🔐 원격 서비스 + OAuth 인증 · 🚫 셸·CLI가 없는 실행 환경(웹 챗 등) · 👥 다중 사용자 권한·감사 로그가 필요한 제품
MCP도 진화 중 — Tool Search(스키마를 필요할 때만 로드) · 코드 실행 결합으로 150K→2K(−98.7%)
상자에 담는 것 = 외부 모델로 나가는 것
내부 코드 · 내부 문서 · 사내 로그 · 보안이 필요한 데이터
일반 개념 설명 · 공개 문서 · 샘플 코드 · 민감 정보를 제거해 추상화한 문제
# ❌ 원본 그대로 "Pixel ABC 프로젝트의 장비 X에서 wafer Y 수율이 72.3%로 떨어졌고…"
# ✅ 재구성된 context "어떤 제조 데이터 분석 파이프라인에서 특정 배치의 품질 지표가 급락했을 때, 원인 분석용 Python 구조를 어떻게 설계하면 좋을까?"
한정된 공간에 무엇을 올리고 무엇을 치울지 —
그 결정이 에이전트 활용의 품질을 좌우합니다.