AI 에이전트(AI Agent)를 설명할 때는 프롬프트(Prompt), 컨텍스트(Context), 하네스(Harness), 루프(Loop)라는 용어가 나열됩니다.

컨텍스트나 도구의 결과는 다음 모델 호출의 입력이 됩니다. 그렇기 때문에 "결국 모두 프롬프트가 아닌가"라는 의문이 생깁니다.

일반적인 설명에서는 프롬프트는 모델에 대한 지시, 컨텍스트는 모델에 전달하는 정보 전체를 가리킵니다. 이 기사에서는 설계상의 책임을 구분하기 위해, 프롬프트를 지시, 컨텍스트를 판단 재료의 선택·취득·정형, 루프를 반복 제어, 하네스를 이들을 움직이는 런타임(Runtime) 기반으로 정리합니다.

대상은 생성형 AI(Generative AI)나 코딩 에이전트(Coding Agent)를 실무에서 사용하기 시작한 엔지니어, 아키텍트, 테크 리드(Tech Lead)입니다. 모델의 내부 구조나 학습 알고리즘은 다루지 않습니다.

결론

AI 에이전트가 기대대로 작동하지 않을 때는 처음부터 프롬프트를 다시 쓰는 것이 아니라, 지시, 판단 재료, 실행 환경, 상태 업데이트·종료 조건 중 어디에 문제가 있는지 나누어 확인하는 방침입니다. 4가지 개념은 동일한 계층은 아니지만, 설계상의 책임을 다음과 같이 정리하고 있습니다.

4가지를 책무로 나누기

프롬프트·컨텍스트·하네스·루프의 관계를 다음과 같은 그림처럼 파악하고 있습니다.

여기서부터는 책무를 설명하기 위한 가상적인 코딩 에이전트 예시로서, "실패한 테스트를 수정하고, 대상 요구사항을 충족하는 근거를 확인하면 완료"라고 의뢰하는 상황을 가정하여 생각합니다.

프롬프트: 모델에게 무엇을 판단하게 할 것인가

프롬프트에는 모델에게 맡기고 싶은 판단을 작성하는 방침으로 합니다. 예를 들어 다음과 같은 지시입니다.

• 테스트 실패 원인을 특정하고 나서 수정할 것
• 원인을 모른다면 관련 사양(Specification)이나 코드를 추가로 조사할 것
• 대상 요구사항을 충족하는 근거가 모일 때까지 완료라고 보고하지 말 것
• 변경의 영향 범위를 설명할 것

여기서는 실패 원인의 가설이나 수정안의 선택을 모델에게 맡깁니다. 프롬프트에 "이 파일에는 접근하지 마세요"라고 쓸 수는 있지만, 그것만으로 접근을 거부할 수 있는 것은 아닙니다. 확실히 지키고 싶은 제약은 권한 설정이나 검증 처리에도 두는 방침으로 합니다.

컨텍스트: 판단 재료를 선택하고, 찾고, 정돈하기

모델에게 전달하는 정보량을 늘리기보다, 대상을 선택하고 순서와 형식을 정돈하는 것을 우선시합니다. 오래된 이력이나 중복은 판단을 방해하지 않는 범위까지 압축합니다.

코드 수정의 예라면 다음과 같은 정보가 후보가 됩니다.

• 실패한 테스트의 이름과 출력
• 테스트 대상 코드
• 해당 코드가 따르는 사양이나 규칙
• 관련 테스트
• 직전의 변경 내용
• 변경해서는 안 되는 범위

필요한 정보를 어떻게 찾을지는 프롬프트, 컨텍스트, 루프, 하네스에 걸친 책임으로 생각합니다. 탐색 방침은 프롬프트, 취득한 정보의 선택과 정형은 컨텍스트, 추가 탐색으로 돌아가는 제어는 루프, 검색 수단이나 권한의 제한은 하네스에 둡니다.

모델에게 검색 도구(Search Tool)를 전달하여 읽을 정보를 판단하게 하는 구성도 선택할 수 있습니다. 다만, 매번 같은 장소에서 테스트 결과나 사양을 가져온다면, 취득 처리를 하네스에 포함하여 미리 모읍니다. 검색의 필요 여부는 모델이나 루프가 판단하게 하고, 취득할 수 있는 범위나 권한은 하네스의 설정으로 고정하는 방침입니다.

찾기 쉬운 형식이나 배치도 이 기사에서는 컨텍스트 엔지니어링(Context Engineering)에 포함합니다. 예를 들어 다음과 같이 정돈합니다.

[Source] tests/order_test.py
[Observation] test_total_returns_400_when_items_are_empty 가 실패
[Expected] 빈 내역에서는 400을 반환
...

출처, 관측 결과, 기대값, 실제 값은 나누어서 전달하도록 하고 있습니다. 로그의 일부를 사양으로 취급할 가능성을 줄이고 싶기 때문입니다. 파일의 배치, 헤더, 라벨, 요약, 이력의 압축도 동일한 책임에 포함됩니다.

하네스: 모델과 개발 환경을 매개하는 런타임 기반

2026년 5월에 제출된 프리프린트(preprint)는 하네스(Harness)를 모델과 개발 환경 사이에서 컨텍스트(Context), 도구(Tool), 상태(State), 관측(Observation), 검증(Verification), 권한(Permission) 등을 매개하는 런타임 기반(Runtime Substrate)으로 정의하고 있습니다. 하네스는 모델의 외부에 있으며, 모델 그 자체도 아니고 리포지토리(Repository)나 테스트 실행 환경 그 자체도 아닙니다. AI Harness Engineering: A Runtime Substrate for Foundation-Model Software Agents

이 글에서도 이 위치 설정에 맞추어 설명합니다. 의미를 판단하고 도구 호출(Tool Call)을 선택하는 것은 모델입니다. 파일 편집이나 테스트 실행의 부작용(Side effect)을 일으키는 것은 개발 환경에서 동작하는 도구입니다. 프롬프트(Prompt) 자체를 하네스와 동일시하지 않고, 하네스에는 프롬프트를 구성하고 컨텍스트를 선택하는 메커니즘을 둡니다. 모델과 개발 환경 사이에는 도구 접근, 권한, 상태, 관측, 검증을 연결하는 메커니즘을 둡니다.

앞서 설명한 코드 수정 예시에서는 하네스에 다음과 같은 메커니즘을 두는 방침을 취하고 있습니다.

• 프롬프트를 구성하고, 컨텍스트를 선택·정형화하여 모델 호출로 전달
• 이용 가능한 도구, 명령어, 읽기/쓰기가 가능한 범위를 정의
• 도구의 실행 결과, 로그, 검증 결과를 상태(State)로 기록
• 출력 스키마(Output Schema)나 금지 작업을 검증
• 요구사항과 검증 결과를 대응시켜 루프(Loop)의 종료 조건으로 전달

프롬프트를 통한 요청과 하네스에 둔 메커니즘에 의한 강제를 비교하면 차이를 알 수 있습니다.

모델이 의도를 이해하게 하고 싶은 내용은 프롬프트에 작성합니다. 반면 권한, 스키마, 검증 결과, 시도 횟수 상한과 같이 외부에서 판정할 수 있는 것은 하네스에 둔 도구 접근, 검증, 루프 메커니즘을 통해 확인하는 방침입니다. 이 부분은 모델의 자기 보고(Self-declaration)에 의존하지 않습니다.

루프: 결과를 다음 판단으로 되돌림

루프에는 하네스 내에서 단 한 번의 모델 호출로 끝나지 않는 작업의 진행을 제어하는 책임을 부여합니다. 모델 출력과 개발 환경으로부터의 실행 결과를 상태에 반영하여, 다음 프롬프트나 컨텍스트를 구성할지, 도구를 호출할지, 혹은 종료할지를 결정합니다. 코드 수정에서는 다음과 같은 흐름으로 진행하는 방침입니다.

• 모델이 수정안을 선택하고, 파일 편집이나 테스트 실행을 도구 호출로서 요구함
• 하네스에 정의된 도구 접근 및 권한 설정으로 호출 가능한 조작을 제한함
• 개발 환경의 도구가 파일을 편집하고 테스트를 실행함
• 실행 결과와 검증 결과가 하네스의 상태에 기록되어 다음 컨텍스트로 정형화됨
• 루프가 다음 판단으로 되돌리거나, 대상 요구사항의 근거, 시도 횟수 상한, 인간으로의 인계에 따라 종료함

IBM의 해설에서는 에이전트의 루프를 Goal, Action, Observation, Adjustment의 반복으로 설명합니다. 결과를 관찰하여 다음 행동을 바꾸는 점은 이 글의 루프와도 공통됩니다. 반면, IBM은 컨텍스트 엔지니어링(Context Engineering)이나 도구 접근도 루프를 구성하는 요소로 꼽고 있습니다. 이 글에서는 문제를 분리하기 위해 그것들을 컨텍스트와 하네스의 책임으로 나누었습니다. What Is Loop Engineering?

루프에는 프롬프트로 촉구하는 모델 내부의 반복과, 코드로 구현하는 외부 루프가 있습니다. 이 글에서는 다음과 같이 나누어 생각합니다.

내부의 반복은 프롬프트로 촉구할 수 있더라도, 실행 횟수나 검증 결과를 외부에서 확실하게 관리하는 것은 아닙니다. 시도 횟수 상한이나 분기를 코드로 관리하는 경우에는 외부 루프로 구현합니다. LangGraph의 공식 문서에서는 LangGraph를 오케스트레이션 런타임(Orchestration Runtime), Deep Agents를 하네스로 구분하고 있습니다. 따라서 LangGraph는 이 글에서 말하는 외부 루프의 구현 사례이며, 하네스와 동의어는 아닙니다. LangGraph 공식 문서

루프 안에서도 모델에게 맡기는 부분과 코드로 고정하는 부분을 나누고 있습니다.

기본 형태로 생각하고 있는 것은, 고정된 워크플로우 (Workflow)의 일부 노드만을 에이전트 (Agent)로서 동작시키는 구성입니다. 진행 경로, 권한, 검증, 상한선은 코드로 고정하고, 모호한 의미 이해나 수정안의 선택을 모델 (Model)에 맡깁니다.

여러 책무에 걸친 처리

검색 결과와 관련된 처리도 다음과 같이 나누고 있습니다.

"도구 (Tool)나 외부 처리의 결과는 프롬프트인가"라는 질문에는 한마디로 답할 수 없습니다. 결과 그 자체는 다음 모델 호출에 대한 입력이 될 수 있지만, 결과를 생성하는 것은 도구, 필요한 정보를 선택하고 정리하는 것은 컨텍스트, 다시 취득할지 판단하는 것은 루프 (Loop)입니다.

기대대로 동작하지 않을 때의 구분

기대대로 동작하지 않을 때는, 증상과 가장 먼저 확인해야 할 책임을 대응시키고 있습니다.

예를 들어, 테스트 결과를 모델에게 전달하지 않고 있다면 컨텍스트 (Context)의 문제입니다. 결과를 전달하고 있음에도 동일한 수정을 반복한다면 루프 (Loop)의 문제입니다. 대상 요구사항을 충족할 근거가 갖춰지지 않았는데 완료된다면, 루프가 검증 결과를 완료 조건으로 올바르게 연결하고 있는지 확인합니다.

FAQ

컨텍스트 (Context)는 프롬프트로 지정하는 참조 정보인가요?

아니요. 일반적으로 컨텍스트는 프롬프트로 지정하는 참조 정보에 국한되지 않습니다. 메시지 이력, 도구 정의, 도구 실행 결과, 외부 데이터, 출력 형식 등, 프롬프트로 직접 지시하지 않더라도 모델에 대한 입력이 되는 정보를 포함합니다. LangChain의 해설에서도 모델 컨텍스트에 지시, 이력, 도구, 응답 형식을 포함하고 있습니다. Context engineering in agents.

이 글의 코드 수정 예시에서는 탐색 방침을 프롬프트에 쓰고, 도구 실행 결과로부터 다음 판단으로 넘길 정보를 컨텍스트로 정리하고 있습니다. 취득 수단과 권한은 하네스 (Harness)에 두고, 추가 탐색으로 돌아가는 처리는 루프에 둡니다.

필요한 정보를 찾는 지시는 프롬프트인가요?

일반적으로 모델에게 탐색 순서나 판단 기준을 전달하는 지시는 프롬프트입니다. 검색 도구를 실행하는 처리나, 읽을 수 있는 경로를 제한하는 처리는 하네스에 포함합니다. 부족한 정보를 발견하여 다시 검색으로 진행하는 제어는 루프에 둡니다. 이 글의 코드 수정 예시에서는 "먼저 실패한 테스트를 확인한다"는 프롬프트에 쓰고, 테스트 결과로부터 대상 파일을 추출하는 처리는 하네스에 두며, 다음 판단에 남길 정보는 컨텍스트로 정리하고 있습니다.

하네스 (Harness) 설정도 프롬프트에 써야 하나요?

아니요. 하네스 설정을 모두 프롬프트에 쓸 필요는 없다고 생각합니다. 모델이 이해하고 판단하게 하고 싶은 규칙이나 도구 사용법은 프롬프트나 도구 정의에 작성합니다. 반면, 타임아웃, 권한, 재시도 횟수, 스키마 검증, 종료 조건 등 외부에서 판정할 수 있는 구현 상세는 코드로 고정합니다.

루프 (Loop)는 하네스의 일부인가요?

이 글에서는 그렇습니다. 하네스는 모델과 개발 환경을 매개하는 런타임 (Runtime) 기반이며, 루프는 그 안에서 상태, 다음 모델 호출, 종료를 제어하는 메커니즘으로 취급합니다. 모델은 하네스의 외부에 있으며, 프롬프트는 1회의 모델 호출에 전달하는 지시입니다. 구현에서는 하네스에 둔 입력 처리가 프롬프트를 구성하고, 컨텍스트를 선택하여 모델에 전달합니다. 구현에 따라서는 오케스트레이션 (Orchestration)을 별도의 런타임으로 조합하기도 합니다.

프롬프트 엔지니어링 (Prompt Engineering)은 불필요해지나요?

불필요해지지는 않을 것이라고 생각합니다. 루프나 하네스를 도입하더라도 모델에게 무엇을 판단하게 할지는 설계해야 합니다. 다만 실행, 권한, 검증, 정지까지를 단일 프롬프트만으로 담당하게 하지 않고, 하네스에 포함된 메커니즘으로 분담하는 방침을 취하고 있습니다.

요약

제가 설계 시 사용하고 있는 정리 방식은 다음과 같습니다.

기대대로 동작하지 않을 때는 지시사항이라면 프롬프트, 판단 재료라면 컨텍스트, 도구·권한·검증이라면 하네스, 지속·종료 조건이라면 루프를 확인합니다.

의미 해석이나 수정안의 선택은 모델에 맡기고, 권한, 검증, 시도 상한, 종료 조건은 하네스에 둔 메커니즘으로 고정하는 방침입니다. 저는 AI 에이전트의 설계와 원인 조사에 이 구분을 사용하고 있습니다.

관련 기사

AI를 팀에 도입할 때 대상, 검증, 책임을 먼저 결정해야 한다는 관점은, 생성형 AI 도입 시 먼저 결정해야 할 7가지 항목: 작업 시간만으로 효과를 측정하지 말 것(7 items to decide before introducing generative AI: Don't measure effectiveness with working time alone)에서 다루고 있습니다.

참고 자료

• What Is Loop Engineering? (IBM Think)
• AI Harness Engineering: A Runtime Substrate for Foundation-Model Software Agents (arXiv)
• Effective context engineering for AI agents (Anthropic)
• Context engineering in agents (LangChain 공식 문서)
• LangGraph overview (LangChain 공식 문서)

Discussion