하네스와 컨텍스트

하네스란 무엇인가

같은 모델을 쓰는데 클로드 코드는 파일을 고치고, 챗봇 창은 설명만 한다. 차이를 만드는 건 모델이 아니라, 모델을 감싼 ‘뼈대’다.

이 뼈대를 하네스(harness)라고 부른다. 말(馬)에 씌우는 마구에서 온 말이다.

두뇌는 혼자서는 세상에 손을 댈 수 없다. 파일을 읽는 것도, 명령을 실행하는 것도, 직전 대화를 기억하는 것도 전부 두뇌 바깥에 누군가가 깔아둔 장치가 한다. 그 장치 전체가 하네스다.

1모듈에서 본 해부도를 떠올리면 쉽다. 가운데 두뇌(모델)만 빼면 나머지가 전부 하네스다. 도구를 호출하는 배선, 결과를 다시 모델에게 먹이는 루프, 매번 모델 앞에 무엇을 깔아줄지 고르는 조립 과정 — 이 모든 비-모델 코드가 하네스다.

핵심은 이거다. 모델은 갈아끼울 수 있는 부품이고, 하네스가 제품의 성격을 결정한다. 같은 두뇌라도 어떤 하네스에 앉히느냐에 따라 챗봇이 되기도 하고 일하는 에이전트가 되기도 한다.

하네스가 매 턴 하는 일

에이전트가 한 번 ‘생각’할 때, 무대 뒤에서 하네스는 정해진 차례를 돈다.

1. 조립지금 모델 앞에 무엇을 깔지 정한다 — 시스템 프롬프트, 직전 대화, 방금 읽은 파일, 쓸 수 있는 도구 목록.
2. 호출그렇게 조립한 묶음을 모델에게 한 번 넘긴다. 모델은 답 또는 “이 도구를 써줘”라는 요청을 돌려준다.
3. 실행모델이 도구를 부르면 하네스가 실제로 실행한다 — 파일을 읽고, 명령을 돌리고, 검색을 한다.
4. 되먹임실행 결과를 다시 모델 앞에 깔고 1번으로 돌아간다. 목표에 닿을 때까지 이 루프가 반복된다.

여기서 한 가지가 분명해진다. ‘모델 앞에 무엇을 깔지’ 매 턴 고르는 것 — 그게 하네스의 가장 중요한 일이다. 그리고 그 깔아두는 자리가 다음 레슨의 주제, 컨텍스트 윈도우다.

하네스(harness)

모델을 감싼 비-모델 코드 전체. 도구 배선·실행 루프·컨텍스트 조립을 담당한다.

모델(model)

두뇌. 글을 넣으면 다음 글을 내놓는 부품. 갈아끼울 수 있다.

턴(turn)

모델을 한 번 호출하는 단위. 에이전트는 한 작업에 수십 턴을 돈다.

토큰과 컨텍스트 윈도우

모델은 기억력이 무한하지 않다. 한 번에 올려둘 수 있는 ‘책상’의 크기가 정해져 있고, 그 책상이 꽉 차면 무언가는 반드시 밀려난다.

이 책상을 컨텍스트 윈도우라고 한다. 책상 위에 올려둔 메모 한 장 한 장이 토큰이다.

토큰은 모델이 글을 다루는 최소 단위다. 단어보다 잘게 쪼갠 조각이라고 보면 된다. 한글은 대략 글자 한두 개가 토큰 하나쯤이고, 영어는 짧은 단어 하나가 토큰 하나쯤 된다. 정확한 수치는 모델마다 다르니 ‘대략 그 정도’로만 기억하면 충분하다.

중요한 건 단위가 아니라 총량에 한계가 있다는 사실이다. 시스템 프롬프트, 지금까지의 대화, 방금 읽은 파일, 도구 설명 — 이 모두가 같은 책상 위에 동시에 올라간다. 책상이 크다고 공짜는 아니다.

책상이 꽉 차면 벌어지는 일

긴 작업을 시키다 보면 에이전트가 점점 멍청해지는 느낌을 받을 때가 있다. 착각이 아니다.

대화가 길어질수록 책상 위 메모가 쌓인다. 한계에 가까워지면 하네스는 오래된 메모를 치우거나 요약해 자리를 만든다. 그 과정에서 아까 분명히 합의했던 규칙이 책상에서 사라지기도 한다.

또 하나, 책상 가운데 있는 메모는 잘 보지만 맨 위·맨 아래에 오래 깔린 메모는 흘려보는 경향이 있다. 그래서 ‘분명히 말했는데 무시했다’는 일이 생긴다. 길이를 무한정 늘리는 게 답이 아닌 이유다.

• 가득 차면 밀려난다. 한계를 넘으면 오래된 맥락이 잘리거나 요약되며, 그때 중요한 약속이 함께 사라질 수 있다.
• 길수록 흐려진다. 책상이 넓어도 구석에 깔린 지시는 주의에서 멀어진다. ‘넣어두기만’ 하면 본 척만 한다.
• 전부가 비용이다. 책상에 올린 토큰만큼 돈과 시간이 든다. 쓸데없는 걸 깔아두면 느려지고 비싸진다.

토큰(token)

모델이 글을 다루는 최소 조각. 한글은 글자 한두 개, 영어는 짧은 단어 하나쯤.

컨텍스트 윈도우

모델이 한 번에 올려둘 수 있는 토큰의 총량. 유한한 책상.

컨텍스트 관리

책상에 꼭 필요한 것만, 잘 보이는 자리에 두는 기술.

컨텍스트 5대 실패모드

에이전트가 무너지는 방식은 무작위가 아니다. 책상이 망가지는 패턴은 크게 다섯 가지로 갈리고, 패턴을 알면 처방도 갈린다.

오염 · 산만 · 혼란 · 충돌 · 부패. 하나씩 보면 “아, 그거 겪어봤다” 싶을 것이다.

이 다섯은 길게 일을 시킬수록 거의 반드시 마주친다. 중요한 건 ‘왜 이상해졌지’에서 멈추지 않고, 어떤 종류의 고장인지 이름을 붙이는 것이다. 이름이 붙으면 대응이 정해진다.

다섯 가지 고장과 처방

• 오염(Poisoning) — 틀린 게 책상에 눌러앉는다. 한 번 잘못 단정한 사실이나 환각이 맥락에 남아 이후 판단을 계속 오염시킨다. → 잘못을 발견하면 그 줄을 지우고, 안 되면 대화를 새로 끊는다.
• 산만(Distraction) — 책상이 너무 넓어 길을 잃는다. 맥락이 비대해지면 지금 목표보다 과거 기록을 답습하며 겉돈다. → 작업을 작게 쪼개고, 끝난 단계는 책상에서 치운다.
• 혼란(Confusion) — 쓸데없는 게 끼어든다. 지금 작업과 무관한 도구·정보가 책상에 올라가 엉뚱한 선택을 부른다. → 이 작업에 필요한 도구·자료만 남긴다.
• 충돌(Clash) — 책상 위 메모끼리 싸운다. 앞에서 “A로 하자”, 뒤에서 “아니 B로” 하면 모델은 모순 속에서 헤맨다. → 결정이 바뀌면 옛 지시를 명시적으로 무효화하고 최신본만 남긴다.
• 부패(Poisoning과 다름, Degradation) — 요약하다 원본이 닳는다. 책상을 비우려 거듭 요약·압축하는 사이 디테일이 미세하게 어긋나 누적된다. → 중요한 원본은 요약본에 의존하지 말고 파일로 보존한다.

지금까지의 대화에서 네가 사실로 전제하고 있는 것들을 목록으로 정리해줘.
- 내가 명시적으로 말한 것
- 네가 추측으로 채운 것
이 둘을 구분해서 표시하고,
추측 중에 확신이 약한 항목은 따로 표시해줘.

서브에이전트·물리적 브레이크

책상이 더러워지는 걸 막는 가장 확실한 방법은, 더러워질 일을 애초에 다른 책상에서 시키는 것이다.

이게 서브에이전트의 핵심이고, ‘물리적 분리’라는 한마디로 요약된다.

큰 작업을 한 책상에서 끝까지 끌고 가면, 앞 레슨의 다섯 고장이 차곡차곡 쌓인다. 대신 무거운 곁가지 — 방대한 자료 뒤지기, 긴 로그 분석 같은 일 — 를 별도의 깨끗한 책상(서브에이전트)에 맡기면, 그 책상이 아무리 어질러져도 본 책상은 멀쩡하다.

서브에이전트는 자기 책상에서 실컷 일하고, 결론만 본 책상으로 가져온다. 수십 개 파일을 뒤진 과정은 자기 책상에 두고 오고, “핵심은 이 세 줄”만 돌려주는 식이다. 본 책상은 깨끗하게 유지된다.

물리적 브레이크 — 사람이 거는 제동

분리만으로 다 되는 건 아니다. 사람이 흐름을 끊어주는 ‘브레이크’도 필요하다.

에이전트는 한번 달리기 시작하면 멈출 줄을 모른다. 그래서 잘못된 전제를 안고 30턴을 더 달리기 전에, 사람이 물리적으로 끊는 지점을 미리 정해 둔다. 이게 물리적 브레이크다.

• 새 대화로 끊기. 작업이 한 단락 끝나면 책상을 통째로 갈아 새 대화로 넘어간다. 가장 단순하고 가장 강력한 브레이크.
• 중간 점검 게이트. “여기까지 한 걸 요약하고 멈춰. 내 확인 받고 계속.” 폭주를 막는 약속된 정거장.
• 결론을 파일로. 한 단계의 결과를 파일에 적어두면, 다음 대화는 그 파일만 읽고 시작한다. 맥락을 책상이 아니라 디스크에 보관하는 셈.

이 작업은 자료를 많이 뒤져야 하니까, 별도 작업으로 분리해서 처리해줘.
- 조사·탐색은 따로 진행하고, 나한테는 결론만 짧게 가져와줘
- 가져올 때: ① 핵심 결론 3줄 ② 근거가 된 파일·출처 목록 ③ 남은 불확실한 점
- 중간 과정의 긴 로그나 전문(全文)은 가져오지 말고 요점만