에이전트 하네스와 루프, 그래프 3층 구조 실무 정리와 증상별 진단 체크리스트 2026년판

에이전트 하네스와 루프, 그래프 3층 구조 실무 정리와 증상별 진단 체크리스트 2026년판

에이전트 하네스: 모델을 뺀 나머지 전부입니다. 시스템 프롬프트, 툴 정의, 메모리, 파일시스템, 샌드박스, 권한, 로깅, 검증 인터페이스가 여기 들어갑니다. LangChain 정의로는 "Agent = Model + Harness"입니다.

목차

1. 에이전트 하네스란 정확히 무엇인가
2. Anthropic이 시스템 프롬프트 80%를 걷어낸 이유
3. 루프 엔지니어링은 확신이 아니라 증거로 돕니다
4. 그래프 엔지니어링은 격식이 값을 할 때만
5. 하네스는 모델과 분리되지 않습니다
6. 증상으로 층을 역산하는 진단표

에이전트를 제대로 만들려면 하네스를 잘 쌓아야 한다고들 합니다. 그런데 2026년 7월 넷째 주에 정반대로 보이는 신호가 사흘 사이에 세 개 겹쳤습니다. 결론부터 말하면 모순이 아니라 성숙 곡선이고, 지금 챙길 방향은 더 쌓기가 아니라 정확히 남기기입니다.

에이전트 하네스란 정확히 무엇인가

LangChain이 2026-03-11에 정리한 정의가 가장 깔끔합니다.

"Agent = Model + Harness. If you're not the model, you're the harness. A harness is every piece of code, configuration, and execution logic that isn't the model itself."

모델이 아니면 전부 하네스라는 뜻입니다. 지능은 모델에 있고, 그 지능을 쓸모 있게 만드는 게 하네스입니다.

아키텍처 그림에서 모델을 지워 보면 남는 게 전부 하네스입니다. 툴, 상태 저장소, 샌드박스, 평가자, 재시도 정책까지요. 같은 모델을 쓰는 두 팀의 결과가 갈리는 이유도 여기 있습니다. 지능 차이가 아니라 작업 환경 차이입니다.

Anthropic이 시스템 프롬프트 80%를 걷어낸 이유

Anthropic은 2026-07-24 공식 블로그에서 이렇게 밝혔습니다.

"We removed over 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations."

측정 가능한 손실 없이 80% 이상을 지웠다는 겁니다. 이유는 과하게 제약하고 있었다는 것이고, 사례가 구체적입니다. 내부 사용 기록에서 한 요청 안의 지시가 서로 부딪히고 있었습니다.

"we see several conflicting messages in a single request like 'leave documentation as appropriate,' or 'DO NOT add comments'"

"문서는 적절히 남겨라"와 "주석은 쓰지 마라"가 같이 들어간 겁니다. 모델은 답을 내기 전에 이 충돌부터 정리해야 했고, 그만큼 생각을 낭비했습니다.

바뀐 규칙 여섯 가지

첫 줄의 변화가 상징적입니다. 예전에는 "주석을 쓰지 마라, 여러 줄 문서화를 하지 마라"였고, 지금은 이렇게 바뀌었습니다.

"Write code that reads like the surrounding code: match its comment density, naming, and idiom."

금지 목록 대신 판단 기준을 준 겁니다.

하네스를 버리라는 뜻은 아닙니다

같은 글이 "하네스를 직접 만든다면 여기에 시간을 많이 써야 한다"고도 말합니다. 걷어낼 대상은 중복과 충돌이지 하네스 자체가 아닙니다. 처방은 세 가지입니다. 규칙 문서는 가볍게 두고 토큰을 코드베이스의 함정에 쓸 것, 파일 구조만 봐도 아는 내용은 적지 말 것, 검증 규칙이 여러 개면 별도 스킬로 뺄 것.

툴도 같습니다. 정의를 미리 싣지 않고 검색으로 찾게 만들어, 쓰기 전까지 컨텍스트를 차지하지 않게 했습니다.

루프 엔지니어링은 확신이 아니라 증거로 돕니다

툴을 쓰는 에이전트에는 이미 작은 루프가 있습니다. 모델을 부르고, 결과를 보고, 툴을 실행하고, 답이 나올 때까지 반복하죠. 그 위에 사이클을 의도적으로 더 쌓으면 루프 엔지니어링이 됩니다. LangChain은 2026-06-16 글에서 이를 하나의 반복문이 아니라 루프 스택으로 봐야 한다고 정리했습니다.

잘 설계된 루프에는 일곱 가지가 있습니다. 트리거, 목표, 상태와 메모리, 행동 정책, 증거, 피드백, 정지 규칙입니다.

제일 자주 깨지는 건 마지막입니다. 에이전트가 "다 됐다"고 말하는 건 정지 조건이 아닙니다. 테스트가 통과하고 스키마가 검증되고 리뷰어가 승인해야 정지 조건입니다. 확신이 아니라 증거로 돌려야 한다는 뜻이죠.

해커뉴스 토론에서도 같은 지적이 나왔습니다.

"Prompts are simply not enough to steer a coding agent to the level of precision needed. Without deep programmatic verification... the solutions the agent produces will always be just slightly (or very) out of true."

다만 검증은 공짜가 아닙니다. 채점자와 재시도마다 호출이 하나씩 붙습니다. 기준은 단순합니다. 검증 비용이 실패 비용보다 쌀 때만 루프를 더합니다.

그래프 엔지니어링은 격식이 값을 할 때만

그래프는 다른 질문을 던집니다. 에이전트가 무엇을 하는가가 아니라 다음에 무엇이 실행돼도 되는가입니다. 노드가 단계고 엣지가 허용된 이동이며, 순서와 분기와 병렬과 사람 개입 지점을 명시합니다.

설계할 때 정하는 건 노드 경계, 상태 스키마, 라우팅 조건, 동시성, 사이클과 출구, 체크포인트입니다.

값을 하는 조건은 분명합니다. 의미 있는 분기, 병렬 작업, 승인 게이트, 복구 경로, 여러 전문 에이전트가 있을 때입니다. "에이전트 하나에 툴 셋 개 주고 일 시키기"가 전부라면 격식만 늘어납니다.

함정도 있습니다. 그래프는 디버깅을 쉽게 만들지만 가정을 너무 일찍 굳혀 버릴 수도 있습니다. 모델이 계획을 스스로 짜야 하는 일에 경로를 미리 다 밀어 넣으면 오히려 잘 부서집니다.

용어도 구분해 둘 필요가 있습니다. 여기서 말하는 그래프는 워크플로 실행 그래프이지 지식 그래프가 아닙니다. 지식 그래프는 데이터 속 개체와 관계를, 워크플로 그래프는 제어와 상태 전이를 표현합니다.

하네스는 모델과 분리되지 않습니다

HumanLayer 창업자가 2026-07-23에 올린 글은 경쟁 제품을 만든다는 이해관계를 첫머리에 밝히고 시작합니다. 그 점을 감안해도 볼 만한 대목이 있습니다.

"claude code won because it was better, and that it was better because Anthropic RL'd the model inside the harness"

먼저 나온 다른 명령줄 에이전트들도 툴 구성은 비슷했는데 결과가 갈린 이유를, 하네스 안에서 모델을 학습시킨 데서 찾은 겁니다. 근거로 든 2024년 논문의 관찰도 흥미롭습니다. 파일 읽기 결과에 줄 번호를 넣는지 같은 툴 모양의 작은 차이가 행동을 바꾼다는 것이죠.

여기서 교훈이 나옵니다. 남의 하네스 구성표를 그대로 베끼는 게 최선이 아닙니다. 하네스는 그 모델, 그 작업과 함께 조정될 때 값을 합니다.

이 글이 사례로 든 "사람이 코드를 읽지도 쓰지도 않는 공장"에 대해서는 논쟁이 끝나지 않았습니다. 해커뉴스에 해당 팀 구성원이 직접 나와 여전히 낙관한다고 밝혔고, 글쓴이도 실패로 단정한 건 아니라며 물러섰습니다.

증상으로 층을 역산하는 진단표

어디부터 손댈지는 증상에서 역산하는 게 가장 빠릅니다.

마지막 칸은 2026-07-24에 새로 생긴 셈입니다. 부족해서 생기는 문제를 다루던 자리에, 많아서 생기는 문제가 별도 항목으로 들어왔습니다.

세 층은 서로를 대체하지 않습니다. 그래프를 아름답게 그려도 하네스가 상태를 잃으면 소용없고, 하네스가 훌륭해도 정지 규칙 없는 루프는 돈만 씁니다.

자주 묻는 질문

Q. 에이전트 하네스와 프롬프트 엔지니어링은 어떻게 다른가요?

프롬프트는 한 번의 호출에서 무엇을 할지 지시하고, 하네스는 그 호출 바깥의 전부입니다. 툴을 어떻게 주는지, 상태를 어디 저장하는지, 권한을 어디까지 여는지가 하네스 몫이죠. 프롬프트를 다듬어도 상태가 유실되거나 툴 정의가 모호하면 결과는 흔들립니다.

Q. 우리 팀도 그래프 프레임워크를 도입해야 할까요?

분기와 병렬, 승인 게이트, 복구 경로가 실제로 있는지부터 보세요. 없다면 미루는 쪽이 안전합니다. 단순한 하네스로 돌려 보고 반복되는 경로가 드러날 때 형식화해도 늦지 않습니다.

Q. 규칙 문서를 줄이면 품질이 떨어지지 않나요?

Anthropic은 코딩 평가에서 측정 가능한 손실이 없었다고 밝혔습니다. 다만 무작정 지우라는 뜻은 아닙니다. 충돌하는 지시와 중복부터 없애고, 남길 것은 판단 기준 형태로 바꾸는 순서입니다.

마무리

작은 팀이 오늘 할 수 있는 점검은 세 가지입니다.

하나, 지시 충돌부터 찾습니다. 규칙 문서를 열어 서로 부딪히는 문장을 찾아보세요. "적절히 판단하라"와 "절대 하지 마라"가 같이 있다면 그게 낭비 지점입니다.

둘, 정지 조건을 문장으로 씁니다. "잘 됐으면 멈춤"이 아니라 "이 명령이 0을 반환하면 멈춤"처럼 기계가 판정할 수 있어야 합니다.

셋, 그래프는 미룹니다. 단순한 하네스로 먼저 돌려 보고 반복되는 경로가 드러날 때 형식화하세요.

세 층 중 지금 에이전트 하네스가 아픈지, 루프가 아픈지부터 짚어 보시길 권합니다.

관련 글

• QJC 블로그 전체 글 보기

참고자료

• The new rules of context engineering for Claude 5 generation models (Anthropic, 2026-07-24)
• The Anatomy of an Agent Harness (LangChain, 2026-03-11)
• The Art of Loop Engineering (LangChain, 2026-06-16)
• Why Software Factories Fail (or: harness engineering is not enough) (HumanLayer, 2026-07-23)
• 해커뉴스 토론 (2026-07-23)