AI 에이전트 개발 실전 #3 계획 세우기와 자기 수정

AI LLM Claude
5 분 소요

2편까지로 루프와 도구가 갖춰졌습니다. 짧은 작업은 이미 잘 돕니다. 그런데 “지난달 주문 데이터를 정리해서 보고서 초안까지 만들어줘"처럼 단계가 많은 작업을 맡기면, 에이전트가 중간에 길을 잃거나 같은 실수를 반복하는 일이 생깁니다. 이번 글에서는 에이전트가 계획을 세우고, 중간 결과를 검증하고, 실패를 스스로 바로잡게 만드는 방법을 다룹니다.

시스템 프롬프트로 행동 규칙 주기 #

지금까지는 목표만 user 메시지로 줬습니다. 여러 단계 작업에서는 작업마다 바뀌는 목표와 별개로, 늘 지켜야 하는 행동 규칙을 시스템 프롬프트에 둡니다.

agent_system_prompt.py 
SYSTEM = """너는 주문 데이터를 다루는 운영 보조 에이전트다.

규칙:
- 작업을 시작하기 전에 단계별 계획을 먼저 세우고, 계획을 한 줄씩 나열한다.
- 각 단계를 마칠 때마다 결과를 한 문장으로 확인하고 다음 단계로 간다.
- 데이터를 변경하는 작업은 변경 전에 현재 값을 먼저 조회해서 확인한다.
- 같은 도구가 같은 입력으로 두 번 연속 실패하면, 다른 방법을 찾거나 작업을 멈추고 상황을 보고한다.
"""

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=SYSTEM,
    tools=tools,
    messages=messages,
)

규칙은 추상적인 다짐보다 행동으로 적는 것이 효과적입니다. “신중하게 행동한다"보다 “변경 전에 현재 값을 먼저 조회한다"가 훨씬 잘 지켜집니다.

계획을 먼저 세우게 하기 #

위 규칙 중 첫 번째가 핵심입니다. 복잡한 작업일수록, 도구부터 부르는 것보다 계획을 먼저 텍스트로 나열하게 하는 편이 결과가 좋습니다. 계획이 대화에 남아 있으면 Claude가 매 단계에서 그 계획을 다시 보면서 진행하기 때문에, 긴 작업에서도 처음 목표를 잊지 않습니다.

계획은 한 번 세우면 끝이 아닙니다. 중간 결과가 예상과 다르면 계획을 고쳐야 합니다. 이것도 규칙으로 적을 수 있습니다. “중간 결과가 계획과 다르면, 남은 계획을 수정해서 다시 나열한 뒤 진행한다"처럼요.

중간 검증을 작업에 끼워 넣기 #

여러 단계 작업에서 가장 위험한 것은, 중간 단계의 실패를 모른 채 다음 단계를 쌓는 일입니다. 막는 방법은 단순합니다. 확인하는 단계를 작업의 일부로 만드는 것입니다.

  • 데이터를 변경했으면, 변경 후 다시 조회해서 의도대로 바뀌었는지 확인합니다.
  • 파일을 만들었으면, 다시 읽어서 내용이 맞는지 확인합니다.
  • 코드를 고쳤으면, 테스트를 실행해서 통과하는지 확인합니다.

검증에 쓸 도구는 대부분 이미 있습니다. 조회 도구가 곧 검증 도구입니다. 필요한 것은 시스템 프롬프트의 규칙 한 줄입니다. “변경 작업 후에는 반드시 결과를 다시 조회해서 확인한다.”

검증이 실패하면 그 결과가 도구 결과로 대화에 들어가고, Claude는 실패를 보고 수정 시도를 합니다. 이것이 자기 수정의 기본 회로입니다. 검증 단계가 없으면 이 회로 자체가 생기지 않습니다.

같은 실수의 반복 멈추기 #

자기 수정에는 부작용이 하나 있습니다. 가끔 같은 방법을 조금씩 바꿔 가며 끝없이 재시도하는 것입니다. 1편의 max_steps가 최후의 안전장치지만, 그 전에 루프 쪽에서 반복을 감지해 끊어 줄 수 있습니다.

repeat_guard.py 
from collections import Counter

failure_count = Counter()

def execute_tool(block) -> dict:
    result = try_run_tool(block)
    if result.get("is_error"):
        key = (block.name, str(block.input))
        failure_count[key] += 1
        if failure_count[key] >= 3:
            result["content"] += (
                " 이 방법은 3회 실패했습니다. 같은 시도를 반복하지 말고,"
                " 다른 방법을 찾거나 지금까지의 상황을 정리해 보고하세요."
            )
    return result

같은 도구·같은 입력의 실패 횟수를 세다가, 한계에 도달하면 에러 메시지에 지시를 덧붙입니다. 2편에서 본 원칙 그대로입니다. 에러 메시지는 Claude가 읽고 따르는 문서이므로, 루프가 파악한 상황을 그 안에 적어 주면 됩니다.

adaptive thinking으로 생각 깊이 조절하기 #

계획과 자기 수정은 결국 추론의 품질 문제이기도 합니다. Claude에는 응답 전에 내부적으로 생각하는 thinking 기능이 있고, 최신 모델에서는 adaptive로 켭니다. 언제 얼마나 생각할지를 Claude가 작업 난이도에 맞춰 스스로 정하는 방식입니다.

adaptive_thinking.py 
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    system=SYSTEM,
    tools=tools,
    messages=messages,
)

effort는 전체적인 노력 수준을 정하는 파라미터입니다. low, medium, high, max가 있고, 에이전트 작업에는 high 이상을 권장합니다. 깊이 생각할수록 토큰을 더 쓰지만, 에이전트에서는 계획이 좋아져 전체 단계 수가 줄어들기 때문에 총비용이 오히려 내려가는 경우가 많습니다.

참고로 claude-opus-4-8에서는 temperature 같은 샘플링 파라미터가 제거되어, 보내면 400 에러가 납니다. 동작 조절은 시스템 프롬프트와 effort로 합니다.

흔히 걸려 넘어지는 곳 #

  • 규칙을 user 메시지에 넣는다 — 행동 규칙을 매번 목표와 함께 보내면 대화가 길어질수록 묻혀 버립니다. 늘 지킬 규칙은 시스템 프롬프트에 둡니다.
  • 검증 없이 단계를 쌓는다 — 3단계에서 틀어진 작업이 7단계에서 발견되면 되돌릴 것이 많아집니다. 변경 직후의 검증이 가장 쌉니다.
  • 재시도에 한계를 안 둔다 — 자기 수정을 믿고 무한정 돌리면 같은 실패에 토큰만 태웁니다. 실패 횟수를 세고, 한계에서 방향 전환을 지시합니다.

마무리 #

이번 글에서는 여러 단계 작업을 버티는 에이전트의 행동 설계를 다뤘습니다.

  • 행동 규칙은 시스템 프롬프트에, 구체적인 행동으로 적습니다. 계획을 먼저 나열하게 하는 규칙이 특히 효과적입니다.
  • 변경 후 재조회 같은 검증 단계를 작업에 끼워 넣어야 자기 수정 회로가 돌기 시작합니다.
  • 같은 실패의 반복은 루프에서 감지해 끊고, adaptive thinking과 effort로 생각 깊이를 작업에 맞춥니다.

그런데 단계가 늘어나면 또 다른 문제가 등장합니다. 대화가 길어지면서 컨텍스트가 한계에 가까워지는 것입니다. 다음 글인 “AI 에이전트 개발 실전 #4 긴 작업을 버티는 컨텍스트 관리"에서 다룹니다.

X