AI 사전

기술이 아니라 계속 움직이는 이름입니다. ‘AI’는 모델이나 토큰처럼 고정된 대상을 가리키지 않습니다. 컴퓨터가 새롭게, 놀랍게 해내는 것이라면 무엇이든 가리킵니다. 지금은 대규모 언어 모델을 뜻합니다. 과거에는 전혀 다른 것을 가리켰습니다.

이 포인터는 때로 AI 효과라고 불리는 잘 알려진 메커니즘에 따라 움직입니다. 어떤 기술이 안정적으로 작동하기 시작하면 이름이 바뀝니다. ‘그냥’ 탐색, ‘그냥’ 통계가 되고, ‘AI’는 다음 미해결 문제로 넘어갑니다. 오래된 관찰입니다. Bertram Raphael은 1971년에 이렇게 표현했습니다. “AI는 컴퓨터로 아직 제대로 푸는 법을 모르는 문제를 통칭하는 이름이다.” Larry Tesler는 1979년경 이렇게 말했습니다. “지능이란 기계가 아직 하지 못한 모든 것이다.”

이 때문에 AI를 둘러싼 대화가 서로 엇갈리곤 합니다. “AI는 추론할 수 없다” 또는 “AI는 과대평가됐다” 같은 주장에는 숨은 시점이 있습니다. 전문가 시스템, 2010년대 이미지 분류기, 지난달의 LLM 중 무엇을 뜻하는지에 따라 전혀 다른 결론을 뒷받침할 수 있습니다. AI에 대한 논의가 막히면 보통 실제로 뜻하는 정확한 용어로 ‘AI’를 바꾸면 됩니다. 모델, 하네스, 에이전트, 제공된 컨텍스트 같은 말입니다.

피하기: 기술적 주장에서는 ‘AI’라는 말만 단독으로 쓰지 말고 뜻하는 구성 요소를 밝혀 주세요. 관행을 가리키는 ‘AI 코딩’은 괜찮지만 “AI가 환각을 일으킨다”라고만 하면 안 됩니다.

사용 예:

“CTO가 AI가 분류 대기열을 처리할 수 있는지 알고 싶어 합니다.”

“범위를 정하기 전에 뜻을 구체화하세요. 티켓 시스템에 접근할 수 있는 하네스의 LLM을 말하는군요. ‘AI’만으로는 명세가 되지 않습니다.”

---

매개변수입니다. 무상태형이며 다음 토큰 예측만 수행합니다. 다른 작업은 하지 않습니다. “Claude Opus 4.x”와 “GPT-5.x”는 모델입니다. 모델은 그 자체로 에이전트처럼 행동할 수 없습니다. 하네스에 연결되어야 합니다.

모델은 파일을 읽거나 명령을 실행하거나 웹을 탐색하거나 어제를 기억할 수 없습니다. 토큰을 입력받고 토큰을 예측하며, 한 번의 모델 제공자 요청마다 그 작업을 수행합니다. 에이전트가 일하는 듯 보이는 모든 행동, 즉 도구를 고르고 결과를 읽고 작업이 끝날 때까지 반복하는 일은 하네스가 여러 번의 예측을 연속으로 조정한 결과입니다.

모델 제공자는 여러 등급으로 모델을 제공합니다. 가장 똑똑하지만 느리고 비싼 대형 모델과 더 빠르고 저렴하지만 성능이 낮은 소형 모델이 있습니다. 등급 선택은 실제 판단이 필요한 문제입니다. 계획이나 어려운 디버깅에는 고성능 모델을, 기계적인 변경에는 가벼운 모델을 사용할 수 있습니다. 하네스에서는 세션 중간에 모델을 바꿀 수 있습니다.

이 단어를 엄격하게 사용하면 진단도 명확해집니다. “모델이 이 일을 못한다”는 구체적인 주장입니다. 같은 모델도 다른 하네스에서 또는 다른 컨텍스트를 사용하면 완전히 다르게 동작할 수 있습니다. 모델을 탓하기 전에 무엇을 받았는지 확인하세요. 실망스러운 출력의 대부분은 매개변수가 아니라 컨텍스트나 하네스에서 비롯됩니다.

사용 예:

“계획 단계에서는 모델을 Sonnet에서 Opus로 바꿔야 할까요?”

“시도해 보세요. 하지만 이 작업을 주로 처리하는 건 하네스입니다. 시스템 프롬프트와 도구가 잘못되어 있다면 모델을 바꿔도 도움이 되지 않습니다.”

---

모델 내부에 있는 숫자이며 흔히 수십억 개에 이릅니다. 훈련 중 조정됩니다. 모델이 “아는” 모든 내용이 이 숫자에 들어 있습니다. 훈련으로 설정되며 추론 중에는 그대로 사용됩니다. 가중치라고도 부릅니다.

기계적으로 매개변수는 입력을 출력으로 바꾸는 요소입니다. 다음 토큰 예측은 거대한 계산입니다. 컨텍스트 창의 토큰을 매개변수에 곱하고 다음 토큰을 예측합니다. 모델 안에는 사실 데이터베이스나 코드 조회표가 없습니다. 유용한 출력을 자주 만들어 내도록 배열된 숫자만 있습니다. 표준 라이브러리 API처럼 훈련 때부터 외워서 답할 수 있는 사실은 파라미터 지식입니다. 어딘가에서 검색한 정보가 아니라 매개변수에 저장되어 있습니다.

기억해야 할 점은 훈련 후 매개변수가 고정된다는 것입니다. 세션 중에 하는 어떤 일도 매개변수를 바꾸지 않습니다. 수정 지시나 보여 준 코드베이스, 모델이 배운 실수로도 바뀌지 않습니다. 모든 세션은 같은 숫자로 실행됩니다. 이것이 모델이 무상태형인 이유이자 내장 지식이 지식 컷오프에서 멈추는 이유이며 프로젝트별 정보가 컨텍스트를 통해 들어와야 하는 이유입니다. 매개변수를 바꾸는 유일한 방법은 추가 훈련이며, 사실상 다른 모델을 만들어 냅니다.

사용 예:

“코드베이스에 맞춰 파인튜닝할 수 있을까요?”

“매개변수가 바뀌므로 그 뒤에는 다른 모델이 됩니다. 프로젝트 하나를 위해서라면 보통 코드베이스를 컨텍스트로 불러오는 편이 재훈련보다 훨씬 저렴합니다.”

---

모델의 매개변수를 설정하는 과정입니다. 방대한 텍스트를 접하게 하고 다음 토큰 예측을 개선하도록 매개변수를 조정합니다. 모델 제공자가 한 번 수행하는 비용이 큰 과정입니다. 사전 훈련(대부분의 작업)과 사후 훈련(지시 따르기와 안전성 같은 후속 개선)을 모두 포함합니다. 이 사전의 수준에서는 둘을 구분할 필요가 없습니다.

규모를 키워 반복하는 방식입니다. 모델에 텍스트를 보여 주고, 다음 토큰을 예측하게 한 다음 실제 다음 토큰에 맞게 매개변수를 조정하고 수조 개의 토큰에 걸쳐 이를 반복합니다. 사실이나 규칙으로 저장하는 것은 없습니다. 모델이 “아는” 모든 내용은 예측 능력이 좋아지는 부산물로, 파라미터 지식 형태로 매개변수에 압축됩니다.

일상에서 중요한 결과는 두 가지입니다. 첫째, 훈련은 특정 시점에 끝나므로 모델에는 지식 컷오프가 있습니다. 지난달에 업그레이드한 라이브러리 버전은 보지 못했습니다. 둘째, 사용자가 직접 훈련할 수는 없습니다. 모델이 코드베이스나 관례, 내부 API를 모른다면 해결책은 “모델을 가르치는 것”이 아닙니다. 사용자가 제어할 수 있는 유일한 입력인 컨텍스트에 자료를 넣는 것입니다.

사용 예:

“내부 API를 알게 할 수 없나요?”

“훈련으로는 안 됩니다. 모델 제공자가 몇 달 동안 진행해야 하는 과정입니다. 대신 API 문서를 컨텍스트에 불러오세요. 실제로 사용자가 조절할 수 있는 지렛대는 그겁니다.”

---

출력을 생성하기 위해 훈련된 모델을 실행하는 과정입니다. 모든 모델 제공자 요청에서 일어납니다. 매개변수는 그대로이며 모델은 제공된 컨텍스트에 대해 다음 토큰 예측만 수행합니다. 훈련보다 비용이 저렴하지만 토큰마다 청구되며 모델 사용에서 주된 비용을 차지합니다.

모델의 생애는 두 단계로 나뉩니다.

추론 중에 하는 일은 매개변수에 기록되지 않습니다. 오늘 전달한 수정 지시가 내일 유지되지 않는 이유입니다. 해결 방법을 신중하게 설명했는데 다음 세션에서 같은 실수를 하는 모델은 사용자를 무시하는 것이 아닙니다. 대화에서 학습할 능력이 없습니다. 모델은 무상태형이며 연속성은 모델 밖, 즉 컨텍스트 창이나 메모리 시스템에서 제공해야 합니다.

이 메커니즘은 청구 방식도 설명합니다. 각 요청은 전체 컨텍스트를 대상으로 모델을 실행하므로 비용은 입력 토큰과 출력 토큰에 따라 증가합니다. 도구를 수십 번 호출하는 에이전트는 왕복할 때마다 추론 비용을 지불합니다. 따라서 컨텍스트 크기는 품질 문제인 동시에 비용 문제입니다.

사용 예:

“왜 정액 라이선스가 아니라 사용량에 따라 비용이 늘어나나요?”

“추론 비용을 내기 때문입니다. 모델 제공자 요청마다 제공자의 하드웨어에서 모델이 실행됩니다. 훈련은 이미 끝났지만 추론은 요청마다 비용이 들고, 도구를 호출하면 턴 하나가 여러 요청으로 늘어날 수 있습니다.”

---

추론 노력은 모델이 답하기 전에 얼마나 많이 추론할지 정하는 다이얼입니다. 모델 제공자 요청마다 설정하며, 모델이 사용자가 보는 답을 작성하기 전에 수행하는 사고 과정의 길이를 제어합니다. 이 사고 과정도 다른 내용과 마찬가지로 추론 시 생성됩니다. 하네스가 숨기는 경우가 많지만 모델이 실제로 수행하는 작업입니다.

노력을 높이면 비용과 시간이 늘어납니다. 추론은 토큰으로 출력되고 보이지 않더라도 출력 토큰으로 청구되며 한 번에 토큰 하나씩 생성됩니다. 따라서 노력을 높이면 답을 기다리는 시간이 길어지고 청구액도 늘어납니다. 속도와 비용을 더 들여 숙고를 늘리는 절충입니다.

대부분의 하네스는 노력을 몇 단계로 제공합니다.

잘못 설정하면 양쪽으로 문제가 생깁니다. 어려운 문제에 노력을 너무 낮게 설정하면 필요한 추론을 건너뛴 채 얕은 답을 자신 있게 내놓습니다. 읽기에는 그럴듯하지만 나중에 비용을 치르는 방식으로 틀립니다. 한 줄짜리 이름 변경에 최상을 설정하면 가장 낮은 설정으로도 얻었을 답을 위해 오래 생각하는 시간을 기다립니다.

세션이 아니라 작업에 맞춰 추론 노력을 설정하세요. 실제로 추론하기 어려운 부분은 높이고, 주변의 반복 작업은 낮추세요.

사용 예:

“동시성 수정이 계속 잘못돼서 세 번이나 다시 설명했어요.”

“추론 노력을 높이세요. 추론이 많이 필요한 버그인데 기본 설정에서는 접근법을 정하기 전에 충분히 생각하지 않는 것 같습니다.”

---

모델이 읽고 쓰는 가장 작은 단위입니다. 대략 단어 크기지만 정확히 일치하지는 않습니다. 흔한 단어는 토큰 하나이고 드물거나 긴 단어는 여러 토큰으로 나뉩니다. 컨텍스트 창의 크기와 비용, 지연 시간은 모두 토큰 단위로 계산합니다.

텍스트는 토크나이저를 거쳐 토큰으로 바뀝니다. 훈련 전에 학습한 수만 개의 조각으로 구성된 고정 어휘이며 입력을 어휘 항목의 순서로 나눕니다. 모델은 문자나 단어를 직접 보지 않습니다. 들어오는 모든 텍스트는 토큰으로 변환되고, 다음 토큰 예측은 나가는 내용을 한 번에 토큰 하나씩 생성합니다.

대략적인 기준으로 토큰 하나는 영어 단어의 4분의 3 정도이므로 토큰 1,000개는 약 750단어입니다. 코드는 예측하기가 더 어렵습니다. 흔한 키워드와 관용 표현은 간결하게 토큰화되지만 새로 만든 식별자, 해시, base64 문자열, 압축된 출력은 “단어”마다 토큰을 많이 차지합니다. 토크나이저의 학습 자료에 자주 나온 텍스트는 짧고 효율적으로 인코딩되고, 그렇지 않은 텍스트는 작은 조각 여러 개로 나뉩니다. `a3f9c2e1` 같은 해시는 어디에도 등장한 적이 없어 토큰 여러 개로 나뉘지만 `function`은 하나입니다. 그래서 드문 문자열이 가득한 작은 파일도 컨텍스트 창에서 예상보다 많은 공간을 차지할 수 있습니다.

토큰은 다른 모든 것을 측정하는 단위입니다. 비용은 토큰별로 발생하며 제공자는 입력 토큰과 출력 토큰을 따로 청구합니다. 출력은 한 번에 토큰 하나씩 생성되므로 속도는 초당 토큰 수로 표시합니다. 컨텍스트 창도 고정된 토큰 수로 정해지므로 파일의 토큰 수가 한 번에 담을 수 있는 양을 결정합니다.

피하기: “단어” — 토큰 경계는 단어 경계와 일치하지 않으며 초당 토큰 수와 토큰당 비용이 실제로 중요한 단위입니다.

사용 예:

“이 프롬프트는 얼마나 커질까요?”

“토크나이저로 확인하세요. 스키마는 간결하지만 JSON 키가 특이해서 생각보다 더 많은 토큰으로 나뉠 겁니다.”

---

모델이 실제로 하는 일입니다. 컨텍스트를 입력받아 다음 토큰 하나를 표본으로 고르고, 이를 추가한 다음 다시 실행합니다. 문장이나 도구 호출, 천 줄짜리 파일 등 모든 출력은 토큰을 한 번에 하나씩 생성해 만듭니다. 모델에는 다른 작동 방식이 없습니다.

각 단계는 같은 방식으로 진행됩니다. 컨텍스트 창에 있는 토큰을 매개변수에 통과시켜 어휘의 모든 토큰에 확률을 부여합니다. 이 토큰은 다음에 나올 가능성이 높고 저 토큰은 낮습니다. 해당 확률에서 토큰 하나를 표본으로 골라 추가하고, 조금 더 길어진 컨텍스트로 루프를 다시 실행합니다. 표본 추출 때문에 같은 프롬프트도 실행할 때마다 다른 출력이 나옵니다. 비결정성은 위에 덧붙은 버그가 아니라 메커니즘 안에 들어 있습니다.

이 메커니즘을 기억하면 이상해 보이는 동작을 설명할 수 있습니다. 모델은 토큰을 내보내기 전에 참인지 확인하지 않습니다. 그럴듯한지 확인할 뿐이며 이것이 환각의 근본 원인입니다. 토큰을 하나씩 순서대로 확정하므로 자신감 있게 시작한 문장이 답변 나머지의 방향을 잘못 이끌 수 있습니다. 또한 출력 토큰을 한 번에 하나씩 생성하므로 생성 속도에 따라 에이전트가 일할 수 있는 속도의 하한이 정해집니다.

사용 예:

“에이전트는 도구 호출을 어떻게 ‘결정’하나요?”

“결정하는 게 아닙니다. 처음부터 끝까지 다음 토큰 예측을 하는 겁니다. 도구 호출은 하네스가 출력 흐름에서 분석해 내는 구조화된 문자열일 뿐입니다.”

---

같은 입력으로 다른 출력을 얻을 수 있습니다. 모델에 같은 컨텍스트를 넣어 두 번 실행해도 답변이 다를 수 있습니다. 단어 하나만 다를 때도 있고 접근법이 완전히 달라지기도 합니다. 코드에서 아무것도 바꿀 필요 없이 이런 일이 생깁니다.

모델이 텍스트를 생성하는 방식과 모델 제공자가 요청을 처리하는 방식의 특성입니다. 추론 중 모델은 가능한 다음 토큰의 확률 분포를 만들고 그중 하나를 표본으로 선택합니다. 가장 가능성이 높은 토큰만 계속 고르면 반복적이고 품질이 낮은 텍스트가 되므로 보통 의도적으로 약간의 무작위성을 둡니다. 응답 초반에 다르게 표본으로 선택된 토큰 하나가 이후 토큰을 모두 바꿀 수 있습니다. 그래서 단어 하나의 차이가 접근법 전체를 바꿉니다. 제공자 측 처리도 변이를 더합니다. 요청은 공유 하드웨어에서 묶음으로 처리되며 묶음 사이의 아주 작은 부동소수점 차이가 비슷한 확률을 가진 토큰 중 무엇을 선택할지 바꿀 수 있습니다. 모든 변이를 없애는 스위치는 없습니다.

같은 작업을 맡긴 에이전트가 다양한 결과를 낸다고 예상하세요. 대부분의 응답은 품질 면에서 적당한 종형 곡선 안에 있으므로 비결정성을 감당할 수 있습니다. 하지만 양쪽 끝도 실제로 존재합니다. 어떤 날은 모델이 날카롭고 어떤 날은 요점을 놓친 것처럼 느껴질 수 있습니다. 같은 작업이라도 주사위를 다르게 굴린 결과입니다. 실질적인 결과는 두 가지입니다. 재시도는 정당한 전략입니다. 실패한 시도는 분포에서 한 번 뽑은 결과이며 같은 작업을 새로 시도하면 더 나은 결과를 얻을 수 있습니다. 또한 결정론적 도구를 쓸 때보다 검증이 더 중요합니다. 에이전트의 동작을 한 번 테스트했다고 같은 동작이 반복되리라 믿을 수 없으므로 자동 검사가 나쁜 결과를 잡아야 합니다.

이 현상에 지나치게 이야기를 덧붙이지 마세요. 사람은 패턴을 찾는 데 능숙하므로 실패가 이어지면 “이번 주 모델이 나빠졌다”는 증거처럼 느껴질 수 있습니다. 대개는 분포의 결과일 뿐입니다.

사용 예:

“오늘 Claude가 너무 형편없어요. 더 나쁜 버전을 출시했나요?”

“아마 아닐 겁니다. 모델 출력은 비결정적입니다. 같은 작업에서도 잘되는 날과 안 되는 날이 있습니다. 원인을 찾기 전에 내일 다시 시도해 보세요.”

---

추론을 위해 모델에 서비스를 제공하는 주체입니다. 보통 원격 서비스(Anthropic, OpenAI, Google)이지만 로컬일 수도 있습니다. 자신의 컴퓨터에서 실행하는 Ollama, LM Studio, llama.cpp 등이 있습니다. 하네스가 직접 모델을 실행하지 않고 제공자에게 요청합니다.

제공자는 인프라를 소유합니다. 매개변수는 제공자 하드웨어에 있고, 모든 모델 제공자 요청에서 하네스가 네트워크로 토큰을 보내 예측 결과를 받습니다. 그래서 모델이나 하네스의 문제로 잘못 여겨지는 여러 유형의 문제는 제공자 쪽에서 비롯됩니다. 요청 제한, 처리 용량 저하, 장애가 여기서 발생합니다. 에이전트가 세션 중간에 멈추거나 모든 턴에서 오류가 나면 먼저 제공자의 상태 페이지를 확인할 만합니다.

제공자는 상업 조건도 정합니다. 입력과 출력 토큰의 토큰별 요금, 접두사 캐시 할인, 이용 가능한 모델을 결정합니다. 제공자와 모델 제작사는 서로 다른 회사일 수 있습니다. Bedrock, Vertex, OpenRouter는 다른 회사의 모델을 제공합니다.

로컬 제공자는 제어력을 얻는 대신 성능을 양보합니다. 자체 하드웨어에 맞는 모델은 최첨단 모델보다 훨씬 작지만 기기 밖으로 데이터가 나가지 않고 토큰마다 청구되지도 않습니다.

사용 예:

“인터넷이 차단된 고객 환경에서 오프라인으로 실행할 수 있나요?”

“모델 제공자를 로컬 제공자로 바꾸세요. 고객 장비에서 Ollama나 llama.cpp를 쓰면 됩니다. 하네스는 신경 쓰지 않습니다. 다른 엔드포인트를 호출할 뿐입니다.”

---

모델을 에이전트로 만들어 주는 주변의 모든 것입니다. 도구, 시스템 프롬프트, 컨텍스트 창 관리, 권한, 훅 등이 있습니다. Claude.ai와 Claude Code는 같은 모델을 사용하지만 하네스가 달라 서로 다르게 동작합니다.

모델은 텍스트를 입력받고 텍스트를 출력하는 한 가지 일만 합니다. 파일을 읽거나 명령을 실행하거나 직전 턴을 기억할 수 없습니다. 그 모든 기능은 하네스가 제공합니다. 각 모델 제공자 요청에 필요한 컨텍스트를 구성하고, 모델이 요청한 도구 호출을 실행하며, 도구 결과를 다시 입력하고, 세션 기록을 저장하고, 위험한 동작 전에 권한을 묻고, 언제 압축할지 결정합니다. 모델이 제안하고 하네스가 실행하는 에이전트 루프를 하네스가 운영합니다.

문제를 진단할 때 중요합니다. 두 제품 사이에 또는 어제와 오늘 사이에 동작이 달라져도 변수는 모델이 아니라 하네스일 때가 많습니다. 다른 시스템 프롬프트, 다른 도구 집합, 바뀐 권한 기본값, 새로운 컨텍스트 관리 전략은 모델이 그대로여도 동작을 바꿉니다. 설정의 대부분이 하네스에 있다는 뜻이기도 합니다. AGENTS.md 파일과 권한 설정, 훅은 모두 모델이 아니라 하네스에 주는 지시입니다.

예: Claude Code, Cursor, Codex CLI, 그리고 코딩용이 아니라 채팅용 하네스인 Claude.ai.

사용 예:

“같은 모델인데 Claude Code는 왜 파일을 편집하고 Claude.ai는 질문에 답만 하나요?”

“하네스가 다르기 때문입니다. Claude Code에는 파일 시스템 도구와 다른 시스템 프롬프트, 권한 계층이 있습니다. 여기서는 모델이 변수가 아닙니다.”

---

하네스와 모델 제공자 사이의 왕복 한 번입니다. 하네스가 현재 컨텍스트를 보내고 제공자가 하나의 응답(도구 호출 또는 최종 답변)을 돌려줍니다. 에이전트가 도구를 호출하면 사용자 메시지 하나가 여러 모델 제공자 요청을 시작할 수 있습니다. 도구 결과마다 다음 요청이 발생합니다.

각 요청에는 모든 내용이 들어갑니다. 시스템 프롬프트, 지금까지의 전체 대화, 모든 도구 결과가 포함됩니다. 모델은 무상태형이므로 제공자는 요청 사이에 아무것도 보관하지 않습니다. 40번째 요청에는 39번째 요청의 내용에 도구 결과 하나를 더해 다시 보냅니다. 반복 비용을 줄이기 위해 접두사 캐시를 사용합니다.

요청은 청구 단위이기도 합니다. 입력 토큰과 출력 토큰, 캐시 할인은 모두 요청마다 계산됩니다. 그래서 평범해 보이는 질문도 예상보다 큰 비용을 낼 수 있습니다. 비용은 메시지 크기에 비례하지 않고 요청 횟수와 각 요청이 전달하는 컨텍스트 크기의 곱에 비례합니다.

요청을 턴과 구별해야 합니다. 턴은 사용자와 한 번 주고받는 일이지만 “실패하는 테스트를 고쳐 주세요”라는 턴 하나가 다음과 같은 요청의 연쇄로 진행될 수 있습니다.

한 턴에 요청 여섯 번이 발생하며 매번 전체 컨텍스트를 다시 보냅니다. 토큰이 어디에 쓰였는지 궁금하면 턴이 아니라 요청을 세세요.

사용 예:

“질문 하나에 토큰 4만 개가 들었어요?”

“도구 호출을 보세요. grep 12회, 읽기 8회, 편집 4회입니다. 도구 결과마다 모델 제공자 요청이 또 생기고 세션의 전체 접두사가 매번 다시 전송됩니다.”

---

각 모델 제공자 요청에서 하네스가 보내는 토큰입니다. 시스템 프롬프트와 대화 기록, 도구 결과 등 모델이 출력하기 전에 읽는 모든 내용이 포함됩니다. 처리 비용이 출력 토큰보다 낮으므로 더 낮은 요율로 청구됩니다.

AI 코딩에서는 입력 토큰이 청구액의 대부분을 차지합니다. 모델은 무상태형이므로 매 턴마다 전체 세션을 입력으로 다시 보냅니다. 첫 메시지부터 그동안의 응답과 모든 도구 결과까지입니다. 50번째 턴의 입력에는 앞선 49턴이 포함됩니다. 모델 제공자 요청 하나는 출력 토큰 수백 개만 생성하면서도 누적된 기록에서 입력 토큰 100,000개를 다시 보낼 수 있습니다.

접두사 캐시는 이전 요청과 정확히 일치하는 기록을 정가 입력 대신 저렴한 캐시 토큰으로 청구해 비용을 줄입니다. 입력 비용이 여전히 부담되면 다시 전송하는 양을 줄이세요. 작업 사이에 초기화하거나 압축하면 됩니다.

사용 예:

“에이전트는 거의 아무것도 쓰지 않는데 청구액이 커요.”

“입력 토큰 때문입니다. 매 턴마다 전체 세션을 다시 보냅니다. 접두사 캐시가 없으면 매 요청에서 기록 비용을 다시 지불하게 됩니다.”

---

모델이 생성해 돌려주는 토큰입니다. 생성에 연산이 더 많이 필요하므로 입력 토큰보다 높은 요율, 보통 약 5배로 청구됩니다.

모델이 작성하는 모든 내용이 포함됩니다. 사용자가 읽는 산문과 코드, 도구 호출, 답변 전에 수행하는 확장 추론까지 모두 셉니다. 마지막 항목은 종종 놀라움을 줍니다. 추론 토큰은 하네스가 사용자에게 보여 주지 않는 경우에도 출력 토큰으로 청구되며 추론 노력을 높이면 더 많이 사용합니다.

출력 토큰은 세션의 속도도 좌우합니다. 모델은 입력을 빠르게 읽지만 출력은 토큰 하나씩 생성하므로 턴이 느리다고 느껴지면 입력을 읽는 시간보다 출력 작성 시간이 원인인 경우가 거의 항상 많습니다. 오래 기다린다면 긴 답변이 나올 가능성이 큽니다.

사용 예:

“입력은 작은데 리팩터링 세션에서 크레딧이 계속 소진돼요.”

“에이전트가 패치 대신 파일 전체를 다시 쓰고 있네요. 출력 토큰은 입력 요금의 약 5배입니다. 변경 사항만 내보내게 하면 청구액이 줄어듭니다.”

---

연속된 모델 제공자 요청에서 공통 접두사를 다시 처리하지 않도록 하는 모델 제공자 측 저장소입니다. 새 요청의 시작이 최근 요청과 일치할 때, 즉 같은 시스템 프롬프트와 어떤 지점까지의 같은 이력이 있을 때 제공자는 이전 작업을 재사용하고 해당 토큰을 훨씬 낮은 요율의 캐시 토큰으로 청구합니다.

세션은 추가만 가능한 형태로 커지므로 캐시가 효과를 냅니다. 매 요청은 전체 이력을 입력 토큰으로 다시 전송하고(자세한 이유는 해당 항목 참조), 일반적인 세션에서는 이력이 끝부분에서만 바뀝니다. 각 요청은 이전 요청에 새 메시지 몇 개를 더한 형태입니다. 제공자는 긴 공통 시작 부분을 한 번 처리해 저장한 다음 접두사가 끝난 지점에서 이어 갑니다. 캐시가 없다면 턴 50회의 세션에서 첫 턴을 50번 다시 처리하는 비용을 내야 합니다.

캐시도 만료됩니다. 항목이 유지되는 시간은 모델 제공자마다 다르며 보통 몇 시간보다 몇 분에 가깝습니다. 세션을 캐시 유효 기간보다 오래 쉬게 두면 다음 요청에서 접두사 전체를 정가로 다시 만들고, 그 뒤에 캐시가 재개됩니다. 이는 주로 하네스 개발자가 신경 쓸 부분입니다. 사용자에게 보이는 결과는 오래 쉰 뒤의 요청이 쉬기 전보다 비싸다는 점입니다.

사용 예:

“왜 세션 중간에 청구액이 급증했죠?”

“하네스가 매 턴 시스템 프롬프트에 현재 시각을 넣기 시작했어요. 첫 토큰이 바뀌면서 접두사 캐시가 끊겼고, 그 뒤의 모든 요청이 정가로 청구됐습니다.”

---

이전 모델 제공자 요청에서 제공자가 캐시해 다시 처리하지 않아도 되는 입력 토큰입니다. 연속된 요청이 접두사를 공유하면 제공자는 접두사 캐시로 작업을 재사용하고 캐시된 부분을 훨씬 낮은 요율로 청구합니다. 긴 세션을 감당할 수 있게 하는 지렛대입니다. 캐시가 없으면 모든 턴에서 전체 기록 비용을 다시 냅니다.

세션의 청구 방식 때문에 중요합니다. 모델은 무상태형이므로 모든 요청에서 전체 대화를 입력 토큰으로 다시 보냅니다. 시스템 프롬프트, 메시지 전체, 모든 도구 결과가 포함됩니다. 50번째 턴에는 각 요청이 이전 49턴의 기록을 싣고 있고 매번 그 전부를 정가로 내야 합니다. 캐시는 계산을 바꿉니다. 제공자가 동일한 접두사로 이미 처리한 토큰은 입력 요금의 10분의 1 이하인 경우가 많은 캐시 토큰 요율로 청구됩니다. 긴 세션에서 보내는 대부분은 캐시 토큰이 되어 비용이 합리적인 수준에 머뭅니다.

토큰이 캐시되는 경우와 그렇지 않은 경우를 예로 살펴보겠습니다. 각 문자는 대화 내용의 한 묶음이며 요청마다 지금까지의 대화를 모두 보냅니다.

캐시는 정확한 접두사에만 일치하는 방식으로 민감합니다. 하네스가 내용을 재정렬하거나 타임스탬프가 바뀌거나 파일 표현이 달라지는 등 대화 초반부가 바뀌면 해당 지점부터 캐시가 적중하지 않고 그 뒤의 모든 내용이 입력 정가로 청구됩니다. 몇 분 동안 활동이 없어도 캐시가 만료되므로 오래 멈춘 세션을 다시 시작하면 기록 비용을 한 번 더 냅니다. 뚜렷한 이유 없이 세션 비용이 급증하면 사용량 보고서에서 캐시 토큰과 입력 토큰을 비교하세요. 캐시가 깨졌다면 이 지표에서 먼저 드러납니다.

사용 예:

“긴 세션 비용이 너무 큽니다. 리팩터링 한 번에 8달러예요.”

“캐시 토큰을 확인하세요. 턴마다 하네스가 시스템 프롬프트나 파일 순서를 바꾸면 접두사가 깨져 요청마다 입력 정가를 다시 냅니다.”

---

정보를 다음으로 이어 가지 않습니다. 모델은 모델 제공자 요청 사이에서 무상태형입니다. 다른 정보를 볼 방법이 없으므로 요청마다 전체 컨텍스트 창을 다시 전송합니다. 에이전트는 기본적으로 세션 간 무상태형입니다. 새 세션은 이전 세션의 흔적 없이 빈 상태로 시작합니다. 상태 저장형과 반대되는 개념입니다.

모델 자체는 영구적으로 무상태형입니다. 훈련 후 매개변수는 고정되며 추론 중에 하는 어떤 행동도 매개변수를 바꾸지 않습니다. 모델은 사용자의 수정 지시를 학습하거나 어제 같은 내용을 들었다는 사실을 기억하지 않으며, 대화가 아무리 그렇게 느껴져도 사용자에게 익숙해지지 않습니다. 세션 중 연속성은 기록을 유지하고 매 요청에 다시 보내는 하네스가 만들어 냅니다. 모델은 대화를 기억하는 것이 아니라 다시 읽습니다.

실질적인 결과는 세션 간에 기억해야 할 내용을 에이전트가 다시 읽을 수 있는 곳에 기록해야 한다는 점입니다. AGENTS.md 파일과 메모리 시스템, 인계 산출물이 그런 용도입니다. 모델이 갖지 못한 기억을 대신하도록 이후 세션의 컨텍스트에 불러오는 파일입니다. 이전에 고치라고 한 실수를 에이전트가 계속 반복한다면 왜 학습하지 않았는지 물을 일이 아닙니다. 학습할 수 없으니까요. 앞으로 시작할 모든 세션이 그 수정 내용을 읽도록 어디에 기록할지 정해야 합니다.

사용 예:

“매번 초기화할 때마다 왜 관례를 잊나요?”

“모델은 무상태형이라 새 세션이 빈 상태로 시작합니다. 내용을 이어 가려면 AGENTS.md나 하네스가 세션 시작에 불러오는 메모리 파일에 적어 두세요.”

---

지금 에이전트가 이용할 수 있는 관련 정보입니다. 모델이 보는 원시 입력(컨텍스트 창)도 아니고 실행 중인 기록(세션)도 아닙니다. 작업과 관련해 에이전트가 알고 있는 내용을 추상적으로 가리킵니다. “컨텍스트에 무언가를 불러온다”는 말은 이를 해당 정보 집합에 추가한다는 뜻입니다. “컨텍스트 엔지니어링”은 이 집합을 선별하는 작업입니다.

세 용어는 다음과 같이 구분됩니다.

이 구분이 중요한 이유는 컨텍스트가 양이 아니라 품질의 척도이기 때문입니다. 컨텍스트 창이 거의 가득 차도 오래된 도구 출력 수천 토큰만 있고 현재 작업과 관련된 내용이 하나도 없다면 컨텍스트는 나쁠 수 있습니다. 반대로 창이 거의 비어 있어도 작업의 성패를 좌우하는 타입 정의 하나만 있다면 컨텍스트는 훌륭할 수 있습니다.

일상적인 실패는 대부분 컨텍스트에서 비롯됩니다. 에이전트가 API를 지어내거나 결정을 뒤집거나 스키마를 추측하면 가장 먼저 당시 컨텍스트에 무엇이 있었는지 물어보세요. 보통 관련 사실을 불러오지 않았거나 주의력 저하로 묻혀 있었습니다. 해결책은 선별입니다. 작업에 필요한 내용은 불러오고 필요하지 않은 것은 제외하세요.

사용 예:

“타입에 없는 필드를 계속 지어내요.”

“타입 파일이 컨텍스트에 없어서 호출부만 보고 추측하는 겁니다. 타입 정의를 읽어 오세요.”

---

모델이 각 모델 제공자 요청에서 보는 모든 것입니다. 용량은 한정되어 있고 모델마다 다르며, 모델이 무엇이든 인식하는 유일한 표면입니다.

토큰이 하나의 순서로 이어집니다. 시스템 프롬프트, 지금까지의 대화, 하네스가 되돌려 준 모든 도구 결과가 포함됩니다. 그 순서에 들어 있는 것은 모델이 사용할 수 있습니다. 빠져 있으면 존재하는지도 알지 못합니다. 코드베이스, 어제 편집한 파일, 세 세션 전에 내린 지시도 마찬가지입니다. 창 밖의 내용이 영향을 주려면 보통 도구 호출 등을 통해 먼저 안으로 가져와야 합니다.

용량이 한정되어 있으므로 결국 가득 찹니다. 매 턴 사용자의 메시지와 모델의 응답, 도구 결과가 더해지고 긴 세션은 결국 한계에 도달해 압축 또는 초기화를 해야 합니다. 또한 창 안의 모든 내용은 서로 경쟁합니다. 토큰을 하나 불러올 때마다 나머지에 쓸 수 있는 양이 하나 줄어들고, 필요하지 않은 내용도 모델의 주의력을 차지합니다. 실질적으로는 창을 예산으로 다뤄야 합니다. 작업에 필요한 내용만 불러오고 나머지는 제외하세요.

피하기: “메모리” — 컨텍스트 창은 작업 상태이며 세션 간에 유지되지 않습니다. 메모리는 그 위에 별도로 추가되는 개념입니다.

사용 예:

“모노레포 전체를 프롬프트에 붙여 넣으면 안 되나요?”

“컨텍스트 창은 토큰 200k입니다. 저장소의 5분의 1 정도에 불과합니다. 작업과 관련된 파일을 고르고 나머지는 도구 호출 뒤에 두세요.”

---

정보를 다음으로 이어 갑니다. 세션은 턴에 걸쳐 상태를 유지합니다. 세션이 진행되면서 컨텍스트가 누적되므로 긴 세션은 멍청한 구간으로 흘러갑니다. 메모리 시스템을 추가해 정보를 환경에 저장하고 다음 세션이 시작될 때 다시 불러오면 에이전트의 상태도 여러 세션에 걸쳐 유지할 수 있습니다. 모델은 상태 저장형이 될 수 없습니다. 겉보기의 연속성은 하네스가 컨텍스트를 다시 제공한 결과입니다. 무상태형과 반대되는 개념입니다.

계층별 상태는 다음과 같습니다.

각 계층의 상태 저장은 바로 아래 계층에 저장된 내용을 다시 읽음으로써 만들어집니다. 하네스가 메시지 기록을 무상태형 모델에 다시 보내므로 세션이 이어지는 것처럼 느껴집니다. 하네스가 환경의 파일을 다시 불러오므로 에이전트가 여러 세션에 걸쳐 기억하는 것처럼 보입니다. 모델 자체에는 어떤 상태도 저장되지 않습니다.

상태를 항상 유지하고 싶은 것은 아닙니다. 앞서 이어진 모든 내용은 다음 작업에 영향을 주므로 세션 초기에 내린 잘못된 가정도 계속 이어집니다. 초기화는 세션 상태를 의도적으로 버리고 기록된 내용에서 다시 시작하는 방법입니다.

사용 예:

“어제 말한 설정을 기억하던데, 모델이 학습했다는 뜻인가요?”

“아니요. 하네스가 설정을 메모리 파일에 기록하고 세션 시작 때 다시 불러왔기 때문에 에이전트가 상태를 유지한 겁니다. 모델 자체는 어제 내용을 전혀 보지 못했어요.”

---

도구, 시스템 프롬프트, 컨텍스트 창을 갖춘 하네스에 연결되어 사용자와 턴을 주고받는 모델입니다. Claude Code도 에이전트이고, Cursor도 에이전트이며, Claude.ai도 에이전트입니다. 실제로 대화하는 대상, 즉 특정 목적에 맞게 설정되어 작동 중인 모델을 에이전트라고 합니다.

이 사전의 다른 용어와 달리 ‘에이전트’는 기계적인 구성 요소의 이름이 아닙니다. 모델은 매개변수 파일이고, 하네스는 지정해 사용할 수 있는 소프트웨어입니다. 에이전트는 그 둘 중 어느 쪽도 아닙니다. 우리가 대화하는 단위입니다. 사람들은 AI를 늘 의인화하며, 에이전트는 의인화의 대상입니다. 일을 맡기는 대상이고, 메시지를 읽고 답하는 대상이며, “또 빌드를 망가뜨렸어”에서 ‘그것’에 해당합니다. 에이전트가 무언가를 했다고 말할 때는 모델과 하네스가 함께 수행했다는 뜻이지만, 이 조합을 하나의 행위자로 부르는 것입니다.

이 개념은 최근 AI 흐름보다 오래됐습니다. 목표를 위임하면 사람을 대신해 행동하는 프로그램인 소프트웨어 에이전트는 AI가 등장한 만큼 오래된 개념입니다.

피하기: “AI”, “봇” (너무 모호해서 매개변수를 뜻하는지 하네스에 연결된 대상을 뜻하는지 알 수 없습니다.)

사용 예:

“마이그레이션에는 어떤 에이전트를 쓰고 있나요?”

“로컬에서는 Claude Code, UI 작업에는 Cursor를 씁니다. 내부 모델은 같고 하네스는 다릅니다.”

---

하네스가 모든 모델 제공자 요청에 앞서 넣는 지침입니다. 에이전트를 위한 상시 브리프이며 에이전트의 정체와 행동 방식, 호출할 수 있는 도구, 따라야 할 관례를 설명합니다. 보통 세션 내내 안정적으로 유지됩니다.

시스템 프롬프트는 사용자가 아니라 하네스 제공자가 작성합니다. 코딩 하네스에서는 규모가 큽니다. 행동 규칙과 도구 설명, 예외 처리 등 토큰을 수만 개 담을 수 있으며 매 턴마다 입력 토큰으로 청구됩니다. 사용자의 상시 지침도 함께 들어갑니다. AGENTS.md 같은 파일은 세션이 시작될 때 시스템 프롬프트 옆에 불러오므로 모델은 사용자의 메시지를 보기 전에 제공업체의 브리프와 사용자 지침을 함께 읽습니다.

모든 요청에서 동일하므로 접두사 캐시의 시작 부분이 됩니다. 이것이 하네스가 세션 중간에 시스템 프롬프트를 계속 편집하지 않고 세션 전체에서 고정하는 이유 중 하나입니다.

모델은 사용자 메시지보다 시스템 프롬프트를 우선하도록 훈련됩니다. 그래서 요청하지 않은 관례를 에이전트가 고집하거나 바꿀 수 없는 형식으로 출력을 내놓는다면 대개 시스템 프롬프트를 따르는 것입니다. 사용자의 메시지가 그 지침과의 논쟁에서 밀리는 셈입니다. 일부 하네스는 사용자 설정을 허용해 시스템 프롬프트를 직접 읽고 실제로 에이전트가 어떤 지시를 받는지 확인하거나 내용을 바꿀 수 있습니다.

사용 예:

“하네스는 두 개고 모델은 같은데 같은 프롬프트에서 동작이 완전히 달라요.”

“시스템 프롬프트가 다릅니다. 하나는 간결한 코드 편집에 맞춰졌고 다른 하나는 설명에 맞춰졌습니다. 차이는 사용자의 메시지가 도착하기 전부터 생깁니다.”

---

에이전트와 상호작용하는 한 번의 범위 있는 작업 단위입니다. 빈 상태에서 시작해 메시지와 도구 결과, 읽은 파일을 쌓다가 초기화하거나 닫거나 새 세션으로 압축하면 끝납니다. 컨텍스트 창을 실제로 채우는 것은 세션입니다. 컨텍스트 창이 상자라면 세션은 상자 안에 서서히 쌓이는 내용물입니다. 컨텍스트 창 하나보다 큰 작업은 여러 세션으로 나눠야 합니다.

세션의 메시지 기록이 에이전트의 작업 메모리입니다. 모델은 무상태형이므로 기억하는 것처럼 보이는 모든 내용, 예를 들어 사용자의 요청, 테스트 결과, 세 턴 전에 내린 결정은 메시지 기록에 있으며 매 모델 제공자 요청마다 다시 전송됩니다. 세션에 없는 내용은 에이전트에게 존재하지 않습니다.

이 메모리는 세션과 함께 끝납니다. 새 세션은 아무것도 없는 상태에서 시작합니다. 어제 세션이 끝날 무렵 코드베이스를 잘 알던 에이전트는 오늘 아침에는 아무것도 모릅니다. 살아남는 것은 파일 시스템입니다. 한 세션에서 쓴 파일을 다음 세션이 읽을 수 있으며, 작업 인계와 메모리 시스템, AGENTS.md가 이 방식을 이용합니다.

세션이 언제 끝나는지는 사용자가 결정합니다. 세션 안의 모든 내용은 이후의 모든 턴에 영향을 주므로 서로 무관한 작업을 한 세션에서 하면 다음 답변에 흔적이 남습니다. 세션마다 작업 하나를 하면 컨텍스트가 작업과 관련된 내용으로 유지되고, 작업 완료가 초기화하기 좋은 시점이 됩니다.

사용 예:

“한 세션을 얼마나 오래 실행해야 망가지기 시작하나요?”

“작업에 따라 달라요. 집중된 리팩터링은 열린 결말의 조사보다 더 오래 예리함을 유지합니다. 세션이 비대해지면 억지로 계속하지 말고 인계하거나 압축하세요.”

---

사용자 메시지 하나와 에이전트가 응답하는 과정 전체를 포함하며 사용자에게 제어권을 돌려줄 때 끝나는 단위입니다. 하나 이상의 모델 제공자 요청을 포함하며 도구를 호출하는 경우에는 여러 요청이 됩니다. 설명을 묻는 질문을 하면 현재 턴이 끝나고 사용자의 답변과 함께 다음 턴이 시작됩니다. 계층은 세션 > 턴 > 모델 제공자 요청입니다.

턴을 별도로 부르는 이유는 길이를 결정하는 것이 사용자가 아니라 에이전트이기 때문입니다. 사용자는 메시지 하나를 맡기고 에이전트는 사용자에게 돌아오기 전에 도구 호출을 몇 번 이어서 할지 결정합니다. 턴은 한 문장 답변으로 끝날 수도 있고 20분 동안 읽고, 편집하고, 테스트를 실행할 수도 있습니다. 이 한 가지 특징을 서로 다른 각도에서 볼 수 있습니다. 긴 턴은 자리 비움 작업을 가능하게 하지만, 감독 없이 문제가 생기는 지점도 긴 턴입니다. 에이전트가 돌아올 때쯤이면 사용자가 의도한 것에서 크게 벗어나 있을 수 있습니다.

턴은 방향을 조정하기에도 자연스러운 단위입니다. 턴 안의 모든 일은 사용자 없이 진행되고, 턴 사이의 간격에 방향을 바꿀 수 있습니다. 대부분의 하네스는 이를 완화합니다. 턴 중간에 에이전트를 멈추고 방향을 바꾸거나, 작업 중 메시지를 입력해 턴이 끝났을 때 읽게 할 수 있습니다. 턴이 자꾸 원치 않는 결과로 끝난다면 보통 더 작은 턴을 요청하는 것이 해결책입니다. 먼저 계획을 세우고 한 단계씩 진행해 자율성을 조금 낮추는 대신 방향을 잡을 기회를 더 자주 만드세요.

사용 예:

“턴 하나에 2분이나 걸렸나요?”

“그 턴 안에서 도구 호출을 14번 했습니다. 각각 별도의 모델 제공자 요청이므로 에이전트가 사용자에게 돌아오기 전에 지연이 쌓입니다.”

---

에이전트가 행동하는 세계, 즉 하네스 바깥에 있으면서 에이전트가 도구 결과를 통해 인식하고 도구 호출로 변경하는 모든 것입니다. 하네스는 에이전트를 실행하고 환경은 에이전트가 작업하는 공간입니다. `AGENTS.md` 같은 파일은 환경에 있고, 하네스는 이를 컨텍스트 창에 불러옵니다. 파일 시스템이 가장 흔한 환경이지만 유일한 환경은 아닙니다. 데이터베이스, 원격 API, 브라우저 세션도 환경이 될 수 있습니다.

에이전트는 환경을 살펴볼 때만 환경을 봅니다. 환경에 대해 아는 모든 내용은 도구 결과로 들어오므로, 각 내용은 확인 당시에는 정확했던 스냅샷의 모음입니다. 에이전트가 읽은 뒤 파일이 바뀌면, 사용자가 직접 편집했거나 빌드 단계에서 다시 생성했더라도 에이전트는 다시 읽으라는 신호를 받을 때까지 오래된 복사본을 바탕으로 계속 추론합니다. 더 이상 그렇지 않은 파일을 자신 있게 설명하는 에이전트는 대개 환경은 바뀌었지만 스냅샷은 그대로인 경우입니다.

환경은 지속되는 계층이기도 합니다. 항상 상태 저장형으로 남는 유일한 계층입니다. 세션이 끝나면 세션의 컨텍스트는 사라지지만 환경에 쓴 파일은 다음 세션이 읽을 때까지 남습니다. 메모리 시스템과 인계 산출물, `AGENTS.md`가 이 점에 의존합니다. 에이전트가 내일도 알아야 할 내용은 환경에 저장해야 합니다.

환경의 크기는 사용자가 정합니다. 샌드박스는 에이전트가 접근할 수 있는 범위를 제한해 환경을 축소하고, 도구를 추가하면 데이터베이스나 API에 접근하도록 범위를 넓힙니다. 경계 안의 내용은 에이전트가 인식하고 변경할 수 있으며, 경계 밖의 것은 에이전트에게 존재하지 않습니다. 에이전트가 잘 작업하도록 환경을 얼마나 잘 구성했는지가 코드베이스의 AX입니다.

피하기: 런타임이나 하네스 자체를 “환경”이라고 부르지 마세요. 하네스는 래퍼이고 환경은 작업 공간입니다.

사용 예:

“에이전트가 스테이징 DB 스키마를 볼 수 없어요.”

“환경에 연결하세요. 스테이징에 읽기 전용으로 제한한 `psql` 도구를 제공하세요. 하네스는 괜찮고, 행동할 수 있는 대상이 없는 겁니다.”

---

에이전트가 읽고 쓰고 실행하는 파일과 디렉터리의 트리입니다. 코딩 에이전트의 기본 환경 형태입니다. AGENTS.md, 스킬, 소스 코드, 빌드 스크립트, 도구 설정이 모두 파일 시스템에 있습니다. 하네스가 “프로젝트에서 시작한다”는 말은 에이전트를 파일 시스템으로 연결한다는 뜻입니다.

에이전트는 도구 호출로만 파일 시스템을 다룹니다. 파일 읽기, 파일 쓰기, 셸 명령 실행 등이 여기에 해당합니다. 도구 호출로 불러오기 전까지 디스크의 내용은 컨텍스트 창에 들어오지 않습니다. 그래서 파일 시스템에 모든 것이 있고 현재 작업에서 읽은 내용만 컨텍스트에 담을 수 있어 에이전트가 컨텍스트 창보다 훨씬 큰 저장소에서도 작업할 수 있습니다. 일부 하네스는 기본적으로 현재 디렉터리의 파일 이름을 내용 없이 트리 형태로 불러옵니다. 이는 컨텍스트 포인터처럼 작동합니다. 에이전트는 무엇이 있는지 확인하고 필요한 파일을 읽습니다.

파일 시스템은 사용자와 공유됩니다. 에이전트가 수정하는 파일은 사용자가 편집기에서 열고 Git diff로 확인하는 파일과 같습니다. 에이전트가 한 일을 검토하는 공동 작업 공간입니다.

사용 예:

“왜 AGENTS.md를 읽어오지 않죠?”

“다른 파일 시스템에서 실행 중입니다. 샌드박스가 프로젝트 루트가 아니라 상위 디렉터리를 마운트했네요. 하네스가 바라보는 경로를 바꾸세요.”

---

하네스가 에이전트에 제공하는 호출 가능한 함수입니다. Read, Write, Bash, Search 등이 있습니다. 도구를 통해 에이전트는 환경을 인식하고 조작합니다. 도구 결과 없이는 환경을 볼 수 없고 도구 호출 없이는 환경을 바꿀 수 없습니다. 결과를 모델로 돌려보내 다음 행동을 결정하게 해야 하므로 도구 호출마다 모델 제공자 요청이 한 번 더 발생합니다.

대부분의 코딩 에이전트에 기본 제공되는 도구는 다음과 같습니다.

도구는 이름, 기능 설명, 매개변수 스키마의 세 가지로 정의됩니다. 하네스는 요청을 보낼 때마다 이 정의를 모델에 전달하고, 모델은 다른 내용을 생성할 때와 마찬가지로 토큰을 써 구조화된 인수 호출을 작성해 도구를 선택합니다. 모델이 직접 실행하는 일은 없습니다. 하네스가 호출을 읽고 함수를 실행한 뒤 결과를 돌려줍니다.

도구 목록이 에이전트가 할 수 있는 일을 정합니다. 성능 좋은 모델도 도구가 제한적이면 제한된 에이전트입니다. 사용할 수 있는 것만으로 모든 일을 처리하게 되므로 에이전트가 Bash에 크게 의존하는 이유도 여기에 있습니다. 셸 도구 하나로 시스템 대부분에 접근할 수 있기 때문입니다. 에이전트에 어떤 기능을 제대로 제공하려면 해당 기능을 도구로 추가하세요. 하네스 외부의 도구를 연결하는 표준은 MCP입니다.

도구 정의는 매 요청마다 컨텍스트를 차지하므로 아무 도구도 호출하기 전부터 도구가 많으면 상시 비용이 발생합니다. 설명이 비슷한 도구가 많으면 모델이 적합한 도구를 고르기도 어려워집니다.

사용 예:

“에이전트가 스테이징에 직접 쿼리를 보낼 수 있나요?”

“하네스에 스테이징 전용 읽기 권한 `psql` 도구를 추가하세요. 해당 도구가 없으면 에이전트는 파일 시스템 밖의 내용을 전혀 볼 수 없습니다.”

---

모델이 도구 이름과 인수를 적어 내놓는 출력입니다. 구조화된 텍스트일 뿐이며 이것만으로는 아무 일도 하지 않습니다. 하네스가 읽어 실행해야 합니다. 모델이 한 번의 모델 제공자 요청에서 생성합니다.

도구 호출의 생명주기는 다음과 같습니다.

에이전트 작업에서 턴 한 번은 대개 이러한 왕복을 여러 번 연결합니다.

다른 출력과 마찬가지로 다음 토큰 예측으로 만들어지므로 모델 출력이면 무엇이든 그렇듯 잘못될 수 있습니다. 존재하지 않는 경로, 명령에 없는 플래그, 정확하지 않고 그럴듯하기만 한 인수가 예입니다. 하네스는 의도한 내용이 아니라 작성된 내용을 실행합니다. 경로를 잘못 입력해도 우아하게 오류가 나는 대신 잘못된 파일을 편집할 수 있습니다.

사용 예:

“테스트를 실행했다고 했는데 파일 타임스탬프가 바뀌지 않았어요.”

“대화 기록을 확인하세요. 실제로 도구 호출을 출력했나요, 아니면 실행했다고 말만 했나요? 모델이 호출을 생성해도 하네스가 실행하지 않았다면 아무 일도 일어나지 않은 겁니다.”

---

하네스가 도구 호출을 실행한 뒤 돌려주는 결과입니다. 파일 내용, 명령 출력, 오류 등이 해당합니다. 에이전트가 환경을 볼 수 있는 유일한 창입니다. 다음 모델 제공자 요청에서 모델로 전달되어 모델이 다음 행동을 결정합니다. 도구 호출과 도구 결과는 같은 교환의 양쪽 끝이며 둘 다 한 턴 안에 있습니다.

도구 결과의 생명주기는 다음과 같습니다.

결과는 세션이 끝날 때까지 컨텍스트에 남습니다. 코딩 세션의 컨텍스트 대부분은 보통 도구 결과로 채워집니다. 파일을 읽을 때마다, 테스트를 실행할 때마다, 검색 결과가 들어오고 더는 쓸모가 없어진 뒤에도 모든 토큰을 계속 차지합니다. 자세한 테스트 로그나 생성된 파일 전체처럼 큰 결과 몇 개만으로도 대화 자체보다 빠르게 세션을 컨텍스트 창의 한계 가까이 밀어붙일 수 있습니다.

모델은 결과만 볼 수 있으므로 그 뒤의 환경을 확인할 방법이 없습니다. 출력이 잘렸거나 명령이 조용히 실패했거나 내용 대신 하네스 오류가 돌아왔다면 모델은 받은 정보를 바탕으로 추론합니다. 시스템에 대한 에이전트의 그림이 잘못된 듯하면 도구 결과를 살펴보세요. 대화 기록 어딘가에 알고 있는 사실과 다른 결과가 있을 수 있습니다.

사용 예:

“파일이 비어 있다고 생각하며 추론하네요.”

“파일 내용이 아니라 권한 거부 결과가 돌아왔습니다. 모델은 오류 문자열만 봤고 파일을 볼 다른 방법이 없습니다.”

---

Model Context Protocol. 외부 도구 서버를 하네스에 연결하는 프로토콜입니다. 에이전트가 하네스에 기본 제공되는 것 외의 도구를 얻는 방법입니다. 에이전트가 ‘MCP를 호출’하는 일은 없습니다. 에이전트는 도구를 호출하고, 그 도구가 마침 MCP 서버에서 제공된 것뿐입니다. 리소스(읽기 전용 데이터)와 프롬프트(재사용 가능한 템플릿)도 노출하지만, 핵심은 도구 제공입니다.

이 프로토콜은 통합 문제를 해결합니다. 표준이 없다면 모든 하네스가 자체 Linear 통합, 자체 Slack 통합, 자체 데이터베이스 통합을 각각 따로 작성하고 유지해야 합니다. MCP를 사용하면 통합을 서버로 한 번 작성하고, MCP 호환 하네스라면 어디서든 사용할 수 있습니다. 하네스가 서버에 연결하면 서버가 제공 도구를 알리고, 해당 도구는 내장 도구와 나란히 에이전트에 제공됩니다.

비용은 컨텍스트에서 발생합니다. 서버가 알리는 모든 도구는 이름, 설명, 매개변수 스키마가 담긴 정의로 들어오며, 모델은 자신이 아는 도구만 호출할 수 있습니다. 단순한 접근법은 모든 정의를 미리 컨텍스트 창에 넣는 것입니다. 기능이 넉넉한 서버 몇 개만 설치해도 세션은 아무것도 입력하기 전에 도구 스키마 토큰을 수천 개씩 싣고 시작하며, 작업에서 쓸 일 없는 도구에 주의력 예산을 소모합니다.

많은 하네스는 이제 도구 검색으로 이 문제를 완화합니다. 전체 정의 대신 컨텍스트에는 사용 가능한 도구를 가리키는 컨텍스트 포인터가 들어갑니다. 에이전트는 이름이나 목적에 따라 도구를 검색하고 필요할 때만 정의를 불러옵니다. 하네스에 이 기능이 없다면 선행 비용은 그대로 적용되므로, 프로젝트에 실제로 필요한 서버만 활성화하는 편이 좋습니다.

사용 예:

“에이전트가 Linear 티켓을 읽어야 해요.”

“하네스가 Linear MCP 서버를 사용하도록 설정하세요. 이 서버는 에이전트가 호출할 수 있는 도구로 Linear API를 제공합니다. 직접 도구 래퍼를 작성할 필요가 없죠.”

---

미리 승인되지 않은 도구 호출을 실행하기 전에 하네스가 사용자에게 보여 주는 내용입니다. 모델이 도구 호출을 생성하면 하네스는 즉시 실행하지 않고 멈춰 확인을 요청합니다. 승인하면 실행하고 거부하면 거부 결과를 도구 결과로 모델에 전달합니다. 위험하거나 민감한 동작에서 하네스가 사람을 작업 루프에 참여시키는 방식입니다.

권한 요청의 생명주기는 다음과 같습니다.

요청을 거부하면 에이전트의 방향을 바꿀 수 있습니다. 모델은 거부를 다른 도구 결과처럼 읽고 다른 접근법을 시도하거나 사용자의 선호를 묻습니다. 대부분의 하네스는 거부에 메시지를 붙이는 기능을 제공합니다. 이 메시지로 요청은 방향을 잡는 지점이 됩니다. “그렇게 말고 마이그레이션 스크립트를 사용하세요”라는 지시가 모델이 다음 행동을 정하는 순간에 도착합니다.

비용은 요청마다 사용자가 응답할 때까지 동기식으로 기다려야 한다는 점입니다. 에이전트는 답을 받을 때까지 멈춰 있습니다. 사용자가 지켜볼 때는 괜찮지만 없을 때는 문제가 됩니다. 요청을 계속 발생시키는 에이전트는 자리 비움으로 둘 수 없습니다. 권한 모드가 다이얼 역할을 합니다. 어떤 호출을 자유롭게 실행하고 어떤 호출은 먼저 물어보게 할지 정합니다. 샌드박스로 자유롭게 실행할 범위를 넓혀도 안전하게 만드는 편이 좋습니다.

사용 예:

“회의 중이었는데 권한 요청 때문에 10분째 멈춰 있었어요.”

“그게 사람 참여형 실행의 비용입니다. 안전한 도구는 미리 승인해 실제로 위험한 호출에서만 요청이 나오게 하세요.”

---

에이전트 모드에서 권한을 확인하는 부분입니다. 어떤 도구 호출이 권한 요청을 띄우고 어떤 호출이 자동 실행되는지를 정합니다. 하네스가 행동 지침을 권한 모드와 묶기 전에 모드 시스템이 맡았던 원래 목적입니다.

하네스는 다음과 같은 단계의 모드를 제공합니다.

단계를 고르는 것은 안전과 중단 사이의 절충이며 양쪽의 실패 유형을 모두 체감하게 됩니다. 너무 엄격하면 사용자가 병목이 됩니다. 에이전트가 무해한 파일 읽기마다 몇 초 간격으로 멈추고, 사용자는 자동으로 승인을 누르다가 승인이 아무 의미도 없게 됩니다. 무조건 승인하는 것은 두 방식의 단점만 합친 최악의 선택입니다. 보호 효과는 없고 중단만 늘어납니다. 너무 느슨하면 먼저 확인하고 싶었던 파일을 에이전트가 편집하고 명령을 실행합니다.

느슨한 권한을 가장 안전하게 사용할 수 있는 곳은 잘못된 도구 호출의 피해 범위가 제한된 샌드박스입니다. 샌드박스 밖에서는 읽기를 자동 승인하되 되돌릴 수 없는 작업에는 사람이 참여하도록 두는 사용자가 많습니다.

사용 예:

“grep을 할 때마다 멈춰서 자리 비움 실행을 완전히 망쳤어요.”

“읽기 전용 도구의 권한 모드는 완화하고 쓰기와 셸은 계속 확인을 요청하게 하세요. 조사 세션에서 뜨는 권한 요청 대부분은 잡음입니다.”

---

실행 중 에이전트의 작동 방식을 정하는 프리셋입니다. 권한 모드와 시스템 프롬프트에 삽입되는 행동 지침을 하나로 묶습니다. 위험한 호출에는 확인을 요청하는 기본 모드, 편집을 차단하고 조사하도록 유도하는 계획 모드, 편집을 자동 승인하는 편집 수락 모드, 모든 것을 자동 승인하는 권한 우회 모드(흔히 YOLO 모드) 등이 있습니다. 세션 중간에도 바꿀 수 있습니다.

권한 모드와 단순한 권한 설정을 구분하는 것은 이 결합 방식입니다. 권한 모드는 관문일 뿐입니다. 어떤 도구 호출을 통과시킬지만 결정합니다. 관문만 있으면 편집을 원하지만 할 수 없는 에이전트가 됩니다. 쓰기를 제안했다가 차단되면 다른 방법을 시도합니다. 삽입된 지침은 그 욕구 자체를 바꿉니다. 계획 모드는 단지 편집을 막는 것이 아니라 에이전트가 계획 단계에 있다고 알려 주어 관문에 맞서 애쓰는 대신 읽고, 질문하고, 제안하게 합니다. 관문과 방향 제시가 같은 쪽을 향합니다.

실제로는 작업이 진행되고 신뢰가 바뀌면서 모드를 변경합니다. 하나의 작업도 여러 모드를 거칠 수 있습니다. 접근 방식을 다듬는 동안에는 계획 모드, 첫 번째 까다로운 편집에는 확인을 요청하는 기본 모드, 에이전트가 변경 사항을 이해하는 것이 확인되면 편집 수락 모드, 샌드박스 안의 자리 비움 실행에는 우회 모드를 쓸 수 있습니다. 모드를 바꿔도 비용은 없습니다. 대화는 새 권한과 지침을 적용한 채 같은 지점에서 계속됩니다. 프롬프트를 읽지도 않고 매번 승인한다면 실제 신뢰보다 모드가 지나치게 엄격합니다. 반대로 계속 편집을 거부한다면 모드가 지나치게 느슨한 것입니다.

공급업체 용어: Claude Code는 이를 “권한 모드”, Codex는 “승인 모드”라고 부릅니다. 두 이름 모두 행동을 결합하기 전부터 쓰였습니다.

사용 예:

“계획만 원했는데 계속 파일을 편집해요.”

“계획 모드로 바꾸세요. 쓰기를 차단하고 조사에 집중할 겁니다.”

“나중에 자리 비움 작업에는 어떤 모드를 쓰죠?”

“우회 모드요. 단, 샌드박스 안에서만요.”

---

에이전트가 내부에서 실행되는 격리된 환경입니다. 컨테이너, VM, 임시 파일 시스템, 권한이 제한된 셸 등이 있습니다. 에이전트 동작의 피해 범위를 제한합니다. 파괴적인 명령을 실행하거나 악성 항목을 가져오더라도 피해가 격리됩니다. 자리 비움 실행을 실용적으로 만드는 안전 기반입니다.

샌드박스와 권한 모드는 같은 문제를 반대 방향에서 해결합니다. 권한은 동작이 실행되기 전에 확인을 요청하고, 샌드박스는 실행된 동작이 접근할 수 있는 범위를 제한합니다. 권한을 사용하면 사람이 작업에 참여해야 합니다. 매번 뜨는 프롬프트는 작업을 중단시키며 계속 확인을 요청하는 세션은 자율적이라고 보기 어렵습니다. 샌드박스는 주의력 대신 인프라를 사용합니다. 격리가 강할수록 확인을 덜 요청할 수 있습니다.

격리 수준은 다음과 같습니다.

샌드박스로 막을 수 없는 것은 정당한 경로를 통해 샌드박스 밖으로 나가는 동작입니다. Git 인증 정보를 가진 에이전트는 푸시할 수 있고, 네트워크에 접근하는 에이전트는 프로덕션 API를 호출할 수 있습니다. 경계를 얼마나 두껍게 할지 정하기 전에 무엇이 경계를 통과하는지 결정하세요.

사용 예:

“밤새 권한 우회로 실행하게 하고 싶지만 아직은 준비가 안 됐어요.”

“샌드박스에 넣으세요. 새 컨테이너를 사용하고 인증 정보를 마운트하지 말고 외부 네트워크를 차단하세요. 최악의 경우 자체 파일 시스템을 망가뜨린 뒤 컨테이너를 폐기하면 됩니다.”

---

자신 있게 동의하는 모델 출력입니다. 훈련에서 비롯됩니다. 모델이 사람이 좋아하는 답을 선호하도록 조정됐고, 사람은 자신이 틀렸다는 말을 듣기보다 동의를 좋아하는 경향이 있습니다. 그래서 모델은 동의가 보상받는다고 학습했습니다. 동의가 틀렸을 때조차 그렇습니다.

다음처럼 나타납니다:

• 압박에 굴복 — “확실해요?”라고 물으면 맞는 답을 뒤집습니다.
• 나쁜 입력 칭찬 — 분석하기 전에 잘못된 계획이 훌륭하다고 동의합니다.
• 편향된 표현 — 자신이 작성했다고 알리면 검토가 긍정적으로, 다른 사람이 작성했다고 알리면 부정적으로 기웁니다. 같은 산출물인데 판정은 달라집니다.
• 모방 — 사용자의 실수를 되풀이해 확인해 줍니다.

진단 테스트: 사용자가 방향을 제시하지 않았다면 모델이 같은 말을 했을까요? 달라진 점이 사용자의 어조나 표현뿐이라면 분석이 실제로 바뀐 것이 아니라 아첨성 동조입니다.

해결: 사용자의 선호를 감추세요. “이 코드가 좋은가요?”가 아니라 “이 코드를 검토해 주세요”처럼 중립적으로 프롬프트를 작성합니다.

피하기: 자신이 좋아하는 답을 들었다는 이유만으로 모든 오답을 “아첨성 동조”라고 부르지 마세요. 진단 테스트가 없다면 이 용어는 “틀렸다”와 다를 바 없습니다.

사용 예:

“리팩터링 계획이 훌륭하다고 하더니 ‘확실해요?’라고 묻자 전체를 번복했어요.”

“전형적인 아첨성 동조입니다. 자신 있게 들렸을 때 먼저 동의하고 의심하는 듯 들리자 굴복했어요. 계획의 품질은 그대로고 어조만 바뀌었습니다. 초기화하고 어느 쪽으로도 뜻을 내비치지 않은 채 다시 물어보세요.”

---

자신 있게 틀린 모델 출력입니다. 원인과 해결책이 다른 두 유형이 있습니다.

다음 토큰 예측은 기저 사실이 진짜인지와 관계없이 유창한 출력을 만듭니다. 모델에는 모르는 내용이 있다는 내부 신호가 없으므로, 존재하지 않는 메서드도 올바른 답과 같은 확신에 찬 어조로 나옵니다. 환각으로 만든 코드는 그럴듯하게 구성됩니다. 실제로 없는 API가 있다면 어떻게 생겼을지를 보여 주므로 대충 훑는 검토에서는 지나가고 실행한 뒤에야 실패합니다.

한 유형의 해결책이 다른 유형을 악화시키므로 어느 쪽인지 알아야 합니다. 사실성 문제는 지식이 부족한 경우입니다. 문서, 타입 정의, 파일 등 컨텍스트를 추가해야 합니다. 충실성 문제는 지식은 있지만 주의력을 두고 경쟁하는 동안 밀려나는 경우입니다. 컨텍스트를 제거해야 합니다. 충실성 문제를 사실성 문제로 오진해 문서를 더 붙여 넣으면 컨텍스트가 커져 이탈이 더 심해집니다. 에이전트가 틀렸을 때 어떤 문제인지 판단하기 전에 올바른 정보가 이미 컨텍스트에 있었는지 확인하세요.

피하기: 유형을 밝히지 않은 채 “환각”을 단순히 “오답”이라는 뜻으로 쓰지 마세요. 무엇을 진단하는지 밝히지 않으면 쓸모가 없습니다.

사용 예:

“스키마에 `parseAsync` 메서드가 있다고 환각했어요.”

“사실성 문제인가요, 충실성 문제인가요?”

“붙여 넣은 문서에 메서드가 있었어요. 턴 40쯤부터 읽기를 멈췄을 뿐입니다.”

“그럼 충실성 문제네요. 문서를 더 추가할 게 아니라 압축하고 다시 불러오세요.”

---

모델이 훈련을 통해 “아는” 내용이며 매개변수에 저장됩니다. 훈련 시점에 고정되며 모델은 자신의 매개변수를 보거나 갱신할 수 없습니다. 압축 과정에서 세부 정보가 사라집니다. 수십억 개의 사실을 고정된 매개변수에 담으면서 드문 정보는 흐릿해집니다. 흔한 주제에는 유창한 답을, 드문 주제에는 지어낸 답을 만드는 원천입니다. 맥락 지식의 반대 개념입니다.

파라미터 지식은 사실 형태로 저장되지 않습니다. 훈련 과정에서 모델에 조회용 데이터베이스를 주는 것은 아닙니다. 텍스트를 잘 예측할 때까지 매개변수를 조정할 뿐이며, 어떤 주제에 대한 텍스트를 잘 예측하는 모델은 그 주제를 아는 듯 행동합니다. 지식의 신뢰성은 훈련 데이터에 해당 주제가 얼마나 자주 나왔는지에 달려 있습니다. 예시가 수백만 개인 주제는 정확히 재현하지만 몇 개뿐인 주제는 비슷한 주제의 형태를 바탕으로 추측합니다. 모델에게 재현과 추측은 같은 과정이므로 어느 쪽을 하는지 스스로 구분하지 못합니다. 만들어 낸 답도 정답과 똑같이 유창하게 나옵니다. 환각은 모델이 잘못 추측한 결과입니다.

파라미터 지식은 시간이 지나며 낡기도 합니다. 지식 컷오프에서 매개변수 갱신이 멈추므로 그 이후 출시되거나 이름이 바뀐 라이브러리는 매개변수에 없고, 변경된 API는 예전 형태로 기억합니다.

두 공백, 즉 너무 드문 지식과 너무 최근의 지식은 같은 방법으로 해결합니다. 매개변수에 넣을 수 없으므로 맥락 지식으로 제공해야 합니다.

사용 예:

“React 코드는 완벽하게 쓰면서 우리 내부 SDK의 메서드는 지어내네요.”

“React는 파라미터 지식에 촘촘히 들어 있습니다. 훈련 예시가 수백만 개예요. SDK는 그렇지 않으므로 모델이 그럴듯한 형태를 채워 넣습니다. SDK 문서를 컨텍스트에 불러오세요.”

---

모델이 파라미터 지식을 갖지 않는 시점 이후의 날짜입니다. 컷오프 이후의 라이브러리, API, 사건은 문서를 맥락 지식으로 불러오지 않으면 사실을 지어내게 만드는 함정이 됩니다. 모델 릴리스마다 자체 컷오프가 있습니다.

모델이 만들어지는 방식 때문에 컷오프가 생깁니다. 훈련 과정에서 텍스트의 스냅샷이 모델의 매개변수에 반영되고 이후 매개변수는 고정됩니다. 모델은 자신의 지식에 경계가 있다는 사실을 알지 못합니다. 컷오프 이후의 내용을 물으면 거부하는 대신 자신이 알고 있는 가장 가까운 내용을 바탕으로 추론합니다. 이 때문에 함정이 조용히 작동합니다. 오래된 라이브러리 버전에 맞춰 작성한 코드는 그럴듯하고 컴파일되는 경우도 많지만 변경된 부분에서 실패합니다.

해결책은 언제나 같습니다. 최신 정보를 컨텍스트에 넣으세요. 변경 기록을 불러오거나 설치된 버전의 타입 정의를 가리키거나 에이전트가 웹에서 문서를 읽게 하세요. 컨텍스트의 내용은 매개변수에 없는 내용보다 우선합니다.

사용 예:

“계속 v3 SDK 문법을 쓰는데 우리는 v5를 사용해요.”

“v5는 지식 컷오프 이후에 출시됐습니다. v5 변경 기록을 맥락 지식으로 불러오세요. 그렇지 않으면 오래된 파라미터 지식을 바탕으로 계속 지어낼 겁니다.”

---

현재 에이전트가 컨텍스트에서 직접 읽을 수 있는 사실입니다. 사용자의 작업 요청, 읽어 온 파일, 도구 결과, 세션 시작 시 불러온 AGENTS.md 내용이 여기에 포함됩니다. 파라미터 지식의 반대 개념입니다. 파라미터 지식은 매개변수에서 회상하고, 맥락 지식은 창에서 읽습니다. 에이전트가 맥락 지식을 바탕으로 작업하면 환각이 훨씬 적습니다. 흐릿한 기억에서 꺼내는 것이 아니라 답이 바로 눈앞에 있기 때문입니다.

두 종류의 지식 중 사용자가 제어할 수 있는 것은 맥락 지식뿐입니다. 매개변수는 고정되어 있으므로 모델이 모르는 지식, 예를 들어 내부 SDK, 지식 컷오프 이후 출시된 라이브러리, 어제 내린 결정을 전달하는 유일한 방법은 모델에 필요한 정보를 컨텍스트에 넣는 것입니다. 실제 AI 코딩 작업의 상당 부분은 필요한 순간에 모델 앞에 올바른 사실을 가져다 놓는 일입니다.

맥락 지식과 파라미터 지식이 충돌하면 보통 맥락 지식이 우선합니다. 현재 API 문서를 붙여 넣으면 모델은 오래된 API에 대한 기억보다 문서를 따릅니다. 다만 이전 버전의 내용이 여전히 새어 나올 수 있으며, 특히 긴 세션 후반부에서 그렇습니다. 문서를 불러왔는데도 에이전트가 오래된 방식을 계속 되살린다면 파라미터 지식이 맥락을 뚫고 나온 것입니다. 수정 사항을 다시 알려 주거나 작업 가까이에 옮기면 도움이 됩니다.

파라미터 지식과 달리 맥락 지식을 사용하는 데는 비용이 듭니다. 창에 불러온 모든 내용은 토큰을 사용하고 모델의 주의력 예산을 두고 경쟁하므로 더 많이 불러온다고 항상 나은 것은 아닙니다. 목표는 모든 사실이 아니라 관련된 사실을 창에 넣는 것입니다.

이 용어는 파라미터 지식과 대비할 때만 사용하세요. 그렇지 않을 때는 컨텍스트라고만 하면 됩니다.

피하기: “작업 메모리” — 맥락 지식은 지금 창 안에 있는 내용이고 메모리 시스템은 세션 간 내용을 창으로 가져옵니다. 규모가 다르므로 혼동하지 마세요.

사용 예:

“문서를 붙여 넣으면 API를 정확히 쓰는데, 없으면 왜 지어내죠?”

“문서가 있으면 맥락 지식, 즉 페이지를 읽는 겁니다. 없으면 파라미터 지식에 의존하고 드문 엔드포인트는 흐릿해집니다.”

---

각 토큰을 예측할 때 모델은 컨텍스트의 다른 모든 토큰을 고려합니다. 어떤 토큰에는 큰 비중을 두고 어떤 토큰은 거의 고려하지 않습니다. 토큰 두 개의 짝을 주의력 관계라고 부르며, 의미 있는 쌍(“her”와 “Sarah”, 또는 `getUser()` 호출과 그 선언인 `function getUser`)은 서로 무관한 쌍보다 더 강하게 영향을 줍니다. 토큰이 N개인 컨텍스트에는 대략 N²개의 관계가 있습니다.

모델이 이해하는 것처럼 보이는 능력은 이 쌍에 달려 있습니다. 대명사를 해석할 때는 “her”와 “Sarah” 사이의 주의력 관계가 강하기 때문입니다. 올바른 인수로 함수를 호출할 때는 호출 지점과 앞서 읽은 정의의 관계가 작동합니다. 이 내용은 조회하는 게 아니라 모든 쌍에 대해 각 모델 제공자 요청마다 새로 계산합니다.

N²라는 수치는 직관보다 빠르게 커지므로 잠시 생각해 볼 가치가 있습니다.

각 쌍은 한 번보다 더 많이 계산됩니다. 모델에는 여러 주의력 헤드가 있습니다. 최첨단 모델의 정확한 수는 공개되지 않았지만 50~100개 정도로 추정할 만하며 각 헤드는 모든 관계를 자체적으로 계산합니다. 따라서 위 표의 모든 쌍이 각 헤드마다 복제됩니다. 관계의 수가 매우 많아집니다.

주어진 작업에서 중요한 관계는 이 중 소수뿐입니다. 사용자의 지시와 그 지시가 좌우하는 코드 사이의 관계가 중요한 몇 개에 해당하고 나머지 대부분은 잡음입니다. 이 두 가지는 서로 다른 속도로 증가합니다. 중요한 관계의 수는 대략 일정하지만 전체 관계는 컨텍스트 크기에 따라 제곱으로 늘어납니다. 토큰 1,000개에서는 필요한 관계가 100만 개 중 하나이고, 100,000개에서는 100억 개 중 하나입니다. 이 계산이 주의력 예산의 밑바탕이며 중요한 관계가 차지하는 몫이 너무 얇아질 때 체감하는 현상이 주의력 저하입니다.

사용 예:

“diff에 있는 `user` 기호 두 개를 계속 혼동하네요. 멍청한 구간에 들어간 것 같아요.”

“맞아요. 각 호출 지점과 선언부의 주의력 관계가 서로 경쟁하고 있습니다. 토큰 모양은 같지만 바인딩은 다르죠. 하나의 이름을 바꾸면 관계가 선명해집니다.”

---

각 토큰은 나머지 컨텍스트에 영향력을 분배할 수 있는 양이 한정되어 있습니다. 관계 하나에 영향력을 많이 쓰면 다른 관계에 돌아갈 몫은 줄어듭니다. 예산은 토큰마다 정해져 있고 컨텍스트가 커져도 늘지 않습니다. 그래서 긴 세션에서는 영향력이 희석됩니다.

신호와 잡음으로 생각해 보세요. 사용자의 지시는 일정한 크기의 신호이고, 컨텍스트 창의 다른 모든 토큰은 경쟁하는 소리입니다. 지시가 더 작아지는 것은 아닙니다. 글자 하나하나 그대로 남아 있습니다. 하지만 컨텍스트가 커질수록 주변의 방이 더 시끄러워져 신호 대 잡음비가 떨어집니다. 컨텍스트가 10k 토큰일 때 가장 크게 들리던 지시가 150k에서는 배경음이 됩니다. 이것이 주의력 저하의 작동 원리입니다. 모델이 잊은 것이 아니라 신호가 잡음에 묻힌 것입니다.

증상은 불복종처럼 보입니다. 에이전트가 초반에 제약을 받아들였는데 나중에 벗어나고, 제약을 다시 붙여 넣어도 효과는 잠시뿐입니다. 원인은 지시가 아니라 창 안에서 지시와 경쟁하는 나머지 내용입니다.

컨텍스트에 무엇을 넣을지는 사용자가 제어할 수 있습니다. 작업에 도움이 되지 않는 내용은 중립적이지 않습니다. 필요한 내용 전체에 잡음을 더합니다. 창을 작게 유지하고, 쌓인 컨텍스트가 더는 비용만큼 가치를 내지 않을 때 초기화하세요. 중요한 제약은 초기에 언급한 내용이 계속 유지되리라 기대하지 말고 다시 밝혀 주세요.

사용 예:

“왜 위쪽에 붙여 넣은 스키마를 계속 무시하죠?”

“이미 멍청한 구간에 깊이 들어왔습니다. 각 토큰의 주의력 예산은 그대로인데 컨텍스트만 계속 커졌어요. 스키마 신호가 이후에 추가한 수천 개의 토큰과 경쟁하고 있습니다.”

---

세션이 길어질수록 각 토큰의 주의력 예산은 더 많은 경쟁 요소에 분산됩니다. 의미 있는 관계 하나에 대한 신호는 약해지고, 관련 없는 컨텍스트의 잡음이 들어옵니다. 같은 모델, 같은 매개변수에서 한 접시를 나눠 먹는 사람이 늘어나는 것뿐입니다. 적정 지능 구간/멍청한 구간 효과의 원인입니다.

세션 중간에 모델의 능력이 떨어지는 것처럼 나타납니다. 한 시간 동안 지키던 제약을 놓치고, 이미 들은 내용을 다시 묻고, 앞서 읽은 파일을 무시하는 코드를 작성합니다. 모델 자체는 바뀌지 않았습니다. 달라진 변수는 이제 모델이 주의를 기울여야 하는 컨텍스트의 양뿐입니다.

점진적으로 발생하기 때문에 세션 내부에서 알아채기 어렵습니다. 오류도 임계점도 없습니다. 각 턴이 이전 턴보다 조금씩 나빠지고, 실수가 뚜렷해졌을 때는 이미 한동안 멍청한 구간에 들어가 있을 수 있습니다.

컨텍스트를 더 추가하는 게 아니라 제거해야 회복됩니다. 무시된 지시를 다시 붙여 넣으면 이미 복잡한 창에 경쟁 요소를 더 추가하므로 효과는 잠시뿐입니다. 효과적인 방법은 다음과 같습니다. 초기화하고 작업에 필요한 내용만 다시 불러오거나, 압축하거나, 새 세션으로 작업을 인계하세요. 지시를 따르지 못하는 현상을 모델 문제가 아니라 컨텍스트 길이에 관한 신호로 다루세요.

사용 예:

“멍청한 구간에 완전히 들어갔어요. 타입 파일에 없는 제네릭을 만들어 내고 있어요.”

“주의력 저하입니다. 타입 정의는 여전히 컨텍스트에 있지만 이후 추가한 모든 내용에 묻혀 신호가 약해졌습니다. 초기화하고 다시 불러오세요.”

---

세션 초기에 에이전트는 “적정 지능 구간”에 있습니다. 예리하고 집중력이 좋으며 기억도 잘합니다. 세션이 길어지면서 “멍청한 구간”으로 흘러갑니다. 산만하고 잘 잊으며 실수가 늘고 충실성 환각도 많아집니다. 같은 모델, 같은 하네스이고 컨텍스트가 늘었을 뿐입니다. 주의력 저하가 체감되는 결과입니다. 최첨단 모델에서도 멍청한 구간은 흔히 토큰 125K~150K 부근에서 시작하지만, 이 수치에는 논쟁이 있습니다. 세션이 비대해지면 초기화하거나 압축하세요. 억지로 계속하지 마세요.

저하는 점진적이므로 놓치기 쉽습니다. 오류 메시지도 없고 뚜렷한 경계도 없습니다. 에이전트가 조금씩, 그러다 눈에 띄게 나빠질 뿐입니다. 흔한 징후는 20턴 전에 한 지시를 잊거나, 이미 고친 실수를 반복하거나, 컨텍스트와 모순되는 내용을 자신 있게 말하는 것입니다. 변화가 서서히 진행되므로 보통은 계속 밀어붙이며 설명을 반복하지만, 이는 컨텍스트를 더 추가해 문제를 악화시킵니다.

이 구간은 컨텍스트 창의 한계와 일치하지 않습니다. 창 대부분이 비어 있어도 멍청한 구간에 깊이 들어갈 수 있습니다. 한계는 하네스가 더 진행하지 못하게 막는 지점이지만 품질은 훨씬 먼저 떨어집니다. 창이 아니라 적정 지능 구간에 맞춰 계획하세요. 실질적인 작업 예산은 에이전트가 기술적으로 담을 수 있는 토큰 수가 아니라 잘 작동하는 범위의 토큰 수입니다.

적정 지능 구간은 예산이며, 무관한 작업이 그 예산을 씁니다. 세션에서 하는 모든 작업은 토큰을 소비하므로 같은 세션에서 두 번째 작업을 시작하면 멍청한 구간에 더 가까운 상태로 출발합니다. 세션마다 작업 하나를 하면 각 작업이 세션 중 가장 예리한 구간을 활용합니다. 단일 작업이 적정 지능 구간 하나보다 크면 나누세요. 자연스러운 경계에서 작업을 인계하거나 압축하고, 새 세션에서 다음 부분을 맡기세요.

사용 예:

“처음 세 구성 요소는 잘했는데 네 번째를 완전히 망쳤어요.”

“적정 지능 구간을 벗어났네요. 같은 모델이지만 이제 멍청한 구간에 깊이 들어갔습니다. 압축하고 계획을 다시 불러오면 다음 구성 요소는 잘될 겁니다.”

---

현재 세션을 끝내고 새 세션을 시작합니다. 다음 메시지는 비어 있는 세션과 비어 있는 컨텍스트 창에서 시작합니다. 보통 사용자가 실행합니다.

초기화는 오염된 컨텍스트의 해결책입니다. 세션에는 실패한 시도와 잘못된 방향, 오래된 도구 결과, 폐기된 계획 등 모든 것이 쌓입니다. 모델은 매 턴마다 이 전체 내용을 다시 읽으며 나쁜 이력이 새로운 작업까지 끌어내립니다. 긴 세션에 깊이 들어가면 에이전트는 점점 모호하고 말을 덜 따르게 됩니다. 명확히 지시한 내용을 무시하고 품질이 떨어지며, 더 잘하라고 재촉해도 소용없습니다. 여전히 컨텍스트 안에서 잡음을 헤치고 있기 때문입니다. 초기화는 잡음을 없앱니다.

초기화해도 대화가 삭제되지는 않습니다. 대부분의 하네스는 세션 기록을 컴퓨터에 보관하므로 대화 기록은 다시 읽거나 이어 갈 수 있습니다. 사라지는 것은 에이전트의 작업 상태입니다. 모델은 무상태형이므로 새 세션은 이전 세션이 알던 것을 전혀 모릅니다. 다음 세션에 필요한 결정이나 진행 상황이 있다면 먼저 인계 산출물을 작성하게 한 뒤, 새 세션이 그 자료를 가리키도록 시작하세요.

세션을 요약해 새 컨텍스트에 넣는 압축과 비교해 보세요. 초기화는 더 무딘 도구입니다. 쓸모없는 내용까지 아무것도 이어지지 않습니다.

사용 예:

“실패하는 테스트를 반복 실행하면서 막혔어요.”

“초기화하세요. 계획 문서와 테스트 파일을 갖춘 새 세션으로 시작하면 됩니다. 기존 컨텍스트와 씨름할 필요가 없어요.”

---

한 세션에서 다른 세션으로 에이전트의 컨텍스트를 전달합니다. 전달 방식은 문서로 작성한 인계 산출물, 메모리 안의 요약(압축) 등 다양합니다. 아무것도 전달하지 않는 초기화와는 다릅니다. 역할 변경(계획 담당 → 구현 담당), 자리 비움 실행 시작, 여러 병렬 세션으로 분기, 컨텍스트 창의 공간 확보 등이 이유가 될 수 있습니다.

받는 세션은 컨텍스트가 없는 상태에서 시작합니다. 모델은 무상태형이며 이전 세션의 어떤 내용도 새 세션에 보이지 않습니다. 다음 세션에 필요한 내용은 명시적으로 전달해야 하고 나머지는 모두 사라집니다. “반환 경로가 없다”는 점이 전달 자료의 형태를 결정합니다. 새 세션은 이전 세션에 무슨 뜻이었는지 물어볼 수 없으므로 전달 자료만으로 충분히 이해할 수 있어야 합니다.

잘못된 인계에서 드러나는 실패는 재논의입니다. 이전 세션이 결정한 내용만 기록하고 이유를 남기지 않아 새 세션이 끝난 결정을 다시 엽니다. 컨텍스트가 하나도 없는 세션이 무엇을 해낼 수 있는지를 기준으로 인계 자료를 평가하세요.

사용 예:

“계획 세션이 무거워지는데 계속 진행해야 할까요?”

“작업을 인계하세요. 결정을 문서로 작성하고 초기화한 뒤 새 세션에서 그 문서를 읽으며 구현을 시작하세요.”

---

원래 형태 그대로의 진실 공급원입니다. 코드, 대화 기록, 원시 로그, 실제 API 응답이 여기에 해당합니다. 대상에 대한 설명이 아니라 대상 그 자체입니다. 2차 자료의 반대 개념입니다.

코드베이스가 실제로 무엇을 하는지 알고 싶다면 코드는 1차 자료입니다. 문서와 아키텍처 다이어그램, README는 모두 코드에 대한 설명이며 작성 당시에는 정확했더라도 그 이후의 갱신 시점은 각기 다릅니다. 에이전트가 프로젝트에 대해 자신 있게 틀린 주장을 한다면 어떤 자료를 기반으로 했는지 물어보세요. 문서를 읽은 에이전트는 문서의 오래된 내용을 물려받지만 코드를 읽은 에이전트는 현재의 사실을 확인합니다.

비용 때문에 1차 자료를 기본으로 사용하기는 어렵습니다. 컨텍스트 창에 불러오려면 비용이 큽니다. 파일 전체, 대화 기록 전체, 입력 토큰으로 요금이 부과되고 주의력 예산을 차지하는 모든 토큰이 포함됩니다. 그 비용으로 얻는 것은 완전성입니다. 무엇이 중요했는지 다른 사람이 판단해 미리 걸러 낸 내용이 없습니다. 지난달에 작성한 요약에는 오늘 중요해진 세부 정보가 없을 수 있지만, 1차 자료에는 여전히 그 내용이 있습니다.

정밀성이 중요할 때 1차 자료를 확인하세요. 정확한 시그니처, 실제 오류, 예외가 발생한 줄이 필요할 때입니다. 컨텍스트를 관리하는 일의 상당 부분은 언제 1차 자료에 비용을 들이고 언제 2차 자료로 충분한지 판단하는 것입니다.

사용 예:

“에이전트는 재시도 로직이 지수형으로 대기한다고 하는데, 실제로는 엔드포인트를 계속 두드리고 있어요.”

“설계 문서에서 그렇게 읽었네요. 실제 재시도 모듈을 보게 하세요. 동작이 중요할 때는 1차 자료를 기준으로 작업해야 합니다.”

---

1차 자료를 한 단계 거쳐 설명하는 기록입니다. 코드를 설명하는 문서, 대화 기록을 설명하는 요약, 검색 결과를 설명하는 보고서가 해당합니다. 설명 대상인 자료보다 컨텍스트 창에 불러오는 비용은 적지만, 작성자가 무엇이 중요한지 결정하면서 내용을 덜어 내므로 필연적으로 손실이 생깁니다. 요약만 읽는 사람은 빠진 내용을 볼 수 없습니다.

컨텍스트 엔지니어링의 많은 부분은 2차 자료를 만드는 일입니다. 압축은 세션 이력을 다음 세션을 시작할 요약으로 바꿉니다. 하위 에이전트는 잡음이 많은 검색에서 자체 컨텍스트를 사용하고 짧은 보고서를 반환합니다. 인계 산출물은 세션의 결정을 다음 세션이 읽는 문서로 압축합니다. 메모리 시스템은 세션에서 배운 내용을 노트로 추립니다. 모두 같은 절충점, 즉 충실도를 여유 공간과 맞바꿉니다.

2차 자료는 두 가지 방식으로 실패합니다. 정보를 잃습니다. 스키마 결정을 빠뜨린 압축 요약이나 예외 사례를 언급하지 않은 보고서처럼요. 그리고 오래됩니다. 1차 자료가 바뀌었는데 설명이 따라가지 못하면 문서는 이번 분기 아키텍처를 지난 분기의 내용과 이번 분기의 확신으로 설명합니다. 에이전트가 어느 쪽으로든 실패한 2차 자료를 바탕으로 행동하면 틀린 정보에 자신 있게 의존합니다. 해결 방법은 에이전트를 1차 자료로 돌려보내는 것입니다.

두 가지 실패가 있다고 해서 2차 자료가 잘못된 것은 아닙니다. 컨텍스트 창은 유한하고 1차 자료를 불러오는 비용은 큽니다. 요약과 보고서, 인계 문서가 없다면 큰 작업을 다룰 수 없습니다. 필요한 기술은 손실되어도 되는 세부 사항이 무엇인지 알고, 손실되면 안 되는 내용은 1차 자료와 대조해 확인하는 것입니다. 잘 만든 2차 자료는 원본으로 돌아가는 컨텍스트 포인터를 포함합니다. 대화 기록의 출처를 표시하는 요약이나 설명하는 파일을 알려 주는 문서처럼요. 설명만으로 부족할 때 독자는 손실된 내용에 의존하는 대신 포인터를 따라갈 수 있습니다.

사용 예:

“인계 문서에는 인증이 끝났다고 되어 있는데 새 세션이 계속 토큰 갱신 오류를 찾습니다.”

“그 문서는 2차 자료입니다. 이전 세션이 사실이 아니라 자신이 믿은 내용을 기록했을 수 있어요. 새 세션에서 인증 테스트를 실행하고 1차 자료를 기준으로 삼게 하세요.”

---

인계를 위한 운반 수단으로 사용하는 문서입니다. 한 세션이 환경에 작성해 다른 세션이 읽습니다. 명세, 티켓, 계획 문서가 모두 인계 산출물입니다.

이 문서를 작성하는 이유는 모델이 무상태이므로 세션을 초기화하면 그 안의 내용이 모두 사라지기 때문입니다. 결정, 제약, 미완성 계획이 이를 담고 있던 컨텍스트와 함께 사라집니다. 하지만 환경은 지속됩니다. 중요한 상태를 파일에 기록하면 다음 세션이 읽을 수 있는 곳으로 옮겨집니다.

이 산출물은 작업 그 자체가 아니라 세션에서 한 일을 설명하는 2차 자료입니다. 그래서 새 세션에 전달하기에 충분히 작으면서도 오해를 일으킬 수 있습니다. 작성 세션이 믿었던 내용을 기록하기 때문에 빠뜨리거나 잘못 기록한 내용은 독자에게 보이지 않습니다. 중요한 주장이라면 다음 세션에서 이를 물려받는 대신 1차 자료, 즉 코드와 테스트를 확인해야 합니다.

좋은 산출물은 아무 컨텍스트도 없는 세션이 읽을 수 있도록 작성됩니다. “아까 이야기한 파일” 대신 구체적인 파일 경로를 적으세요. 다음 세션이 다시 논의하지 않도록 무엇을 왜 결정했는지 설명하세요. 끝난 일과 남은 일도 기록하세요. 작성 세션에 산출물이 어디에 쓰일지 알려 주면 도움이 됩니다. “이 작업의 내용을 전혀 모르는 새 세션을 위한 인계 문서를 작성하세요.”

또 다른 전달 방법인 압축은 메모리 안의 내용을 요약합니다. 산출물에는 두 가지 장점이 있습니다. 파일로 디스크에 남으므로 다른 작업이 의존하기 전에 직접 읽고 수정할 수 있고, 재사용할 수도 있습니다. 같은 명세로 병렬 세션 다섯 개를 안내할 수 있습니다.

사용 예:

“계획 담당 에이전트와 구현 담당 에이전트 사이에 일을 어떻게 나누죠?”

“계획 담당이 파일 경로, 결정, 제약을 담은 인계 산출물을 작성하게 하세요. 구현 담당 세션은 산출물 포인터를 읽으며 시작하고 그 내용을 작업 개요로 사용하면 됩니다.”

---

여러 세션에 걸친 작업을 설명하는 인계 산출물입니다. 각 세션이 일을 어떻게 나누어 하는지가 아니라 무엇을 만들고 있는지를 기록합니다. 작업이 진행되면서 내용이 바뀝니다. 티켓으로 구성됩니다.

세션은 일회용이지만 큰 작업은 그렇지 않기 때문에 명세가 필요합니다. 컨텍스트 창을 한 번 넘기는 작업이라면 컨텍스트 바깥에 자리를 마련해야 합니다. 이전 컨텍스트를 초기화해도 남아 있는 에이전트의 환경 안의 공간, 즉 저장소 파일이나 GitHub 이슈, 에이전트가 접근할 수 있는 이슈 트래커가 될 수 있습니다. 명세가 바로 그 공간입니다. 목표와 제약, 지금까지 내린 결정, 상태가 표시된 티켓 목록을 담습니다. 새 세션은 앞서 쌓인 잡음을 물려받지 않고도 이를 읽어 작업이 어디까지 왔는지 알 수 있습니다.

명세는 팀이 이미 문서화하던 방식에서 물려받은, 쉽게 알아볼 수 있는 몇 가지 형태로 작성됩니다. 제품 요구사항 문서 (PRD)는 사용자에게 보이는 기능과 이유, 수용 기준에 초점을 둡니다. 설계 문서나 RFC는 기술적인 내용, 즉 선택한 접근법과 기각한 대안, 절충점을 다룹니다. 간단한 작업이라면 티켓 체크리스트가 있는 `plan.md` 하나로도 여러 세션에 걸친 기능을 관리할 수 있습니다. 형식보다 역할이 중요합니다. 에이전트에게는 이 문서가 모두 같습니다. 각 세션이 시작될 때 읽는, 지속 가능한 의도 선언문입니다.

사용 예:

“이걸 전부 한 세션에서 해야 할까요?”

“아니요. 명세로 정리하고 티켓으로 나눠 각 티켓을 별도 세션에서 처리하세요. 전체 작업을 컨텍스트 하나에서 끝내려 하면 절반도 가기 전에 적정 지능 구간을 벗어날 겁니다.”

---

한 번의 세션에 해당하는 일을 범위로 정하는 인계 산출물입니다. 독립적으로 사용하거나 명세의 하위 항목으로 연결할 수 있습니다. 티켓은 서로를 막거나 의존할 수 있으므로 작업 순서는 선형 계획이 아니라 의존성 그래프에서 정해집니다.

핵심 제약은 규모입니다. 티켓 하나는 세션이 적정 지능 구간을 벗어나기 전에 완료할 수 있어야 하며, 이 제약은 검증할 수 있습니다. 티켓 작업이 끝나기 전에 세션이 자주 퇴화한다면 티켓이 너무 큰 것이므로 나누세요. 각 세션이 5분만 작업하기 전에 대부분의 컨텍스트를 설정에 쓴다면 티켓이 너무 작은 것이므로 합치세요.

좋은 티켓은 다른 맥락이 없는 독자를 위해 작성됩니다. 목표와 수용 기준, 관련 파일과 결정으로 연결되는 컨텍스트 포인터를 담아야 합니다. 마지막 세션에서 알았던 내용을 다시 추론하지 않고도 새 세션이 작업을 시작할 수 있을 만큼 충분해야 합니다.

의존성 그래프는 병렬 작업도 가능하게 합니다. 서로 독립적인 티켓, 즉 그래프의 잎 노드는 각자 별도 세션에서 동시에 처리할 수 있습니다. 이는 여러 에이전트를 동시에 운영하는 효과적인 방법입니다. 소프트웨어 공장에서는 티켓이 준비 상태로 표시되는 순간 해당 세션을 시작하는 트리거가 되기도 합니다.

사용 예:

“마이그레이션 명세는 어디서부터 시작하죠?”

“티켓 그래프를 보세요. 스키마 변경이 백필에 선행하고, 백필이 API 전환에 선행합니다. 잎 노드를 골라 세션 하나를 시작하면 됩니다.”

---

메모리에서 수행하는 작업 인계입니다. 이전 세션의 기록을 요약해 새 세션을 시작하는 데 사용합니다. 의도적으로 손실이 발생합니다. 대화 기록은 1차 자료이고 요약은 2차 자료이므로 세부 내용을 줄여 여유 공간을 확보합니다. 사용자가 직접 시작하거나 자동 압축이 자동으로 실행합니다.

작동 방식은 이렇습니다. 컨텍스트 창은 용량이 정해져 있고, 긴 세션은 그 공간을 채웁니다. 모든 도구 결과, 파일 읽기, 잘못된 시도가 기록에 남습니다. 기록이 무거워지면 하네스가 모델에 세션을 요약하게 한 뒤 원래 기록을 버리고 요약으로 새 세션을 시작합니다. 요약에 포함되지 못한 내용은 컨텍스트에서 사라집니다. 일부 하네스는 기존 기록을 디스크에 보존하고 요약에 그 기록을 가리키는 컨텍스트 포인터를 남겨 이 손실을 줄입니다. 그러면 2차 자료가 1차 자료를 연결해 주므로 요약에서 빠진 세부 사항을 원본을 다시 읽어 복구할 수 있습니다.

요약은 모델이 작성하므로 프롬프트로 조정할 수 있습니다. “스키마 결정은 보존하세요”라고 하면 산출물을 더 신중하게 만들 수 있습니다. 시점도 중요합니다. 작업 중간이 아니라 계획이 확정된 뒤 단계가 끝나는 시점에 압축하세요.

모든 것을 버리고 새로 시작하는 초기화와 비교해 보세요. 압축은 핵심을 다음 세션으로 가져가려 하고, 초기화는 핵심이 더 나은 곳에 이미 기록돼 있으리라 기대합니다.

사용 예:

“컨텍스트가 무거워졌는데 테스트도 아직 돌려야 해요.”

“시작하기 전에 압축하세요. 새 세션이 스키마 결정을 유지하고 탐색 과정은 버리도록 요약 프롬프트에 남아야 할 내용을 적으세요.”

---

컨텍스트 창이 가득 차려 할 때 하네스가 자동으로 시작하는 압축입니다.

하네스는 컨텍스트 창이 얼마나 찼는지 감시합니다. 보통 80% 안팎의 임계점을 넘으면 실행을 잠시 멈추고 모델에 지금까지의 세션을 요약하게 한 뒤 요약으로 새 세션을 시작합니다. 그다음에는 아무 일도 없었던 것처럼 작업이 계속됩니다.

하지만 실제로는 일이 일어났습니다. 압축은 정보를 잃으며 자동 압축은 사용자가 시점을 고르지 못한 상태에서 정보를 잃습니다. 수동 압축은 단계가 끝나는 시점에 실행해 모델에 무엇을 보존할지 알려 줄 수 있습니다. 자동 압축은 임계점에 도달하는 순간, 리팩터링 도중이라도 실행되며 어떤 결정을 남길지 요약이 스스로 선택합니다. 전형적인 징후는 에이전트가 자신 있게 작업을 계속하지만 한 시간 전에 정한 제약을 조용히 잊고, 작업이 그 제약과 모순되기 시작할 때야 알아차리는 것입니다.

대응 방법은 자동 압축이 실행되지 않게 하는 것입니다. 컨텍스트 표시기를 확인하고 자연스러운 경계에서 직접 압축하거나 결정을 계획 문서 또는 디스크의 인계 산출물에 기록하세요. 그러면 요약이 이를 잃을 수 없습니다. 대부분의 하네스에서는 완충 영역도 설정할 수 있습니다. 임계점을 앞당기거나 늦추거나 자동 압축을 완전히 꺼서 실행 전 여유 공간을 조절할 수 있습니다.

사용 예:

“스키마에 대해 앞서 정한 내용을 기억하지 못하는 것 같아요.”

“턴 사이에 자동 압축이 실행되어 초기 결정이 요약되면서 무언가 빠진 것 같습니다. 계획 문서를 다시 불러오거나 다음에는 직접 압축해 무엇을 남길지 정하세요.”

---

에이전트를 여러 세션에 걸쳐 상태 저장형으로 만들려는 시스템입니다. 세션 중에 정보를 환경에 저장했다가 다음 세션이 시작될 때 컨텍스트 창에 다시 불러와 사용자가 세션을 초기화한 뒤에도 연속성이 유지되게 합니다.

메모리 시스템에는 두 부분이 있습니다. 쓰기 경로에서는 세션 중 에이전트가 사용자가 밝힌 선호나 프로젝트에 관한 사실 등 배운 내용을 환경 안의 파일로 기록합니다. 읽기 경로에서는 세션이 시작될 때 하네스가 해당 파일이나 파일의 색인을 컨텍스트 창에 다시 불러옵니다. 많은 하네스에는 자체 메모리 시스템이 포함되어 있습니다. Claude Code의 `/memory`가 그 예입니다. 직접 만들 수도 있습니다. 메모 디렉터리와 메모를 참조하라는 AGENTS.md의 지시를 함께 두면 됩니다.

항상 불러오는 콘텐츠라면 모두 같은 절충점이 적용됩니다. 메모리가 쌓이므로 대부분의 시스템은 한 줄짜리 색인만 불러오고 본문은 전부 인라인으로 넣는 대신 컨텍스트 포인터 뒤에 둡니다. 메모리는 2차 자료이므로 오래되기도 합니다. 3월에 기록한 사실이 프로젝트가 바뀐 6월에도 같은 신뢰도로 불러와집니다. 메모리 시스템에도 AGENTS.md와 마찬가지로 정리가 필요합니다.

사용 예:

“Postgres를 쓰고 MySQL은 쓰지 않는다고 계속 다시 말해야 해요.”

“메모리 시스템을 연결하세요. 첫 턴에서 학습한 내용을 파일 시스템에 기록하고 세션을 시작할 때 다시 불러오세요. 모델 자체는 무상태이므로 메모리 계층이 연속성이 있는 것처럼 만들어 줍니다.”

---

세션이 시작될 때 하네스가 컨텍스트 창에 불러오는 환경 내 파일입니다. 프로젝트가 에이전트에게 제공하는 상시 브리프입니다. 여러 하네스에서 통용되는 관례이며 일부 하네스에는 자체 변형도 있습니다. 예를 들어 Claude Code에서는 CLAUDE.md를 사용합니다.

자동으로 불러오므로 세션마다 같은 내용을 반복하지 않는 방법입니다. 모델은 무상태입니다. 한 세션에서 받은 수정 지시는 다음 세션에 전달되지 않으므로 매번 새 세션에 프로젝트가 pnpm을 사용한다거나, 특정 플래그로 테스트를 실행한다거나, 어떤 디렉터리는 생성된 것이니 건드리지 말라고 알려 줘야 합니다. 같은 내용을 두 번 수정해 준 적이 있다면 그 내용을 AGENTS.md에 넣을 후보로 볼 수 있습니다.

코드만으로 에이전트가 알아낼 수 없는 내용이 적절합니다. 빌드 및 테스트 명령, 코드베이스만 보고는 알기 어려운 관례, “생성된 클라이언트는 절대 편집하지 말 것” 같은 엄격한 제약입니다. 문서가 아니라 브리프이므로 짧고 선언적으로 작성하세요.

절충점은 모든 내용이 항상 로드된다는 것입니다. 지시가 쌓이고 대부분은 특정 작업과 무관해집니다. 긴 AGENTS.md는 토큰을 소모하고 스스로 효과도 약화합니다. 컨텍스트에 지시가 많아질수록 특정 지시 하나를 모델이 따르는 신뢰성은 떨어집니다.

피하기: 점진적 공개 방식이어야 할 내용을 AGENTS.md에 넣지 마세요. 어떤 내용이든 모든 세션, 모든 턴에서 해당 토큰 비용을 지불해야 합니다. 스타일 가이드는 스킬이나 컨텍스트 포인터 뒤에 둘 수 있습니다. AGENTS.md에는 모든 상황에 적용되는 규칙만 남기세요.

사용 예:

“왜 모든 세션이 토큰 4,000개를 이미 쓴 채로 시작하죠?”

“AGENTS.md를 확인하세요. 누군가 전체 스타일 가이드를 스킬 뒤에 두지 않고 거기에 붙여 넣었네요.”

---

지금 에이전트에게 필요한 컨텍스트만 불러오고 나머지는 컨텍스트 포인터로 연결하는 방식입니다. 현재 작업에 필요한 컨트롤만 보여 주고 나머지는 클릭 뒤에 감추는 UI 디자인 개념에서 가져왔습니다.

컨텍스트는 두 번 비용을 발생시키므로 이 기법이 필요합니다. 미리 불러온 모든 토큰은 매 턴마다 입력 토큰으로 청구되며, 필요한지와 관계없이 에이전트의 주의력 예산을 씁니다. 전체 스타일 가이드와 배포 런북, 데이터베이스 관례를 전부 넣은 AGENTS.md는 모든 면에서 에이전트의 능력을 떨어뜨립니다. 지금 작업에 중요한 지시는 관련 없는 지시에 희석됩니다. 이를 알아볼 수 있는 징후는 컨텍스트에 있다는 사실을 알고 있는 규칙을 에이전트가 무시하는 것입니다. 규칙은 들어 있지만 묻혀 있습니다.

점진적 공개는 이를 뒤집습니다. 항상 불러오는 계층은 작게 유지하세요. 주제마다 한 문장과 세부 내용의 포인터만 둡니다. 구성 요소를 작성할 때는 스타일 가이드를, 배포할 때는 배포 런북을 읽고, 테스트를 고칠 때는 둘 다 읽지 않게 합니다. 스킬은 하네스에 내장된 패턴입니다. 짧은 설명은 매 세션에 불러오고, 전체 지침은 해당 스킬이 실행될 때만 불러옵니다.

사용 예:

“스타일 가이드 전체를 AGENTS.md에 붙여 넣어야 할까요?”

“아니요. 점진적 공개를 사용하세요. 에이전트가 구성 요소를 작성할 때 필요한 스타일 가이드를 스킬로 참조하세요. AGENTS.md는 매 턴 토큰 비용을 발생시킵니다.”

---

한 문서에서 다른 문서를 가리키는 언급입니다. 작업에서 필요한 경우에만 에이전트가 이를 컨텍스트 창에 불러올 수 있습니다. 점진적 공개는 이 단위를 활용합니다.

내용을 인라인으로 넣는 대신 포인터를 사용하는 이유는 비용입니다. 컨텍스트 창에서 포인터는 한 줄만 차지합니다. 포인터가 가리키는 문서는 토큰을 수천 개 담고 있을 수 있지만, 에이전트가 실제로 따라가기 전까지는 그 토큰에 비용이 들지 않습니다. 토큰 2,000개 분량의 운영 절차서를 AGENTS.md에 인라인으로 넣으면 모든 세션이 비용을 냅니다. 대신 “배포 절차: `internal/deploy.md` 참조”라고 적으면 배포를 하는 세션만 문서를 불러옵니다. 작업이 관련 있을 때 에이전트는 도구 호출로 포인터를 따라갑니다.

포인터가 작동하려면 안정된 경로와 그 경로를 따라갈 가치가 있는 시점을 에이전트가 알 수 있게 하는 충분한 설명, 두 가지가 필요합니다. 맨 경로만 있으면 에이전트가 따라갈 이유를 알 수 없습니다. “`internal/deploy.md` 참조”라고만 쓰고 내용 설명이 없으면 필요한 세션이 건너뛸 수 있습니다. 작업이 제시되는 방식과 일치하도록 문구를 작성하세요. “릴리스, 배포 또는 롤백 — 먼저 `internal/deploy.md`를 읽을 것.”

살펴보기 시작하면 포인터는 어디에나 있습니다. AGENTS.md의 줄, 스킬 설명(하네스는 설명을 불러오고 본문은 그 뒤에 둡니다), 디렉터리 목록의 파일 이름, 문서 사이의 링크가 모두 포인터입니다.

포인터는 2차 자료를 그 자료가 파생된 1차 자료에 다시 연결할 수도 있습니다. 원본 대화 기록을 가리키는 압축 요약이나, 설명하는 원본 파일을 표시한 문서가 예입니다. 이 연결 덕분에 2차 자료에서 생긴 손실을 복구할 수 있습니다. 요약만으로 충분하지 않다는 사실이 드러나면, 에이전트는 포인터를 따라 원본을 읽고 요약에 남은 내용에만 의존하지 않습니다.

피하기: “참조” — 너무 건조해서 이를 따라가면 컨텍스트가 추가된다는 느낌을 주지 못합니다. “포털” — 지나치게 화려합니다.

사용 예:

“AGENTS.md가 너무 커지고 있어요.”

“대부분은 내용이 아니라 컨텍스트 포인터여야 합니다. 항상 적용되는 규칙은 인라인으로 두고 배포 절차와 스타일 가이드는 스킬로 만든 뒤 컨텍스트 포인터만 남기세요.”

---

한 가지 작업을 잘 수행하는 데 필요한 지침과 리소스를 하나로 묶은 교육 가능한 기능입니다. 컨텍스트 포인터가 현재 작업에 맞춰 컨텍스트 창에 불러올 때까지 환경에 보관됩니다. 하네스에서 점진적 공개를 구성하는 단위입니다.

스킬은 agentskills.io에서 정의한 개방형 표준입니다. Anthropic이 처음 개발했고 이후 주요 하네스 대부분이 채택했으므로 한 번 작성한 스킬을 여러 곳에서 사용할 수 있습니다. 스킬은 다음을 포함한 폴더 형식입니다.

• `SKILL.md` 파일 — 메타데이터(최소한 이름과 설명) 및 실제 지침
• 선택 사항: 에이전트가 실행할 수 있는 스크립트
• 선택 사항: 지침이 가리키는 템플릿과 참고 자료

기본적으로 이름과 설명만 컨텍스트에 들어갑니다. 에이전트가 맡은 작업이 스킬과 관련 있을 때 나머지 내용을 불러옵니다. 그때까지 스킬은 전체 지침이 아무리 길어도 토큰 한두 문장 정도만 차지합니다.

스킬은 어떤 작업인지와 관계없이 모든 세션에 불러오는 AGENTS.md와 다릅니다. 스킬은 릴리스, 새 서비스의 기본 골격 작성, 마이그레이션 작성 등 특정 작업이 생겼을 때 읽고, 그 외에는 무시합니다.

피하기: “도구” — 도구는 에이전트가 호출하는 것이고, 스킬은 에이전트가 읽는 지침입니다.

사용 예:

“배포 런북은 어디에 두면 좋을까요?”

“스킬로 두세요. 배포 작업일 때만 에이전트가 불러옵니다. AGENTS.md에 넣으면 매주 한 번 쓰는 내용을 모든 턴에서 토큰 비용을 들여가며 불러와야 합니다.”

---

다른 에이전트가 도구 호출로 시작한 에이전트입니다. 자체 세션과 컨텍스트 창에서 실행하고 단일 도구 결과를 돌려줍니다. 작업 인계와는 다릅니다. 부모는 하위 에이전트의 결과를 돌려받을 것을 기대하지만, 작업 인계에는 반환 경로가 없습니다. 하위 에이전트는 다른 하위 에이전트를 시작할 수 없습니다. 트리는 한 단계 깊이입니다. 하위 에이전트는 컨텍스트를 계층적으로 구성하기 위한 것이 아니라 격리하기 위한 것입니다.

목적은 시끄러운 작업이 부모의 컨텍스트를 채우지 않게 하는 것입니다. 광범위한 검색이나 긴 파일 조사에서는 도구 결과가 여러 페이지 나오지만 대부분은 답을 찾는 동안에만 필요합니다. 부모 안에서 직접 작업하면 그 결과가 세션의 나머지 시간 동안 부모 컨텍스트에 남습니다. 하위 에이전트 안에서 실행하면 잡음은 일회용 창에 담기고, 최종 보고서만 부모에게 전달됩니다. 그 보고서는 2차 자료입니다. 부모는 원본 결과가 아니라 하위 에이전트의 설명을 받으므로 보고서에서 빠진 내용은 부모가 알 수 없습니다.

하위 에이전트는 병렬로도 실행됩니다. 부모는 서로 독립적인 작업에 여러 하위 에이전트를 동시에 투입할 수 있습니다.

사용 예:

“grep 결과 때문에 컨텍스트가 넘치고 있어요.”

“검색을 하위 에이전트에게 맡기세요. 잡음은 자체 컨텍스트 창에서 처리하고 필요한 파일 경로 두 개만 보고할 겁니다.”

---

세션 중에 한 명 이상의 사람이 에이전트와 짝을 이루어 실시간으로 검토하거나 방향을 바꾸거나 함께 작업하는 방식입니다. 사람은 개별 동작만 승인하는 것이 아니라 작업에 참여해 함께합니다.

반대되는 방식은 에이전트가 감독 없이 실행되고 결과를 나중에 평가하는 자리 비움 작업입니다. 사람 참여형 작업은 문제가 아직 바로잡기 쉬울 때 발견할 수 있다는 뜻입니다. 에이전트가 잘못된 파일을 선택하거나, 요구사항을 잘못 읽거나, 막다른 길로 가기 시작하는 것을 보고 한 문장으로 방향을 바꾸면 됩니다. 자신만만한 상태로 잘못된 가정에 따라 20분간 작업한 결과를 나중에 발견하는 대신 말이죠. 에이전트는 자신이 잘못된 길에 있는 때를 안정적으로 알아채지 못합니다. 혼자 두면 멈춰서 질문하기보다 계속 나아가는 경향이 있습니다.

어떤 방식이 맞는지는 작업에 달려 있습니다. 명세가 분명하고 위험이 낮으며 검증하기 쉬운 작업은 자리 비움에 적합합니다. 모호하거나 되돌릴 수 없거나 완료된 결과를 검토하기 어려운 작업, 예를 들어 스키마 마이그레이션이나 까다로운 설계 결정, 프로덕션에 영향을 주는 일은 작업에 계속 참여하는 편이 좋습니다. 판단 기준은 간단합니다. 잘못된 방향으로 가는 데 드는 비용은 얼마이며, 얼마나 늦게 알아차릴까요?

사용자의 반응이 입력이므로 본질적으로 사람이 참여해야 하는 작업도 있습니다. 꼼꼼하게 캐묻기는 질문에 답할 사람이 있어야 작동하고, 프로토타이핑은 산출물에 반응할 사람이 있어야 작동합니다.

계속 참여하면 주의력을 사용합니다. 주의력은 희소한 자원입니다. 에이전트 활용을 개선하는 방법의 하나는 계획, 자동 검사, 마지막의 사람 검토를 활용해 안전을 유지하면서 더 많은 작업을 감독 범위 밖으로 옮기는 것입니다. 소프트웨어 공장은 트리거로 세션을 시작해 이를 한 단계 더 발전시키므로 작업을 시작하는 일조차 직접 할 필요가 없습니다.

사용 예:

“밤새 이 작업을 자리 비움으로 실행할까요?”

“아니요. 스키마 마이그레이션이니 사람이 참여하도록 하세요. 각 단계를 보고 백필할 열을 잘못 고르면 방향을 바로잡고 싶습니다.”

---

키보드에서 떨어져 있음. 사용자가 세션을 시작한 뒤 에이전트를 감독 없이 실행하도록 두는 작업 방식입니다. AI 코딩의 처리량 배율 효과입니다. 잠을 자거나 식사하거나 다른 일을 하는 동안 여러 자리 비움 세션을 병렬로 실행할 수 있습니다. 안전하게 하려면 대개 허용적인 권한 모드와 샌드박싱이 필요합니다.

사용자가 없으면 에이전트는 모호한 결정을 다르게 처리합니다. 사용자가 지켜보는 동안 모호한 결정은 질문으로 드러나 답할 수 있습니다. 자리를 비우면 에이전트가 기본값을 고르고 계속 진행하며, 이후의 모든 결정은 그 추측을 바탕으로 쌓입니다. 전형적인 실패는 처음 10분에 잘못 내린 판단을 바탕으로 자신감 있게 완성한 작업을 몇 시간 뒤 돌아와서 발견하는 것입니다. 작업이 엉성한 것은 아닙니다. 일관성은 있지만 잘못된 전제에 대한 일관성입니다.

실행 중에는 입력할 수 없으므로 시작 전과 종료 후에 입력하세요. 시작 전에는 꼼꼼하게 캐묻기 세션이나 작성된 명세로 모호함을 해결해 에이전트가 혼자 채워야 할 빈틈을 줄이세요. 실행 중에는 자동 검사와 자동 검토가 주의를 대신해 기계적으로 잡을 수 있는 문제를 빠르게 실패시킵니다. 종료 후에는 병합이 이미 끝난 변경이 아니라 PR처럼 검토 가능한 결과를 받으세요. 자리 비움은 사람의 검토를 없애는 것이 아니라 끝까지 미룹니다. 따라서 끝에 도착한 결과는 검토할 가치가 있어야 합니다. AX가 자리 비움 실행에서 가장 중요한 이유도 같습니다. 지켜보는 사람이 없으면 에이전트가 의지할 것은 환경뿐입니다.

피하기: “백그라운드 에이전트” — 사람의 작업 방식(사용자가 자리를 비움)보다 기계(백그라운드 실행)를 강조합니다. AFK는 중요한 사실, 즉 사용자가 지켜보지 않는다는 점을 나타냅니다.

사용 예:

“이걸 밤새 자리 비움으로 실행합니다. 리팩터링에 샌드박스로 격리한 에이전트 세 개를 돌리고 아침에 PR을 검토할게요.”

“권한 우회로요?”

“네. 읽기 전용 파일 시스템에 네트워크는 차단할게요.”

---

환경에서 실행되는 결정론적 검증입니다. 테스트, 타입 검사, 린트, 빌드, 커밋 전 훅 등이 해당합니다. 판단 없이 통과 또는 실패만 반환합니다. 다른 사람을 개입시키지 않고 에이전트가 스스로 수정하는 데 이용할 수 있는 신호입니다. 불안정한 테스트는 검사가 아닌 것이 아니라 고장 난 검사입니다. 자동 검사는 설계상 결정론적이어야 합니다.

자기 수정은 반복 루프로 작동합니다. 에이전트가 변경을 만들고, 도구 호출로 검사를 실행하면 실패 출력이 컨텍스트 창에 들어옵니다. 파일과 줄이 표시된 타입 오류, 기대값과 실제값이 담긴 실패 어설션 같은 정보입니다. 이 정도면 사람의 개입 없이 에이전트가 문제를 고치고 검사를 반복해 통과할 수 있습니다. 결정론이 이 루프를 신뢰할 수 있게 합니다. 같은 코드에는 항상 같은 판정이 나오므로 통과가 의미를 갖습니다. 불안정한 검사는 이를 망칩니다. 멀쩡한 코드를 ‘수정’하거나 실제 실패를 재시도로 넘어가게 만듭니다.

좋은 검사가 코드베이스의 AX에 큰 부분을 차지하는 이유도 이 때문입니다. 엄격한 타입과 빠른 테스트 모음, 린터가 있는 저장소에서 에이전트는 대부분의 실수를 사용자가 보기 전에 잡습니다. 이런 도구가 없는 저장소에서는 만들어 낸 결과를 그대로 내보냅니다. 이 차이는 자리 비움 실행에서 특히 중요합니다. 실행 중에는 검사가 유일한 검증이기 때문입니다. 하지만 검사는 어설션한 내용만 잡아냅니다. 초록색 검사는 어설션한 속성이 성립한다는 뜻이지 코드가 올바르다는 뜻은 아닙니다. 판단이 필요한 공백은 자동 검토와 사람의 검토가 맡습니다.

피하기: “피드백 루프” / “백프레셔” — 둘 다 검사를 검토와 한데 묶습니다. 피하기: “테스트” — 테스트는 자동 검사에 포함되지만 자동 검사가 모두 테스트인 것은 아닙니다.

사용 예:

“에이전트가 자리 비움 실행에서 계속 고장 난 코드를 내보내요.”

“샌드박스에 어떤 자동 검사가 연결돼 있나요?”

“단위 테스트뿐이에요.”

“타입 검사와 린트를 추가하세요. PR이 올라오기 전에 그 결과로 스스로 수정할 겁니다.”

---

한 에이전트가 다른 에이전트의 작업을 검토하는 일입니다. 흔히 다른 모델이나 시스템 프롬프트를 사용합니다. 비결정적이며 판단을 내립니다. PR 병합 전, 커밋 이력에 대한 사후 검토, 하위 에이전트로 세션 중간 등 어디서든 실행할 수 있습니다. CI에서 LLM을 심판으로 쓰는 것은 자동 검토이지 자동 검사가 아닙니다. 어디에서 실행되는지가 아니라 어설션이 하는 일에 따라 유형이 결정됩니다.

작업 에이전트와 검토 에이전트를 분리해야 효과가 있습니다. 코드를 작성한 에이전트에게 자기 작업을 검토하라고 하면 얻는 것이 거의 없습니다. 버그를 만든 세션 안에는 버그를 만든 추론도 들어 있고, 에이전트는 자신의 결론을 다시 읽으며 이를 확인으로 받아들입니다. 새 컨텍스트 창을 가진 검토자는 그런 애착이 없습니다. 검토에 필요한 대로 낯선 사람처럼 diff를 볼 수 있습니다. 다른 모델이나 검토 전용 시스템 프롬프트를 쓰면 효과가 더 커집니다. 사각지대가 달라지고, “문제를 찾아라”처럼 모호한 지시보다 실제 관심사(보안, API 계약, 성능)에 초점을 둘 수 있습니다.

다른 검토 계층 사이에서 역할을 합니다. 자동 검사는 결정론적이며 기계적으로 어설션할 수 있는 내용을 확인하고, 사람의 검토는 비용이 높고 확장하기도 가장 어렵습니다. 자동 검토는 중간에 놓입니다. 오해를 부르는 함수 이름이나 놓친 예외 사례처럼 판단이 필요한 문제를 기계 비용으로 찾습니다. 비결정적이므로 놓치는 문제도, 문제가 아닌 것을 표시하는 경우도 있습니다. 사람의 검토를 대체하는 관문이 아니라 사람이 보기 전 기본 품질을 끌어올리는 필터로 다루세요.

피하기: “AI 검토” / “에이전트 검토” — 실제 작업 에이전트와 구별하기에 너무 모호합니다.

사용 예:

“자리 비움 실행에서 나쁜 PR이 너무 많이 올라와요.”

“병합 전에 자동 검토 단계를 추가하세요. 다른 모델과 별도 시스템 프롬프트를 사용해 보안과 계약 변경에 초점을 맞추세요.”

---

에이전트가 만든 코드를 사용자가 읽고 판단하는 일입니다. diff나 변경된 파일을 읽는 것은 해당하지만 에이전트가 한 일에 대한 설명만 읽는 것은 해당하지 않습니다. 설명은 산출물이 아닙니다. 설명은 검토받는 당사자가 쓴 2차 자료이고 diff는 1차 자료이므로 검토란 diff를 읽는 것입니다.

에이전트가 코드를 더 많이 만들면 검토가 병목이 됩니다. 유용한 접근법 하나는 검토 전략을 층별로 나누는 것입니다. 자동 검사는 기계적으로 판별할 수 있는 실패를 잡고, 자동 검토는 설명할 수 있는 문제를 잡습니다. 사람의 검토는 변경이 올바른지, 코드베이스에 맞는 접근인지, 그 기능 자체가 있어야 하는지처럼 사용자만 판단할 수 있는 문제에 집중합니다.

검토는 일찍 할수록 저렴합니다. 작업을 시작하기 전에 계획을 읽거나 진행 중에 작은 diff를 보는 데는 몇 분이면 됩니다. 자리 비움 실행이 끝난 뒤 완성된 브랜치를 파헤치는 데는 더 오래 걸립니다. 검토를 어디에 둘지는 사후에 덧붙일 일이 아니라 사람 참여형 설계 결정입니다.

피하기: “코드 검토”만 쓰면 사람 검토와 자동 검토 중 무엇인지 모호합니다.

사용 예:

“자리 비움 실행에서 나온 결과를 제가 직접 검토했어요.”

“diff를 읽었나요, 요약만 읽었나요?”

“diff요. 요약에는 사용하지 않는 코드를 삭제했다고 되어 있었는데 알고 보니 생성된 파일에서 그 함수를 호출하고 있더군요.”

---

사용자가 에이전트의 코드를 사람이 검토하지 않고 받아들이는 작업 방식입니다. diff는 내부를 알 수 없는 것으로 취급하고, 코드가 어떤 모양인지보다 프로그램이 작동하는지가 중요합니다. 자동 검토와 자동 검사는 실행될 수도 있지만, 바이브 코딩은 어느 쪽도 규정하지 않습니다.

이 용어는 Andrej Karpathy가 2025년 초에 만들었습니다. “분위기에 완전히 맡기고”, “코드가 존재한다는 사실도 잊어버린다”는 뜻입니다. 원하는 것을 설명하고, 돌아온 결과를 받아들인 다음, 실행해 판단합니다.

바이브 코딩은 검토를 속도와 맞바꿉니다. diff를 읽는 일은 에이전트 주도 작업에서 대개 가장 느린 단계이므로 이를 생략하면 주된 병목이 사라집니다. 실패 비용이 낮은 코드, 예를 들어 프로토타입, 일회성 스크립트, 내부 도구라면 합리적인 절충입니다. 위험은 코드의 수명과 중요도에 따라 커집니다.

비용은 나중에 발생합니다. 바이브 코딩한 변경이 아무도 읽지 않은 코드베이스에 쌓입니다. 동작만 확인했으므로 동작에 드러나지 않는 문제, 예를 들어 로그에 기록된 비밀, 빠진 예외 사례, 조용히 잘못 처리되는 데이터는 발견되지 않은 채 배포됩니다. 누군가 시스템을 디버깅할 때가 처음으로 코드를 읽는 순간입니다. 사람이 검토하지 않으면 여전히 실행되는 자동 검증, 즉 테스트와 타입 검사, 자동 검토만이 코드가 통과하는 유일한 관문입니다. 소프트웨어 공장에서 나온 변경을 대상으로 코드베이스 전체나 일부에 같은 태도를 적용하면 다크 팩토리가 됩니다.

피하기: “바이브 코딩”을 “품질이 낮은 AI 코딩”의 동의어로 쓰지 마세요. 이 용어는 결과 코드의 품질이 아니라 검토 방식에 관한 것입니다.

사용 예:

“인증 흐름에서 바꾼 내용을 읽어 봤나요?”

“바이브 코딩했어요. 로그인이 계속 작동하는지만 확인했습니다.”

“푸시 전에 diff를 읽으세요. 인증을 분위기에 맡기면 비밀이 로그에 새어 나갑니다.”

---

무엇을 만들고 있는지에 대해 사용자와 에이전트가 함께 공유하지만 어떤 산출물과도 동일하지 않은 이해입니다. Brooks가 The Design of Design에서 쓴 용어입니다. 대화와 인계 산출물, 코드는 모두 디자인 콘셉트를 담거나 그에 도달하려는 산출물이지만 그 자체가 콘셉트는 아닙니다. 디자인 콘셉트의 품질은 이를 만들어 가는 대화의 품질로 드러납니다.

이 용어는 익숙한 좌절감의 배경에 있는 간극을 가리킵니다. 에이전트가 요청한 그대로 작성했는데도 결과가 틀립니다. 흔한 원인은 사용자가 원하는 것을 충분히 구체화하지 않았다는 것입니다. 사용자의 머릿속에서도 디자인 콘셉트가 완성되지 않았습니다. 프롬프트에는 이미 고민한 부분만 담기고 아직 생각하지 않은 부분은 빠졌습니다. 에이전트는 맞춰야 할 기준이 없으므로 그 침묵을 자신의 가정으로 채웠습니다. 고장 난 것은 없습니다. 공유할 만한 전체 디자인 콘셉트가 아직 없었기에 공유된 것도 없었습니다.

동료와 마찬가지로 상대가 아직 묻지 않은 질문에도 사용자가 할 법한 방식으로 답하기 시작하면 디자인 콘셉트가 공유되고 있음을 알 수 있습니다. 그전까지는 대화가 계속되어야 합니다. 꼼꼼하게 캐묻기는 이를 의도적으로 수행하는 방식입니다. 너무 일찍 명세를 작성하면 어긋난 이해를 더 오래 남는 산출물에 담을 뿐입니다. 배우는 과정에서 디자인 콘셉트도 계속 바뀝니다. 산출물은 뒤처질 수 있으므로 지난주 이해를 충실히 기록한 명세라도 이번 주 세션을 잘못 이끌 수 있습니다.

사용 예:

“요청한 그대로 작성하는데도 계속 틀려요.”

“아직 디자인 콘셉트를 공유하지 못했습니다. 에이전트가 빈틈을 가정으로 채우고 있어요. 명세를 작성하게 하기 전에 취소, 환불, 부분 이행을 두 사람 모두 같은 뜻으로 이해할 때까지 대화하세요.”

---

에이전트와 함께 디자인 콘셉트를 발전시키는 기법입니다. 에이전트가 사용자를 소크라테스식으로 인터뷰하며 한 번에 하나씩 결정을 내리고 각 항목에 권장 답변을 제시합니다. 완성된 계획으로 급히 넘어가는 속도를 늦추며, 콘셉트가 안정될 때까지 인계 산출물을 작성하지 않습니다.

이 기법이 필요한 이유는 에이전트가 빈틈을 조용히 채우기 때문입니다. 두 줄짜리 프롬프트로 명세를 써 달라고 하면 아직 정하지 않은 부분을 멈춰서 질문하는 대신 기본값을 선택해 문서에 넣습니다. 결과물은 완성된 것처럼 보이고 추측과 결정이 구별되지 않으므로 검토할 때나 구현된 기능이 예상하지 못한 예외를 처리할 때 뒤늦게 알아차립니다. 꼼꼼하게 캐묻기는 이를 뒤집습니다. 추측하는 대신 에이전트가 질문하게 합니다.

이 기법은 사람 참여형입니다. 사용자의 답이 입력입니다. 대화로 답할 수 없는 질문, 직접 봐야 판단할 수 있는 질문이 생기면 프로토타이핑으로 전환하세요.

사용 예:

“바로 명세부터 쓰더니 취소 처리 로직을 잘못 만들었어요.”

“먼저 꼼꼼하게 캐물으세요. 문서에 반영하기 전에 부분 취소, 환불, 시점에 대해 질문하게 하세요. 대화에서 해결하는 편이 코드로 해결하는 것보다 비용이 적습니다.”

---

대화만으로는 충실도가 낮아 실제 산출물을 놓고 이야기해야 할 때 에이전트에게 빠르고 거친 버전을 만들게 하는 것입니다.

꼼꼼하게 캐묻기는 대화로 설계 결정을 해결합니다. 대화는 저렴하지만 충실도가 낮습니다. 상호작용의 느낌, 실제 호출 코드에서 API 형태가 사용하기 편한지, 실제 데이터 크기에서 레이아웃이 작동하는지처럼 말만으로 답할 수 없는 질문이 있습니다. 인터뷰를 하다가 “모르겠어요. 직접 봐야겠어요”라는 솔직한 답을 하게 됩니다. 그다음부터 논의는 제자리걸음을 합니다. 대신 에이전트에게 만들어 보게 하고, 직접 살펴본 뒤 답을 가지고 대화를 이어 가세요.

에이전트가 제작 비용을 낮춰 주므로 이 방법을 실용적으로 사용할 수 있습니다. 예전에는 하루 걸리던 대략적인 모형이 이제는 몇 분이면 만들어지므로 일상적으로 해 볼 가치가 있습니다. 사람 참여형 기법입니다. 사용자가 반응할 수 있도록 프로토타입을 만드는 것입니다.

대개 한 번 보고 끝내지는 않습니다. 프로토타입을 반복하며 반응하고, 수정을 요청하고, 다시 반응하세요. 각 과정에서 실제 산출물을 기준으로 다음 결정을 해결할 수 있으며 대화보다 충실도가 높습니다.

프로토타입을 모두 거칠게 만들 필요는 없습니다. 실제로 평가하는 부분을 프로덕션 품질로 만들면 결정을 내린 뒤 사용자가 반응한 구성 요소나 API를 실제 코드베이스로 옮길 수 있습니다. 따라서 프로토타입은 명세가 참조할 핵심 자료가 됩니다.

사용 예:

“마법사를 한 페이지로 할지 세 단계로 나눌지 30분째 논쟁하고 있어요.”

“말로는 결정이 안 나요. 에이전트에게 두 가지를 모두 프로토타이핑하게 하세요. 눌러 보면 5분 안에 답을 알 수 있습니다.”

---

개발자 경험, 즉 코드베이스와 도구 체계가 사람의 작업을 얼마나 쉽게 만드는지를 뜻합니다. 좋은 DX에는 빠른 피드백, 이해하기 쉬운 오류 메시지, 실제로 궁금한 점에 답하는 문서, 첫 시도부터 작동하는 설정이 포함됩니다. 이 용어는 AI 코딩보다 훨씬 오래됐습니다. 이 사전에서는 AX와 대비하기 위해 주로 다룹니다.

DX는 사람과 코드베이스가 상호작용하는 경험이며 그 이상도 이하도 아닙니다. 두 사용자층의 주요 차이는 사람이 상태 저장형이고 에이전트가 무상태형이라는 점입니다. 사람은 코드베이스를 한 번 익히고 그 지식을 매일 이어 갑니다. 그래서 나쁜 DX도 견딜 수 있습니다. 느린 CI는 푸시를 모아서 우회하고, 문서가 없으면 Slack에 한 번 물어보고, 복잡한 구조는 파일 위치를 외워 해결합니다. 이런 우회 방법이 쌓여 팀은 자신들을 방해하는 코드베이스에서도 생산성을 유지합니다.

에이전트는 그런 축적 없이 같은 코드베이스를 마주합니다. 세션 간에 무상태형이므로 매번 처음부터 다시 익혀야 합니다. 빠른 테스트 모음과 명확한 오류 메시지의 이점을 얻지만, 전날 알아낸 내용은 환경에 기록되지 않으면 모두 사라집니다. 에이전트는 도구 결과를 통해서만 환경을 인식합니다. AX는 그 간극을 가리킵니다. 개발자가 에이전트일 때도 유지되는 DX 요소와, 사람이 필요로 하지 않는 컨텍스트 창을 여유 있게 유지하는 일 같은 추가 요구 사항입니다.

두 경험이 겹치므로 DX에 투자하면 엄격한 타입, 빠른 테스트, 예측 가능한 구조처럼 AX도 비용 없이 개선되는 경우가 많습니다. 하지만 둘은 항상 일치하지 않습니다. 보기 좋은 온보딩 문서는 사람에게는 첫 주 동안 도움이 되지만, AGENTS.md에서 접근할 수 없다면 에이전트에게는 전혀 도움이 되지 않습니다.

사용 예:

“우리 DX는 괜찮아요. 신입이 일주일이면 생산적으로 일합니다.”

“누군가 일주일 동안 옆에 붙어 있기 때문에 생산적인 거죠. 에이전트에게 그런 일주일은 없습니다. AX는 별도로 확인하세요.”

---

에이전트 경험, 즉 코드베이스에서 에이전트가 일을 잘하도록 환경을 얼마나 잘 마련했는지를 뜻합니다. DX에 대응하는 에이전트 측 경험입니다. 같은 모델과 같은 하네스를 쓰는 에이전트가 한 저장소에서는 잘하고 다른 곳에서는 못한다면, 보통 차이는 AX입니다. 모델을 탓하거나 프롬프트를 다시 쓰고 싶겠지만, 해결책은 저장소에 있는 경우가 많습니다.

좋은 AX에는 세 가지 주요 차원이 있습니다.

AX와 DX는 겹칩니다. 좋은 검사와 깔끔한 아키텍처는 두 사용자층 모두에게 도움이 됩니다. 하지만 두 경험은 다릅니다. 사람은 암묵적인 지식, 느린 CI, “결제 모듈은 Sarah에게 물어보세요” 같은 방식도 감당할 수 있지만 에이전트는 그렇지 못합니다. 에이전트는 IDE 툴팁이나 멋진 대시보드에서 도움을 얻지 않습니다. 도구 결과에 텍스트로 나타난 실패 정보가 필요합니다. DX가 좋으면서 AX가 나쁜 코드베이스도 가능합니다.

피하기: AX를 DX의 동의어로 취급하지 마세요. 두 사용자층에는 서로 다른 투자가 필요합니다.

사용 예:

“API 저장소에서는 에이전트가 좋은 코드를 쓰는데 프런트엔드에서는 엉망이에요.”

“API 저장소에는 엄격한 타입과 빠른 테스트가 있지만 프런트엔드에는 둘 다 없고 항상 로드되는 스킬이 40개나 있습니다. 모델 문제가 아니라 AX 격차입니다.”

---

이슈 생성, 일정, CI 실패, 다른 세션의 완료 등 사람이 아닌 트리거가 에이전트 세션을 시작하는 작업 체계입니다. 이를 통해 더 많은 작업이 자리 비움 상태로 실행되고, 사람의 주의력은 남아 있는 사람 참여형 판단에 쓰입니다.

공장이 없으면 누군가 세션을 시작해야만 작업이 시작됩니다. 완전히 자리 비움으로 할 수 있는 작업도 사람이 세션을 열고 티켓을 지정하고 시작시킬 때까지 기다립니다. 팀은 그 방식만으로 가능한 것보다 더 많이 출시하고 싶어 합니다. 공장은 세션을 시작하는 과정에서 사람을 빼지만, 반드시 다른 모든 과정에서도 사람을 빼는 것은 아닙니다.

흔한 트리거와 그에 따라 시작되는 세션은 다음과 같습니다.

공장이 소프트웨어 프로세스 전체를 다룰 필요는 없습니다. 한 종류의 세션 하나를 실행해 검토 가능한 PR 하나를 여는 cron 작업도 공장입니다. 작게 시작하는 편이 유용합니다. 좁은 루프는 규모와 성격이 비슷한 PR을 만들고, 이를 검토하면서 루프를 얼마나 신뢰할 수 있는지 확인한 뒤 범위를 넓힐 수 있습니다.

공장 안의 어느 단계에든 사람이 참여할 수 있습니다. 세션을 실행하는 이슈를 작성하고 라벨을 붙일 수도 있고, 구현을 시작하기 전에 계획을 승인할 수도 있고, 병합 전에 사람이 검토할 수도 있습니다. 어떤 판단을 사람이 맡을지 정하는 일이 핵심 설계 질문입니다. 공장에서 나온 결과를 사람이 전혀 검토하지 않는 코드베이스 또는 코드의 일부는 다크 팩토리입니다.

사용 예:

“`no-floating-promises` 위반을 전부 누가 고쳤나요?”

“공장이요. cron 작업이 매일 밤 린트 규칙 하나를 골라 PR을 엽니다. 저는 아침에 검토만 합니다.”

---

소프트웨어 공장이 코드를 작성하고 사람이 그 코드를 읽지 않는 코드베이스 또는 코드의 일부입니다. 사람의 검토가 없습니다. 사람은 작업을 시작하는 이슈를 작성할 수 있지만 결과로 나온 코드는 아무도 읽지 않습니다. 이름은 작업장에 사람이 없는 상태로 제품을 만드는 ‘소등 공장’에서 유래했습니다.

다크 팩토리는 변경 하나가 아니라 코드 영역 전체를 대상으로 하는 바이브 코딩입니다. 바이브 코딩에서는 자신이 요청한 변경을 읽지 않기로 선택하지만, 변경이 존재한다는 사실은 알고 있습니다. 다크 팩토리에서는 팀이 그 선택을 코드 영역 전체에 한 번 내립니다. 그 뒤로는 누구도 변경을 개별적으로 요청하거나 확인하지 않습니다. 새 작업을 시작하는 트리거가 발생하는 속도만큼 변경이 도착합니다.

문제는 무언가 고장 났을 때 드러납니다. 변경 내용을 아무도 읽지 않았기 때문에 무엇이 바뀌었는지 알 수 없습니다. 팀에서 아무도 읽지 않은 코드를 디버깅해야 합니다. 원인은 수많은 변경 중 어디에나 있을 수 있고, 각 변경은 검사도 통과했습니다.

자동 검사와 자동 검토만이 유일한 관문입니다. 이들이 문제를 찾지 못하면 문제는 코드에 들어갑니다.

피하기: 아무도 지켜보지 않는 상태로 공장이 실행된다는 이유만으로 코드베이스를 ‘다크’라고 부르지 마세요. 에이전트 세션이 자리 비움 상태로 실행되더라도 사람이 PR을 검토한다면 그것은 소프트웨어 공장입니다. 다크 팩토리가 아닙니다.

사용 예:

“결제 서비스의 재시도 로직을 누가 바꿨죠? 팀에서 아무도 기억하지 못해요.”

“결제 서비스는 다크 팩토리입니다. 에이전트가 CI를 통과한 변경을 전부 병합합니다. 아무도 그 변경을 읽지 않았어요.”

---