AI 에이전트를 써본 사람이라면 한 번쯤 이 경험을 한다. 터미널에 "어드민 패널 추가해줘"라고 입력했더니 600줄이 생성됐는데, 막상 열어보니 내가 원하던 게 아닌 것. 에이전트는 틀리지 않았다. 나의 의도를 잘못 전달한 것이다. 이 문제의 이름은 '컨텍스트 설계의 부재'다.
최근 세 편의 글이 각기 다른 각도에서 같은 결론을 가리킨다. Claude Code 실무 워크플로우를 공개한 개발자 Gabbs의 경험, 컨텍스트 패킷 아키텍처를 제안한 Majdi의 설계론, 그리고 Sentra가 분석한 에이전트 토큰 비용 구조. 표면적으로는 제각각이지만, 세 편 모두 같은 전제에서 출발한다. 에이전트에게 더 많은 것을 주는 게 아니라, 더 정확한 것을 주는 것이 핵심이다.
설계 → 계획 → 실행: 에이전트를 위한 3단계 워크플로우
Gabbs는 Claude Code를 실무 프로젝트(React + Vite + Sanity 스택)에 적용하면서 얻은 가장 중요한 통찰을 이렇게 요약한다. "에이전트에게 일을 시키기 전에 반드시 문서로 된 계획이 있어야 한다." 처음엔 관료적으로 느껴졌지만, 실제로는 이 단계가 결과의 질을 갈랐다.
그의 워크플로우는 세 단계로 나뉜다. 설계(Design): 코드를 건드리기 전에 대화로 문제를 정의하고, 두세 가지 접근법과 각각의 단점을 정리해 docs/plans/에 문서로 남긴다. 계획(Plan): 설계 문서를 파일 단위 작업 목록으로 변환한다. 어떤 파일을 수정하고, 어떤 테스트를 먼저 쓰고, 어떤 커맨드로 검증할지. 실행(Execute): 계획서가 앞에 있으면 에이전트는 표류하지 않는다. 뭔가 어긋날 때 "에이전트가 이상한 짓을 했다"가 아니라 "4번 단계에서 계획을 벗어났다"로 문제를 특정할 수 있다.
이 접근의 진짜 가치는 위임 가능한 작업의 범위를 넓히는 데 있다. Express 서버를 Vercel Functions로 마이그레이션하는 것처럼 "기계적이고, 명확하게 정의되어 있으며, 객관적인 성공 기준이 있는" 작업은 에이전트가 인간보다 낫다. 연속으로 스무 가지 디테일을 틀리지 않아야 하는 일에서. 반대로 에이전트가 실패하는 지점도 명확하다. 전제를 너무 빨리 수용하고, 나쁜 아이디어에도 동의하며, 긴 세션에서는 초반 결정을 잊는다. 그래서 결정은 대화가 아닌 파일에 남겨야 한다.
컨텍스트 패킷: 리포지토리 전체가 아니라 '지금 이 변경'에 필요한 것만
Majdi의 글은 더 구조적인 문제를 건드린다. 리포지토리 전체에 접근 권한을 준다고 에이전트가 시스템을 더 잘 이해하는 건 아니다. 오히려 반대일 수 있다. 폐기된 코드, 기록되지 않은 결정, 서로 모순되는 예시들—이 모든 노이즈 속에서 에이전트는 "어느 게 진짜 규칙인가"를 판단해야 한다.
그가 제안하는 것이 컨텍스트 패킷(Context Packet)이다. 단일 변경이나 워크플로우를 위해 필요한 최소한의 범위 입력. 폴더 구조가 아닌 의존성 그래프를 기반으로 구성된다. 예를 들어 "결제 알림 워커에 재시도 로직 추가"라는 작업은 단순해 보이지만, 안전한 구현에는 메시지 전달 방식, 멱등성 키 지원 여부, 어떤 예외가 일시적인지 같은 질문이 필요하다. 이 정보는 코드에 존재할 수도 있고 없을 수도 있다. 클루(clue)는 컨트랙트(contract)가 아니다.
컨텍스트 패킷의 구조는 이렇다. read: 읽어야 할 파일과 ADR(Architecture Decision Record). edit: 수정 가능한 파일 목록. must_preserve: 소스 코드만으로는 드러나지 않는 보존해야 할 동작. checks: 실행해야 할 검증. 이 패킷은 코드처럼 버전 관리되고 리뷰된다. 핵심은 에이전트가 "근처에 있는 코드"를 기준으로 추론하지 않고, "명시된 계약"을 기준으로 작동하게 만드는 것이다. 검색 경계(retrieval boundary)를 정책으로 만들면 검사하고 개선할 수 있다.
에이전트 비용의 73%는 인풋이다: 컨텍스트 최적화가 곧 비용 최적화
Sentra의 분석은 컨텍스트 설계를 비용 문제로 치환해서 보여준다. 에이전트 5개, 하루 200회 호출, 호출당 입력 토큰 20,000개 기준으로 월 $4,125. 그 중 73%가 인풋 비용이다. 우버의 CTO가 AI 예산이 2026년 수개월 만에 소진됐다고 언급한 것도 이 맥락이다. 문제는 예산이 아니라 컨텍스트다.
비용을 낮추는 레버는 네 가지다. 프롬프트 캐싱: 안정적인 접두사를 90% 저렴하게 재전송. 단, 캐싱은 가격 레버이지 정확성 레버가 아니다. 지난달에 바뀐 정책도 오늘 아침에 바뀐 정책만큼 잘 캐싱된다. 모델 라우팅: 같은 플릿을 Claude Opus 5에서 Haiku 4.5로 전환하면 $4,125 → $825. 습관이 아닌 난이도 기준으로 라우팅해야 한다. 배치 처리: 비동기 허용 작업은 50% 할인. 컨텍스트 줄이기: 앞의 세 가지는 토큰 단가를 낮추지만, 이것만이 토큰 수 자체를 줄인다.
마지막 레버가 가장 중요하다. RAG로 4개 문서 ~7,000토큰을 던지는 것과, 교차 시스템 팩트를 한 번 해소해서 ~200토큰으로 제공하는 것의 차이. Sentra가 Terminal-Bench 2.1에서 측정한 결과, 작업 범위 메모리 레이어를 사용한 에이전트는 토큰 41% 감소, 비용 72% 절감, 그리고 정확도는 83.4% → 88.3%로 상승했다. 비용이 줄면서 품질도 올라간 이유는 '더 적지만 더 나은 컨텍스트' 메커니즘 덕분이다. 재시도가 줄고 세션이 짧아지는 효과가 겹친다.
이 분석이 도달하는 결론도 같다. 토큰맥싱(tokenmaxxing)이 아닌 컨텍스트맥싱(contextmaxxing). 에이전트가 매 세션마다 리포지토리를 처음부터 다시 읽는다면, 더 많은 일을 하는 게 아니라 같은 일을 더 비싸게, 그리고 노이즈가 더 많아서 약간 더 나쁘게 하고 있는 것이다.
세 관점이 합쳐질 때
실무 워크플로우, 아키텍처 패턴, 비용 최적화—세 편의 글이 도달하는 지점은 하나다. 에이전트에게 전달하는 컨텍스트는 설계의 대상이다. docs/plans/에 남긴 계획 문서는 Gabbs에게는 표류 방지 장치였고, Majdi의 컨텍스트 패킷 관점에서는 must_preserve 필드의 역할을 한다. Sentra의 프레임으로 보면 불필요한 컨텍스트 재생성을 막는 지식 레이어다.
프론트엔드 개발자로서 이 흐름을 받아들이는 방식은 이렇다. 에이전트가 컴포넌트를 뽑기 전에 어떤 디자인 시스템 토큰을 써야 하는지, 어떤 접근성 규칙이 있는지, 어떤 파일이 수정 범위인지를 계획 문서에 명시한다. 그 문서가 SKILL.md든 docs/plans/든 컨텍스트 패킷이든—형식보다 중요한 건 결정이 대화 밖에 존재해야 한다는 원칙이다. 대화는 잊혀지지만 파일은 남는다.
에이전트가 이상한 결과를 냈을 때 "AI라서 그렇다"로 끝내는 대신, "컨텍스트 설계의 어느 단계가 빠졌는가"로 질문을 바꾸는 순간—에이전트와의 협업은 예측 가능한 시스템이 된다.