프롬프트는 코딩 에이전트의 가장 작은 부분이다

코딩 에이전트는 프롬프트에서 출발하지만, 성패는 그 프롬프트를 둘러싼 런타임에서 갈립니다. 더 작고 기계적으로 보면 이렇게 이해할 수 있습니다: 프롬프트, 루프, 하네스.

프롬프트가 가장 작은 부분인 이유

Claude 스타일의 코딩 에이전트는 3계층 시스템으로 보는 편이 더 정확합니다. 하네스가 환경을 책임지고, 실행 루프가 모델과 도구의 상호작용을 중재하며, 프롬프트는 압축된 지시를 제공합니다. Anthropic의 도구 사용 계약에 따르면 Claude는 구조화된 tool_use 요청을 내보내고, 애플리케이션이 도구를 실행한 뒤 tool_result 블록을 반환합니다 . 즉 프롬프트는 신중한 동작을 요청할 수 있지만, 권한, 샌드박싱, 컨텍스트 조립, 훅, 로깅, 중단 조건을 강제할 수 있는 것은 하네스입니다.

요약 답변: 프롬프트가 가장 작은 부분인 이유는 코딩 에이전트의 신뢰성이 하네스와 루프에서 나오기 때문입니다. 타입이 지정된 도구 호출, 반환된 관찰 결과, 권한, 샌드박스, 훅, 수명주기 제어가 핵심입니다. Anthropic의 2026년 릴리스는 100만 토큰 컨텍스트 창과 12만 8천 토큰 출력 상한을 프롬프트 텍스트가 아니라 런타임 표면으로 강조했습니다 .

이 경계가 중요한 이유는 프롬프트는 권고에 가깝지만 도구 정책은 실행 가능하기 때문입니다. 프롬프트는 “편집 전에 먼저 검사하라”고 말할 수 있지만, 하네스는 쓰기를 제한하고, 셸 명령에 승인을 요구하고, 프로젝트 메모리를 로드하고, MCP 서버를 노출하고, 도구 사용 전후에 훅을 트리거하며, 검증기가 통과하거나 턴 예산이 소진되면 에이전트를 멈출 수 있습니다. 시드 영상은 이 조사를 위한 프롬프트로는 유용하지만, 오래 남는 근거는 공개된 에이전트 및 도구 사용 문서에 있습니다 .

"The client application executes the tool," — Anthropic 도구 사용 문서 (source: Anthropic)

최근 플랫폼 변화도 같은 방향을 가리킵니다. Anthropic의 2026년 6월 30일 Sonnet 5 릴리스에는 100만 토큰 컨텍스트 창, 최대 12만 8천 출력 토큰, 기본 활성화된 adaptive thinking, 2026년 8월 31일까지 적용되는 입력 100만 토큰당 2달러 및 출력 100만 토큰당 10달러의 도입 가격이 명시되었습니다 . 2026년 7월 24일 Opus 5 릴리스에는 100만 토큰 컨텍스트 창, 최대 12만 8천 출력 토큰, 기본 활성화된 thinking, 입력/출력 100만 토큰당 5달러/25달러 가격이 명시되었습니다 . 이것들은 모두 하네스와 수명주기 제어입니다. 컨텍스트, 출력 상한, 샌드박스, 이벤트, 관리형 세션이 여기에 해당합니다.

class CodingAgent:
    def __init__(self, prompt):
        self.prompt = prompt
        self.tools = ["read", "edit", "run tests"]
        self.loop = ["observe", "plan", "act", "verify"]

    def solve(self, task):
        return (
            f"Task: {task}\n"
            f"Prompt: {self.prompt!r}\n"
            f"Agent: tools={self.tools}, loop={self.loop}\n"
            "Point: the prompt starts the work; tools, feedback, and verification do most of it."
        )


print(CodingAgent("fix the bug").solve("make the program correct"))

루프가 시작되기 전에 하네스가 책임져야 할 것

하네스는 모델이 추측해서는 안 되는 모든 것을 책임져야 합니다. 작업공간 파일, 현재 git 상태, 사용자 요청, 모델 지시, 도구 스키마, 권한 모드, 프로젝트 메모리, 외부 연결이 여기에 포함됩니다. 실제로 Claude Code, OpenAI Codex, SWE-agent, mini-SWE-agent는 모두 환경 준비를 모델 응답 밖에 두고, 모델이 그 준비된 틀 안에서 작동하게 합니다.

코딩 에이전트의 실행 전제 조건은 구체적입니다. 첫 번째 모델 호출 전에 하네스는 어떤 저장소가 활성 상태인지, 작업 트리가 더러운지, 어떤 파일이나 로그가 관련 있는지, 어떤 지시가 적용되는지, 어떤 도구가 허용되는지, 편집, 셸 명령, 네트워크 호출, MCP 서버에 승인이 필요한지를 알고 있어야 합니다. Claude Code는 터미널 접근, 프로젝트 컨텍스트, CLAUDE.md 메모리, MCP, 훅, 권한, 스킬, 서브에이전트를 통해 이 분리를 문서화합니다 .

2026년에 커진 규모 압력은 이 분리를 덜 중요하게 만드는 것이 아니라 더 중요하게 만듭니다. Anthropic 릴리스 노트에는 2026년 6월 30일 Claude Sonnet 5가 100만 토큰 컨텍스트 창과 12만 8천 최대 출력 토큰으로 올라왔고, 2026년 7월 24일 Claude Opus 5도 같은 컨텍스트 및 출력 제한을 갖춘 것으로 나와 있습니다 . 더 큰 컨텍스트가 자동으로 더 나은 컨텍스트를 뜻하지는 않습니다. 잡음이 많은 파일, 오래된 로그, 관련 없는 기록은 여전히 잘못된 편집으로 이끌 수 있습니다. 하네스는 실행 루프가 시작되기 전에 컨텍스트를 선택하고, 라벨링하고, 압축하고, 감사해야 합니다.

실행 루프는 어떻게 돌아가나?

실행 루프는 에이전트의 상태 머신이다. 모델에 메시지와 도구 스키마를 보내고, 모델 밖에서 요청된 도구를 실행한 뒤, 관찰 결과를 돌려주고, 모델이 더 이상 도구를 요청하지 않을 때까지 이를 반복한다. Anthropic의 도구 사용 계약에서는 tool_use가 루프를 계속 이어가고, end_turn, max_tokens, stop_sequence, 또는 refusal이 턴을 끝내거나 중단한다고 Anthropic 도구 사용 문서는 설명한다.

1. 작업 상태를 보낸다. 하네스는 사용자 요청, 압축된 대화 기록, 관련 프로젝트 컨텍스트, 타입이 지정된 도구 스키마를 보낸다. 모델이 봐야 하는 것은 요청할 수 있는 대상이지, 셸이나 파일시스템에 대한 직접 접근 권한이 아니다.
2. 모델 응답을 읽는다. 응답에 tool_use 블록이 있으면 이를 구조화된 요청으로 다룬다. 모델이 이미 무언가를 실행했다고 가정하지 않는다.
3. 요청된 호출을 각각 디스패치한다. 애플리케이션은 하네스의 권한과 샌드박스 규칙 아래에서 요청된 파일 읽기, 편집, 셸 명령, 테스트 명령, MCP 호출, 또는 다른 도구를 실행한다.
4. 실제 관찰 결과를 붙인다. 하네스는 stdout, stderr, 파일 내용, 테스트 실패, 권한 거부, 또는 그 밖의 구체적 결과가 담긴 tool_result 블록을 돌려준다.
5. 모델을 다시 호출한다. 모델은 새 관찰 결과를 바탕으로 추론하고, 또 다른 도구 호출을 요청하거나 최종 응답을 만든다.
6. 도구가 아닌 중단 사유에서만 멈춘다. 최종 답변은 단지 명령 하나가 실행됐기 때문이 아니라, 도구가 아닌 중단 조건이 나온 뒤에 내보내야 한다.

"The client-side application is responsible for executing the tool," — Anthropic, tool-use documentation at Anthropic

이는 ReAct의 실무 버전이다. 추론, 행동, 관찰을 번갈아 끼워 넣어 모델이 추측이 아니라 도구 출력에 근거해 이후 결정을 내리게 한다. 이 패턴은 근거 없는 답변을 줄여 주지만, 검증의 필요성을 없애지는 않는다. 모델은 여전히 스택 트레이스를 잘못 읽거나, 처음 매칭된 파일에 과하게 맞추거나, 얕은 확인만 하고 멈출 수 있다.

검증은 최종 답변 전에 루프 안에서 이뤄져야 한다. 셸 명령 뒤에는 종료 상태와 출력을 다시 넣는다. 파일을 읽은 뒤에는 관련 내용을 다시 넣는다. 편집 뒤에는 의미 있는 가장 작은 검증기를 실행한다. 집중 테스트, 타입체크, 린트 규칙, 또는 재현 명령이 될 수 있다. OpenAI는 Codex 에이전트 루프 글에서 Codex를 사용자 입력, 모델 지침, 도구, 이전 항목을 둘러싼 오케스트레이션 루프로 설명한다.

class CodingAgent:
    def __init__(self, prompt):
        self.prompt = prompt
        self.tools = ["read", "edit", "run tests"]
        self.loop = ["observe", "plan", "act", "verify"]

    def solve(self, task):
        return (
            f"Task: {task}\n"
            f"Prompt: {self.prompt!r}\n"
            f"Agent: tools={self.tools}, loop={self.loop}\n"
            "Point: the prompt starts the work; tools, feedback, and verification do most of it."
        )


print(CodingAgent("fix the bug").solve("make the program correct"))
Captured stdout:
Task: make the program correct
Prompt: 'fix the bug'
Agent: tools=['read', 'edit', 'run tests'], loop=['observe', 'plan', 'act', 'verify']
Point: the prompt starts the work; tools, feedback, and verification do most of it.

최소 프롬프트는 어디까지면 충분한가?

최소 프롬프트 텍스트는 행동 의도에서 멈춰야 한다. 에이전트의 역할, 작업공간 경계, 편집 전 확인 원칙, 검증 수단으로 테스트를 선호한다는 점, 막혔을 때의 행동, 간결한 최종 보고 방식을 정의하는 정도다. Anthropic의 Agent SDK 문서는 최소 기본 시스템 프롬프트로도 도구 호출을 지원할 수 있으며, claude_code 프리셋이나 커스텀 프롬프트 문자열을 통해 제품별 동작을 더할 수 있다고 설명한다 . 이 경계를 지켜야 프롬프트가 정책 엔진처럼 변하지 않고 읽을 수 있는 상태로 남는다.

프롬프트가 결정론적 제어를 대신해서는 안 된다. 도구 스키마, deny 및 ask 규칙, 샌드박스 정책, 라이프사이클 훅, 콜백 검사는 타입이 있고 테스트와 감사가 가능한 코드로 표현하는 편이 낫다. Claude Code의 훅은 PreToolUse, PostToolUse, PermissionRequest, Stop, PostCompact 같은 라이프사이클 지점에서 실행된다 . 그런 검사는 모델에게 조심하라고 부탁하는 문단이 아니라 하네스에 있어야 한다.

• 프롬프트에 둘 것: 역할, 프로젝트 경계, 편집 전 확인, 실행 가능한 검증 선호, 막혔을 때 질문하기, 변경 파일과 테스트 결과 보고.
• 하네스에 둘 것: 허용 도구, 권한 모드, 샌드박싱, 승인 규칙, 훅 실행, 로깅, 재시도 또는 중단 조건.
• 평가에 둘 것: 에이전트가 올바른 파일을 편집하는지, 충분한 근거 뒤에 멈추는지, 검증 실패를 무한 반복 없이 처리하는지.

주의할 점은 권한 순서다. Anthropic의 Agent SDK는 훅, deny 규칙, ask 규칙, 권한 모드, allow 규칙, 그리고 canUseTool 스타일 콜백 순서로 평가한다. 일부 구성에서는 자동 승인된 호출 때문에 이후 콜백 로직에 도달할 수 없어서 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED 경고가 발생할 수 있다 . 안전 로직이 그곳에서 가려진 상태라면, 프롬프트 문구를 더 추가해도 문제가 해결되지 않는다.

최소 프롬프트가 작동한 뒤에는 무엇을 시도해야 할까?

최소한의 코딩 에이전트 프롬프트가 작동했다면, 다음 반복에서는 범위를 바깥으로 넓혀야 한다. 더 많은 설명을 붙이기 전에 명시적인 중단 예산, 검증 단계, 지속 메모리 경계, 훅 로깅, 더 좁은 도구 스키마를 추가하라. 현재 Claude Code의 기본 요소에는 스킬, 서브에이전트, MCP 서버, 훅, 권한, 세션 수준 제어가 포함되지만, 이것들은 에이전트 프롬프트 자체가 아니라 하네스와 런타임 계층에 속한다 Claude Code 기능 .

실패를 라우팅 신호로 삼아라. 에이전트가 잘못된 파일을 수정한다면 컨텍스트 조립, 검색, 저장소 스캔, 작업 프레이밍을 점검하라. 같은 실패 테스트를 계속 재시도한다면 최대 턴 규칙, 중단 조건, 필수 검증 단계로 실행 루프를 더 단단히 묶어라. 위험한 셸 명령을 시도한다면 더 긴 지시문이 그것을 억제해 주길 기대하지 말고 권한, 샌드박스 정책, 거부 규칙, 훅을 고쳐라. Claude Code는 PreToolUse, PostToolUse, PermissionRequest, Stop, PostCompact 같은 수명주기 이벤트용 훅을 문서화하고 있다 Claude Code 훅 가이드 .

유용한 확장 경로는 점진적이다. 스킬은 반복 가능한 워크플로를 패키징할 수 있고, 서브에이전트는 위임된 작업을 위해 컨텍스트와 도구를 분리할 수 있으며, MCP 서버는 타입이 지정된 인터페이스로 외부 시스템을 노출할 수 있다. 훅은 결정을 기록하거나 위험한 호출을 차단할 수 있고, 세션 수준 오버라이드는 기본 프롬프트를 다시 쓰지 않고 런타임 동작을 바꿀 수 있다 Claude Code 서브에이전트 . 각 추가 요소를 숨겨진 프롬프트 덩어리가 아니라 제품 제어면으로 다루어라.

class CodingAgent:
    def __init__(self, prompt):
        self.prompt = prompt
        self.tools = ["read", "edit", "run tests"]
        self.loop = ["observe", "plan", "act", "verify"]

    def solve(self, task):
        return (
            f"Task: {task}\n"
            f"Prompt: {self.prompt!r}\n"
            f"Agent: tools={self.tools}, loop={self.loop}\n"
            "Point: the prompt starts the work; tools, feedback, and verification do most of it."
        )


print(CodingAgent("fix the bug").solve("make the program correct"))

이 검증된 스니펫은 의도적으로 작게 만들었다. 프롬프트는 작업을 시작하고, 실제 작업의 대부분은 도구, 피드백, 검증이 맡는다. 실용적인 테스트는 단순하다. 프롬프트에서 설명의 절반가량을 덜어내고, 같은 하네스 제어를 유지한 채 같은 작업을 다시 실행해 보라. 동작이 달라진다면 그 규칙을 테스트하고, 로그로 남기고, 강제할 수 있는 프롬프트 바깥에 인코딩하라.

자주 묻는 질문

코딩 에이전트에서 시스템 프롬프트란 무엇인가?

시스템 프롬프트는 에이전트의 역할, 동작, 응답 경계를 정의하는 지시 계층이다. 코딩 에이전트에서는 간결하게 유지해야 한다. 에이전트가 어떻게 일해야 하는지는 설명하되, 권한, 샌드박싱, 도구 접근, 실행 정책은 하네스에 맡겨라. Anthropic의 Agent SDK 문서는 사용자 지정 시스템 프롬프트를 프리셋과 런타임 제어가 제공하는 더 넓은 제품 동작과 구분한다: Claude Code Agent SDK 시스템 프롬프트 문서.

Claude가 도구를 직접 실행하나?

아니다. Claude는 구조화된 출력을 통해 도구 사용을 요청하고, 주변 애플리케이션이 도구 호출을 실행한 뒤 결과를 반환한다. Anthropic의 도구 사용 흐름은 이를 모델이 도구 요청을 내보내고, 클라이언트가 도구를 실행하고, 클라이언트가 도구 결과를 다시 보내는 루프로 설명한다: Anthropic 도구 사용 문서.

하네스와 실행 루프는 어떻게 다른가?

하네스는 모델 주변의 런타임을 맡는다. 프로젝트 컨텍스트, 도구 정의, 권한, 샌드박싱, 로그, 상태, 사용자 상호작용이 여기에 포함된다. 실행 루프는 그 런타임 안에서 반복되는 모델-도구 사이클이다. 컨텍스트와 도구를 보내고, 도구 요청을 받고, 호출을 디스패치하고, 결과를 반환한 뒤, 작업이 정의된 중단 조건에 도달하면 멈춘다. OpenAI도 Codex를 도구, 사용자 입력, 이전 항목을 둘러싼 오케스트레이션된 루프로 비슷하게 설명한다: OpenAI Codex 에이전트 루프 글.

왜 모든 에이전트 규칙을 하나의 큰 프롬프트에 넣지 않는가?

모든 규칙을 하나의 큰 프롬프트에 넣으면 실패를 점검하기가 더 어려워진다. 권한, 컨텍스트 로딩, 재시도 동작, 검증 정책이 모두 설명문으로 표현되어 있으면, 실패가 모델 추론에서 왔는지, 누락된 컨텍스트에서 왔는지, 약한 도구 스키마에서 왔는지, 안전하지 않은 런타임 설정에서 왔는지 구분하기 어렵다. Claude Code 권한과 훅 같은 결정론적 제어는 감사하고, 테스트하고, 변경하기가 더 쉽다: Claude Code 권한 및 Claude Code 훅.

최소한의 코딩 에이전트 프롬프트에는 무엇이 들어가야 하나?

최소한의 코딩 에이전트 프롬프트는 역할, 작업공간 경계, 수정 전 점검 동작, 검증 선호, 막힌 상태에서의 동작, 간결한 보고 기대치를 정의해야 한다. 모든 도구 규칙이나 런타임 정책을 인코딩하려 해서는 안 된다. 실용적인 기준점으로, Claude Code는 프로젝트 컨텍스트, 도구, 서브에이전트, 훅, 권한 같은 제품 동작을 프롬프트 자체 바깥의 기능으로 노출한다: Claude Code 기능 개요.

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기