코딩 에이전트 직접 프롬프팅 중단: 프롬프트 자동화 루프 구축하기

더 이상 코딩 에이전트에 프롬프트를 입력해서는 안 됩니다. 에이전트에 프롬프트를 제공하는 루프를 설계해야 합니다. 이는 흘려들을 수 있는 말처럼 들리지만, 현재 유능한 엔지니어들이 AI와 작업하는 방식에서 가장 큰 변화를 나타냅니다. AI 코딩 에이전트를 통해 실질적인 이점을 얻는 사람들은 에이전트를 대화 파트너로 여기는 것을 멈췄습니다. 그들은 에이전트를 자신이 구축한 루프 내부의 작업자로 취급합니다.

버튼

요약 (TL;DR)

코딩 에이전트 루프는 에이전트를 반복적으로 실행하는 제어 구조입니다: 변경 사항을 생성하고, 실행하고, 강력한 신호에 대해 결과를 확인하고, 실패를 다시 피드백하고, 확인이 통과하거나 한계에 도달할 때까지 반복합니다. 에이전트 자체가 어려운 부분이 아닙니다. 검증 게이트가 어렵습니다. 모호한 게이트("괜찮아 보여, 다시 시도해봐")를 가진 루프는 표류하며 "완료"를 환각합니다. 결정론적 게이트(실패하는 테스트, 스키마 불일치, 깨진 계약)를 가진 루프는 수렴합니다. API 및 백엔드 작업의 경우, 자동화된 테스트 스위트와 계약 검사가 바로 그 게이트입니다. 이것이 바로 API 테스트가 에이전트 워크플로의 중심에 있어야 하고, 마지막에 덧붙여지는 것이 아닌 이유입니다.

프롬프트 입력에서 루프 설계로

대부분의 사람들은 채팅 상자를 통해 AI 코딩을 접합니다. 요청을 입력하고, 답변을 읽고, 작동하는 것을 복사한 다음 다시 입력합니다. 이것이 프롬프트 입력입니다. 일회성 함수나 빠른 설명에는 괜찮습니다. 그러나 작업이 제대로 수행되기 위해 한 번 이상의 피드백 라운드가 필요할 때(대부분의 실제 작업에서 그렇듯이) 무너집니다.

수동 프롬프트 입력의 문제입니다. 당신이 바로 루프입니다. 당신이 출력을 읽고, 버그를 찾아내고, 다음에 무엇을 말할지 결정하고, 오류를 다시 붙여넣습니다. 모든 반복은 인간을 기다립니다. 에이전트는 몇 초 만에 코드를 생성할 수 있지만, 당신이 컨텍스트를 전환하고, 스크롤하고, 타이핑하는 동안 몇 분 동안 유휴 상태로 있습니다. 당신은 빠른 시스템의 느린 부분이 됩니다.

루프를 설계하는 것은 이러한 상황을 뒤집습니다. 출력을 읽고 다음 프롬프트를 결정하는 주체가 되는 대신, 자동으로 이를 수행하는 하네스를 구축합니다. 에이전트가 코드를 작성합니다. 스크립트가 이를 실행합니다. 결과가 캡처됩니다. 실패하면, 그 실패는 다음 프롬프트로 에이전트에 바로 전달됩니다. 내부 루프에는 사람이 없습니다. 당신은 오직 경계선에서만 개입합니다: 작업을 설정하고, 결과를 승인하고, 잘못될 경우 실행을 중지시키는 것입니다. 효과적인 에이전트 구축에 대한 Anthropic의 자체 글도 다른 표현으로 같은 점을 강조합니다. 승리는 모델 주위에 연결하는 환경에서 나오며, 더 영리한 단일 프롬프트에서 나오는 것이 아닙니다.

정신 모델의 변화는 작지만 완전합니다. "에이전트에게 무엇을 말해야 할까?"라고 묻는 것을 멈추고 "어떤 루프가 에이전트가 스스로 말하게 만들까?"라고 묻기 시작하세요.

코딩 에이전트 루프의 실체

과장된 부분을 걷어내면 코딩 에이전트 루프는 다섯 가지 부분으로 구성됩니다. 하나라도 빠뜨리면 루프는 결코 종료되지 않거나 잘못 종료됩니다.

**작업 사양.** 완료된 모습에 대한 명확하고 서면화된 설명입니다. "작동하게 만들어라"가 아니라, "POST /orders 엔드포인트는 생성된 주문과 함께 201을 반환하고, 스키마에 대해 본문을 검증하며, 누락된 필드는 422로 거부한다"와 같은 식입니다.
**에이전트.** 모델과 그 도구들: 파일 읽기, 파일 쓰기, 셸 명령어 실행. 이것은 모든 사람이 집착하지만 당신이 가장 통제할 수 없는 부분입니다.
**실행 단계.** 에이전트가 변경 사항을 만들면, 실제로 무언가가 이를 실행합니다. 테스트, 빌드, 타입 검사, 라이브 엔드포인트에 대한 요청 등이 있습니다.
**검증 게이트.** 구체적인 이유와 함께 통과 또는 실패를 반환하는 결정론적 검사입니다. 이것이 조향 장치(핸들)입니다. 이 글의 대부분을 여기서 다룰 것입니다.
**종료 조건.** 루프는 언제 멈춥니까? 게이트 통과, 최대 반복 횟수 도달, 또는 비용 예산 초과 시입니다. 종료 조건이 없는 루프는 워크플로가 아니라 폭주하는 것입니다.

의사 코드(pseudocode)로 전체 패턴은 몇 줄 안에 들어갑니다:

task = load_spec("orders-endpoint.md")
for attempt in range(MAX_ITERATIONS):
    agent.run(task, feedback=last_result)   # generate
    result = run_verification()             # run + check the gate
    if result.passed:
        break                               # terminate: success
    last_result = result.failures           # feed failure back
else:
    escalate_to_human(last_result)          # terminate: gave up

그 루프가 전체 아이디어입니다. 에이전트가 생성하고, 게이트가 판단하며, 실패가 다음 프롬프트가 되고, 모든 것이 성공(green)하거나 시도 횟수를 모두 소진할 때까지 실행됩니다. 사람들이 온라인에서 "Ralph" 기법으로 공유하는 변형은 MAX_ITERATIONS를 높게 설정하고 사양을 엄격하게 작성한 것입니다. 에이전트 하네스 아키텍처에 대한 저희의 분석을 읽어보셨다면, 이것이 가장 작고 정직한 형태의 하네스입니다.

원샷 프롬프트가 한계에 부딪히는 이유

단일 프롬프트는 모델이 처음부터 올바르게 작동하거나, 모델이 잘못한 부분을 당신이 잡아낼 것이라고 가정합니다. 두 가지 가정 모두 대규모에서는 무너집니다.

모델은 그럴듯한 코드를 생성하는 데는 강하지만, 그 코드가 올바른지 아는 데는 약합니다. 그들은 올바르게 보이고 컴파일되며, 에지 케이스에서 조용히 잘못된 상태 코드를 반환하는 엔드포인트를 작성할 것입니다. 채팅에서는 프로덕션에 적용될 때까지 눈치채지 못할 수도 있습니다. 모델은 에지 케이스가 깨졌다는 피드백을 받지 못하므로, 자신 있게 성공을 보고합니다. "완료된 것처럼 보이는 것"과 "실제로 완료된 것" 사이의 그 간격이 바로 루프가 제 역할을 하는 지점입니다.

루프는 모델이 자신의 작업에 대해 내리는 의견을 거부함으로써 그 간격을 좁힙니다. 에이전트는 완료되었다고 말할 수 없습니다. 게이트가 그렇게 말합니다. 테스트를 실행하세요. 만약 빨간불이 들어오면, 작업은 완료되지 않은 것이며, 그 빨간색 출력은 에이전트가 읽을 다음 것입니다. 모델의 자신감은 더 이상 중요하지 않습니다. 오직 신호만이 중요합니다.

생산성 측면도 있습니다. 수동 프롬프트 입력은 당신이 적극적으로 지켜보는 한 에이전트로 처리량을 제한합니다. 루프를 사용하면 여러 에이전트를 동시에 실행할 수 있으며, 각 에이전트는 자신의 게이트에 대해 자신의 작업을 수행합니다. 그 이유는 내부 사이클에서 당신이 필요하지 않기 때문입니다. 이것이 바로 동적, 병렬 에이전트 워크플로에 대한 저희 글에서 다루는 비약적인 발전입니다: 루프가 자동화되면, 더 빨리 타이핑하는 것이 아니라 루프를 추가함으로써 확장할 수 있습니다.

모든 사람이 간과하는 부분: 검증 게이트

불편한 진실입니다. 대부분의 실패한 에이전트 워크플로는 모델이 너무 약해서 실패하는 것이 아닙니다. 피드백 신호가 너무 약해서 실패합니다.

게이트가 무엇을 하는지 생각해보세요. 매 반복마다 게이트는 에이전트에게 두 가지 중 하나를 알려줍니다: 통과했으니 멈춰라; 또는 실패했으니 정확한 이유는 여기 있다. "정확한 이유가 여기 있다"의 품질이 다음 반복이 개선될지 아니면 표류할지를 결정합니다. 42번째 줄과 실패한 어설션을 가리키는 정확한 스택 트레이스를 에이전트에게 제공하면, 에이전트는 올바른 것을 수정합니다. "뭔가 잘못된 것 같으니 검토해달라"고 제공하면, 에이전트는 추측하고, 종종 더 자신감 있는 소리를 내면서 코드를 더 나쁘게 만듭니다.

결정론적 게이트는 수렴합니다. 모호한 게이트는 표류합니다. 이것이 핵심입니다.

좋은 게이트는 무엇입니까?

**이진적이고 재현 가능합니다.** 매번 동일한 입력에 대해 동일한 판정을 내립니다. "모델이 오늘 기분이 어떤지에 따라 달라진다"는 것은 없습니다.
**명확한 이유와 함께 실패를 알립니다.** 테스트 이름, 예상 대 실제 차이(diff), 줄 번호, 오류 코드 등입니다. 이 이유는 다음 프롬프트가 되므로 구체적이어야 합니다.
**에이전트가 조용히 편집할 수 없습니다.** 에이전트가 테스트를 변경하여 통과시킬 수 있다면, 그 게이트는 쇼에 불과합니다. 게이트를 보호하세요. 에이전트가 소유한 코드가 아니라 사양으로 취급해야 합니다.
**루프를 돌릴 수 있을 만큼 빠르게 실행됩니다.** 20분 걸리는 게이트는 반복 속도를 제한합니다. 긴밀한 루프에는 빠른 검사가 필요합니다.

모든 성숙한 코드베이스에는 좋은 게이트가 이미 존재합니다. 단위 테스트, 타입 검사기, 린터, 컴파일러, 스키마 유효성 검사기, 계약 테스트 등이 있습니다. 이들은 결정론적 오라클입니다. 이들은 사람들에게 "이것은 잘못되었고, 그 이유는 이것입니다"라고 알려주기 위해 만들어졌으며, 이는 에이전트 루프가 필요로 하는 바로 그 신호입니다. 게이트를 새로 발명할 필요가 없습니다. 이미 신뢰하는 게이트에 루프를 연결하고, 커버리지가 부족한 곳에 새로운 게이트를 작성해야 합니다. 그 계층을 공식화한 적이 없다면, 자동화된 테스트의 실제 모습에 대한 저희 가이드를 루프에 연결하기 전에 좋은 기반으로 삼을 수 있습니다.

API 및 백엔드 작업의 경우, 테스트 스위트가 곧 루프입니다

이것은 서비스를 구축하는 모든 사람에게 추상적인 아이디어가 구체화되는 지점입니다. 에이전트가 API 엔드포인트를 작성할 때, 그것이 작동한다고 말하는 최종 진실은 무엇입니까? 모델의 요약이 아닙니다. 테스트 중인 엔드포인트의 실제 동작입니다: 올바른 상태 코드, 스키마와 일치하는 응답 본문, 인증 적용, 잘못된 입력 거부, 계약 준수.

그 모든 것은 자동적으로 결정론적인 결과와 함께 확인 가능합니다. 이는 당신의 API 테스트 스위트가 에이전트 루프가 필요로 하는 검증 게이트와 정확히 같은 형태로 이미 구성되어 있다는 의미입니다. 당신은 내내 게이트를 구축하고 있었던 것입니다; 단지 그것을 테스트라고 불렀을 뿐입니다.

엔드포인트 작업을 위한 구체적인 루프는 다음과 같습니다:

에이전트가 작업 사양과 OpenAPI 정의를 읽은 다음 엔드포인트를 작성하거나 편집합니다.
하네스가 실행 중인 서비스에 대해 API 테스트 스위트를 실행합니다: 상태 어설션, 모든 응답에 대한 JSON 스키마 유효성 검사, 사양에 대한 계약 검사.
실패는 구조화되어 돌아옵니다. "customer_id 누락 시 422를 예상했으나 500을 받았습니다." "응답 필드 total이 문자열인데 스키마는 숫자라고 합니다." "사양의 엔드포인트 /orders/{id}는 구현되어 있지 않습니다."
그 구조화된 실패가 에이전트의 다음 프롬프트가 됩니다. 에이전트는 특정 간극을 수정합니다.
스위트가 성공(green)할 때까지 반복한 다음, 검토를 위해 인간에게 넘깁니다.

핵심은 3단계의 피드백이 분위기가 아니라 정확하고 기계가 생성한 것이라는 점입니다. 그것이 루프가 헤매지 않고 수렴하게 만드는 요인입니다. 여기서 스키마 우선 및 계약 테스트는 그 어느 때보다 중요합니다. 왜냐하면 OpenAPI 사양이 에이전트와 게이트 모두가 읽는 공유된 진실의 원천이 되기 때문입니다. 코드와 사양 간의 불일치는 더 이상 느린 문서화 문제가 아니라 즉각적인 빨간 게이트가 됩니다.

이것이 Apidog가 에이전트 워크플로에서 수행하는 역할입니다. Apidog는 디자인, 스키마, 모의 서버 및 자동화된 테스트가 한곳에 통합된 올인원 API 플랫폼으로, 이는 게이트와 사양이 기본적으로 동기화 상태를 유지한다는 의미입니다. 당신은 Apidog 테스트 시나리오에 루프를 연결하고, 에이전트는 모든 반복에서 스키마 유효성 검사를 거친 통과/실패 결과를 얻으며, 모의 서버는 아직 구축되지 않은 종속성을 대신하여 에이전트가 안정적인 대상을 기반으로 작업할 수 있도록 합니다. 이 패턴을 이미 실행 중인 팀들은 Apidog AI 에이전트 디버거와 같은 것을 통해 에이전트의 도구 접근을 연결하여 에이전트가 인간 테스터와 동일한 방식으로 엔드포인트를 호출하고 검사할 수 있도록 합니다. 수동으로 테스트 러너를 만드는 대신 시각적으로 게이트를 구축하고 싶다면 Apidog를 다운로드하세요.

오늘 최소한의 자체 수정 API 루프 구축하기

시작하는 데 프레임워크가 필요하지 않습니다. 사양, 테스트 명령, 그리고 몇 줄의 글루 코드가 필요합니다. 여기 실제 작업을 수행하는 가장 작은 버전이 있습니다.

1단계: 게이트의 의도로 사양 작성. 계약을 OpenAPI 파일에, 동작을 테스트 케이스에 넣습니다. 에이전트는 이 둘을 모두 읽습니다. 이것은 문서화 역할도 하므로, 버려지는 작업이 아닙니다.

2단계: 실패 시 0이 아닌 값으로 종료되는 테스트 명령 선택. 종료 코드가 정확하다면 어떤 것이든 작동합니다. pytest 스위트, Newman 실행, Apidog CLI 테스트 시나리오 등입니다. 루프는 통과/실패 및 캡처된 출력에만 관심이 있습니다.

# the gate, as one command
apidog run ./tests/orders-suite --reporter json > result.json

3단계: 루프 연결. 에이전트를 실행하고, 게이트를 실행하고, 결과에 따라 분기합니다.

MAX_ITERATIONS = 8
feedback = None
for attempt in range(MAX_ITERATIONS):
    run_agent(task="implement orders API per spec", feedback=feedback)
    gate = subprocess.run(["apidog", "run", "./tests/orders-suite",
                           "--reporter", "json"], capture_output=True)
    if gate.returncode == 0:
        print(f"green on attempt {attempt + 1}")
        break
    feedback = parse_failures(gate.stdout)   # the next prompt writes itself
else:
    print("8 attempts, still red; escalating to a human")

4단계: 게이트 보호. 에이전트가 편집할 수 있는 파일 목록에서 테스트 파일과 사양을 제외하세요. 만약 에이전트가 통과하기 위해 테스트를 다시 작성할 수 있다면, 당신은 진행 상황을 속이는 기계를 만든 것입니다.

5단계: 비용 제한. 반복 횟수를 제한하고, 지출을 제한하세요. 모든 시도를 기록하여 루프가 수렴하는지 아니면 실패하는지 확인할 수 있도록 합니다. 토큰 지출을 모니터링하고 있다면, 수렴하지 않는 루프는 예산을 빠르게 소진하기 때문에 에이전트 토큰 비용 절감에 대한 저희의 지침이 직접적으로 적용됩니다.

그것이 작동하는 자체 수정 루프입니다. 에이전트가 작성하고, 스위트가 판단하며, 실패가 방향을 이끌고, 자신감 있는 거짓말 대신 성공(green) 엔드포인트 또는 깔끔한 에스컬레이션을 얻게 됩니다.

좋은 루프 설계하기: 주의해야 할 실수들

작동하는 루프와 조용히 돈을 낭비하는 루프를 구별하는 몇 가지 패턴이 있습니다.

**에이전트가 스스로 숙제를 평가하도록 허용하는 것.** 유일한 검사가 "에이전트, 완료했습니까?"라면, 당신은 루프가 아니라 추가 단계가 있는 챗봇을 가지고 있는 것입니다. 게이트는 에이전트 외부에 있어야 합니다.
**너무 거친 게이트.** 세 가지 얕은 테스트로 "테스트 통과"는 에이전트가 세 가지 테스트를 만족시키고 커버되지 않은 모든 부분에 버그를 배포한다는 의미입니다. 루프 품질은 게이트 커버리지에 의해 제한됩니다. 얇은 테스트는 얇은 결과를 낳습니다.
**종료 가드 없음.** 최대 반복 횟수와 비용 상한선이 없는 루프는 모델이 해결할 수 없는 작업을 영원히 돌릴 수 있습니다. 항상 종료 조건을 설정하고, 문제가 발생하면 항상 인간에게 에스컬레이션해야 합니다.
**느린 게이트.** 15분짜리 통합 스위트는 훌륭한 야간 확인 도구이지만, 내부 루프에는 형편없습니다. 루프를 위한 빠른 게이트와 병합을 위한 철저한 게이트를 유지하세요. 외부 종속성을 모의(mock)하여 루프가 불안정한 타사 서비스에 대기하지 않도록 합니다.
**변경 가능한 사양.** 에이전트가 버그 있는 코드에 맞춰 OpenAPI 파일을 편집하면, 계약 테스트는 잘못된 이유로 성공(green)합니다. 사양은 헌법입니다. 에이전트는 사양 하에서 작동하는 것이지, 사양 위에서 작동하는 것이 아닙니다.
**하나의 거대한 작업.** "전체 서비스 구축"과 같은 거대한 작업을 처리하는 루프는 거의 수렴하지 않습니다. 각자 고유한 게이트를 가진 엔드포인트 크기의 작업으로 분해하세요. 작은 루프는 완료되지만, 큰 루프는 실패합니다.

대부분의 문제는 같은 원칙으로 귀결됩니다: 프롬프트가 아닌 신호에 투자하십시오. 여기에 제시된 연결 패턴과 실패 모드는 에이전트 워크플로 도구 연결에서 다룬 내용과 일치하며, 당신의 에이전트가 Claude Code, Cursor, Codex 또는 직접 구축한 것이든 관계없이 유효합니다.

앞으로의 방향

"프롬프트 입력은 멈추고, 루프를 시작하라"는 말은 더 긴 추세의 한 단면입니다. 가치 있는 기술은 프롬프트 작성이 아닙니다. 그것은 루프 설계입니다: 명확한 사양 작성, 결정론적 게이트 구축, 종료 조건 선택, 그리고 에이전트가 무엇을 건드릴 수 있고 없는지 결정하는 것입니다. 이는 프롬프트 엔지니어링보다 시스템 설계에 더 가깝고, 이미 테스트, 계약 및 CI 측면에서 생각하는 엔지니어에게 보상이 됩니다.

이는 또한 좋은 테스트 인프라의 가치를 변화시킵니다. 수년 동안 자동화된 테스트는 결코 필요하지 않기를 바랐던 보험과 같았습니다. 에이전트 워크플로에서는 빠르지만 신뢰할 수 없는 생성기를 올바른 결과를 수렴하는 시스템으로 바꾸는 조향 메커니즘이 됩니다. 강력한 자동화된 테스트 커버리지와 깔끔한 계약을 이미 갖춘 팀은 에이전트를 연결하여 즉시 이점을 얻습니다. 그것이 없는 팀은 자신감 넘치지만 테스트되지 않은 코드를 빠르게 생성하는 방법을 얻게 됩니다.

따라서 실용적인 움직임은 더 나은 모델이나 더 영리한 프롬프트를 쫓는 것이 아닙니다. 게이트를 구축하는 것입니다. 사양을 강화하세요. API 테스트를 결정론적이고 빠르게 만드세요. 스키마를 진실의 원천으로 유지하세요. 그런 다음 그 주변에 루프를 감싸고 게이트가 성공(green)할 때까지 에이전트가 반복적으로 실행하게 하세요.

핵심 요점

이 변화는 말하기는 쉽지만 내면화하기는 어렵습니다. 코딩 에이전트에 프롬프트를 입력하는 것을 더 잘하려고 하지 마십시오. 에이전트에 프롬프트를 제공하는 루프를 설계하는 것과 그 루프가 작동하는 피드백 신호를 더 잘 만드는 데 집중하세요. 에이전트는 올바른지 여부에 대한 신뢰할 수 있는 감각이 없는 빠른 생성기입니다. 루프는 결정론적 게이트를 통해 그 감각을 제공합니다. API를 구축하는 모든 사람에게, 당신은 이미 게이트를 소유하고 있습니다. 당신의 테스트 스위트, 스키마, 그리고 계약은 열정적인 생성기를 올바른 결과를 수렴하는 시스템으로 바꾸는 최종 진실입니다.

작게 시작하세요. 하나의 엄격한 사양을 작성하고, 하나의 빠른 API 테스트 스위트에 루프를 연결하고, 게이트를 보호하고, 반복 횟수를 제한하고, 당신이 내부 루프에 개입하지 않고 에이전트가 실패(red) 엔드포인트를 성공(green)으로 바꾸는 것을 지켜보세요. 그런 다음 다음 루프를 구축하세요. 게이트가 시각적이고, 스키마를 인식하며, 팀 전체에서 공유 가능하도록 만들고 싶다면, Apidog는 디자인, 모의, 자동화된 테스트를 하나의 작업 공간에서 제공합니다; 다운로드하여 테스트가 에이전트를 이끄는 원동력이 되도록 만드세요.

버튼