AI 에이전트가 아는 건 이 상자 안에 든 것뿐입니다.
무엇을 올리고 무엇을 치울지가 결과를 정합니다.
에이전트의 작업 책상
AI 에이전트가 아는 건 지금 "상자(컨텍스트 창)" 안에 든 것뿐입니다. 상자는 1M으로 커졌지만, 쌓일수록 흐려집니다.
/context로 확인하고, 작업 하나가 끝나면 비우세요 (/compact · /clear).지금까지 결정한 것, 남은 할 일, 버린 방향을 NOTES.md에 정리해줘. 그다음 이 파일만 보고도 새 세션에서 이어서 할 수 있는지 스스로 확인해줘.
상자 밖의 것은 AI에게 보이지 않습니다
✅ 필요한 것만 올라오면 — 똑똑하게 일합니다
❌ 잡음이 섞이면 — 좋은 모델도 헷갈립니다
상자에 없는 정보 = 세상에 없는 정보
두꺼운 책 여러 권이 통째로 들어가는 크기 — 최신 Claude 모델 기준
중형 프로젝트 하나가 거의 통째로 들어가는 크기
문제는 크기가 아니라 쌓인 양 — 들어간다고 다 잘 보지는 않습니다
같은 뜻이라도 한국어는 영어의 약 1.5–2배 토큰을 씁니다 — 그만큼 체감 용량이 줄어듭니다.
※ 이 덱의 숫자는 감을 잡기 위한 어림값입니다. 모델·도구·요금제마다 다르니 내 상자는 /context로 직접 확인하세요.
'Claude Code'를 설치하면 — 모델 Claude를 감싼 이 프로그램이 깔리는 것
우리가 설치하는 건 모델이 아니라 모델을 감싼 프로그램, 하네스입니다. 하네스가 하는 일 세 가지:
같은 모델 + 다른 하네스 = 다른 에이전트
지침 "테스트 없는 수정은 하지 말 것"
요청 "그냥 빨리 고쳐줘"
→ 대개 지침이 이겨 "수정 후 테스트까지" 합니다.
예전 결정: SQLite 사용 · 현재 결정: DuckDB 사용
둘 다 상자에 남아 있으면 에이전트는 어느 쪽을 따를지 흔들립니다.
여기 든 글자는 매 턴 다시 읽히는 상주 비용입니다 — 길수록 느려지고, 비싸지고, 핵심이 묻힙니다.
파일을 미리 다 읽지 않고, 필요한 것만 그때그때 가져옵니다. 대신 가져온 건 상자에 남습니다.
루프마다 조금씩 ↑
92% — 하루 종일 끌고 온 세션
끝까지 가면 자동 압축 — 지난 대화가 요약본으로 바뀌고 세부 결정·이유·예외가 사라집니다.
하지만 그 전에 이미 나빠집니다 — context rot(맥락 부패).
1M 상자에선 압축보다 이쪽을 먼저 만납니다.
LLM이 쓴 요약문으로 원문 히스토리를 통째로 교체합니다 — zip과 달리 복원 불가.
BEFORE — 원문 히스토리 141K
🙋 "로그인 버그 고쳐줘" 🤖 auth.py 읽기 — 812줄 전체 36K 🧪 pytest 로그 3,200줄 · 실패 2건 40K 🤖 원인: exp를 로컬 시간으로 계산해 UTC 서버와 1시간 어긋남 🙋 "refresh token 로직은 건드리지 마" 🤖 수정 diff · 재테스트 통과 …
AFTER — 모델이 새로 쓴 요약 6K
"로그인 버그를 수정했다. 원인은 토큰 만료 시간 계산 오류였고, auth.py를 고쳐 테스트가 통과했다."
상자가 엉망이면 좋은 모델도 엉뚱하게 일합니다. (숫자는 비유)
# ❌ 에이전트에게 불리한 요청 "이거 고쳐줘. 이전에 말한 방식으로." # '이전 방식'이 상자에서 밀려났다면 # 에이전트는 그것을 모릅니다
# ✅ 핵심 context가 명확한 요청 "이 버그를 고쳐줘. 단, 전역 상태는 추가하지 말고 auth_service.py 안에서 처리해줘. 수정 후 test_auth.py를 실행해서 확인해줘."
✅ 상자로
이번 작업의 재료들
🎯 목표 — "속도 개선, 동작 유지" 📜 빌드 로그 30,000줄 전체 🚧 제약 — "스키마 변경 금지" 🗞 폐기된 요구사항 v1 🧨 최근 에러 로그 tail 🗂 "참고용" 문서 뭉치 · 사내 규정 전문❌ 치운다
# ❌ 나쁜 예 "이 코드 개선해줘." # 무엇이 '개선'인지 에이전트가 탐색으로 # 알아내야 함 → 탐색 20~60K 토큰
# ✅ 좋은 예 "이 함수의 속도를 개선해줘. 동작은 바꾸지 말고, 기존 테스트는 모두 통과해야 해. 가능하면 복잡한 의존성 추가 없이 수정해줘."
파일과 함수를 콕 집어 주면 찾아 헤매는 비용이 사라집니다.
"찾아서 고쳐줘" 대신 "src/auth/login.ts의 validateToken()을 고쳐줘"
→ 요청 문장 다듬기는 프롬프트 엔지니어링 덱
# ❌ 나쁜 예 빌드 로그 30,000줄 전체 붙여넣기 # 한 번에 수십만 토큰이 잡음으로 채워짐 # 정작 중요한 한 줄은 중간에 묻힘
# ✅ 좋은 예 "마지막 에러는 아래와 같아. ImportError: cannot import name 'X' from 'module_y' 관련 변경은 module_y.py에서 함수명을 변경한 뒤 발생했어."
판단에 필요한 건 마지막 에러 + "무엇을 바꾼 뒤부터" 한 줄입니다. 전체 로그는 파일로 두고 필요하면 AI가 직접 읽게 하세요.
→ 같은 에러가 반복될 때는 디버깅 덱
매번 설명하던 규칙을 CLAUDE.md에 두면 에이전트가 세션마다 같은 기준으로 시작합니다.
대신 이 파일은 매 세션 자동으로 상자에 들어갑니다 — 한 줄 한 줄이 매 턴 다시 읽힙니다.
① 늘 참인 것만, 짧게 — 폴더 구조·금지 사항·확인 방법
② 가끔 필요한 긴 절차는 스킬로 — 평소엔 이름만 상주 (CH 5)
상자는 화이트보드, 파일은 공책입니다.
대화 "포트는 8081을 쓰기로 했어"
→ 한참 뒤 자동 압축 → 요약에서 빠짐 →
에이전트가 다시 8080으로 되돌립니다
"이번에 정한 규칙과 이유를 docs/decisions.md에 기록해줘" ──── /clear · 다음 날 새 세션 ──── "docs/decisions.md 읽고 이어가줘"
압축 · 초기화 후에도 그대로 복구
긴 작업의 체크리스트. 단계마다 갱신하면 "어디까지 했나"가 남습니다
조사 결과·중간 발견·버린 방향. 다음 세션이 그대로 이어받습니다
하네스가 스스로 적어 두는 기억 파일 — Claude Code의 auto memory 등
현재까지 결정된 것: - 인증 로직은 auth_service.py - DB 스키마는 변경하지 않음 - 원인: token 만료 계산 오류 다음 단계: test_auth_expiry 실행
내가 시킨 요약이 자동 압축보다 정확합니다
같은 일을 이어갈 때 — 대화를 요약본으로 교체
새 일을 시작할 때 — 작업 하나 = 세션 하나
옛 문장은 그대로 남습니다
대화 기록은 뒤에 덧붙기만 합니다 — "버려"라고 해도 옛 문장은 상자에 그대로 남습니다.
# ✅ 그래도 말하는 이유 — 더 최근의 분명한 지시가 이깁니다 "이전의 SQLite 기반 접근은 폐기하고, 이제부터는 DuckDB + Parquet 기준으로 진행해줘." # 버릴 것과 새 기준을 한 문장에 함께 적는 게 요령
① 유효한 결정을 파일에 남기고 /clear · 새 세션
② /compact "SQLite 논의는 버려줘" — 요약에서 빼기
서브에이전트는 자기만의 새 상자에서 일합니다. 파일 수십 개 읽기·긴 테스트 로그는 그 안에서 끝나고, 메인 상자에는 결론 몇 K만 돌아옵니다.
팀장에게 조사 보고서 한 장만 올리는 것과 같습니다. → 서브에이전트와 오케스트레이션
MCP(Model Context Protocol) — 하네스에 외부 도구(GitHub·Slack·사내 DB…)를 꽂는 공개 표준입니다. 여기서는 상자 비용만 봅니다. 실제 연결은 → 내 도구가 혼자 돌게
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)
본문이 길어도 평소 비용은 머리말 몇 줄. → 스킬 만드는 법
과제: "열린 PR을 확인하고 리뷰 코멘트를 남겨줘" — MCP 서버 vs 명령줄 도구(CLI) + 스킬
도구 35개의 이름·설명·스키마가 매 세션 로드 — 그날 안 써도
호출 결과(JSON)도 매번 상자를 통과
상주는 머리말(frontmatter) 몇 줄뿐
필요할 때: SKILL.md ~2K 로드 → gh pr list 실행. 모델은 이미 git · gh 사용법에 익숙
쓰지 않는 날의 상주 비용: 약 18K vs 약 0.05K
🔐 로그인(OAuth)이 필요한 원격 서비스 · 🚫 명령줄을 못 쓰는 환경(웹 챗 등) · 👥 여러 사람 권한·감사 기록이 필요할 때
기준은 하나: 자주 안 쓰는 도구를 상자에 상주시키지 않기. → 연결 설정은 automation 덱
고객명·수율·장비명·내부 주소가 로그나 파일에 섞여 무심코 함께 나갈 수 있습니다.
# ❌ 사외 도구에 원본 그대로 "Pixel ABC 프로젝트의 장비 X에서 wafer Y 수율이 72.3%로 떨어졌고…"
# ✅ 민감 정보를 걷어낸 질문 "제조 데이터 분석 파이프라인에서 특정 배치의 품질 지표가 급락했을 때, 원인 분석용 Python 구조를 어떻게 짜면 좋을까?"
① 회사 기밀·실데이터는 사내 승인 도구에서만 — 애매하면 넣지 않는다.
② API 키·비밀번호는 코드·대화·커밋에 남기지 않는다 — 새어 나갔다면 삭제가 아니라 재발급.
③ 회사 정책이 이 자료보다 우선한다.
이 덱에서 하나 더: 로그·파일을 통째로 붙이기 전에 무엇이 섞여 있는지 한 번 훑어보기.
다음으로 — 지식을 가르치는 법 · CLAUDE.md · 스킬 · 서브에이전트 · 디버깅
한정된 공간에 무엇을 올리고 무엇을 치울지 —
그 결정이 에이전트 활용의 품질을 좌우합니다.