agent가 스스로 진행 상황을 관리하게 하라

구조화된 self-planning

Claude Code가 일할 때 여러 단계가 필요한 경우가 많습니다: grep으로 참조를 찾고 → 여러 파일을 읽고 → 코드를 수정하고 → 테스트를 실행합니다. 모델이 "감각적으로 진행"하도록 두면 처음 몇 단계는 잘 하다가 중간에 잊어버리고 마지막에 중도 포기하는 것을 볼 수 있습니다.

s03의 해법은 목록 도구를 주는 것입니다: 모델이 직접 todo 도구를 호출해 작업 항목을 넣고, TodoManager는 구조를 검증하고, 저장하고, 현재 뷰를 반환합니다. 두 가지 장점이 있습니다:

• 모델이 "해야 할 일"을 명시적으로 표현하도록 강제됩니다—적는 것만으로도 사고 정리에 도움이 됩니다.
• 사람이 모델이 무슨 생각을 하는지 볼 수 있습니다. 디버깅 경험이 10배 좋아집니다.

# TODO 뷰, 각 항목은 구조화되어 있습니다
[ ] #1: grep "TODO" across src/
[>] #2: read src/app.py and list comments     # 진행 중
[ ] #3: generate summary markdown
[ ] #4: write to TODO_LIST.md

(0/4 completed)

하드 규칙: 동시에 하나의 in_progress만 허용

TodoManager.update()에는 한 가지 검증이 있습니다:

if in_progress_count > 1:
    raise ValueError("Only one task can be in_progress at a time")

엄격해 보이지만 사실 모델을 돕는 것입니다. 동시에 3개가 "진행 중"이 되면 여기저기 손대다 아무것도 완성하지 못합니다. 단일 작업 진행을 강제하면 하나를 완료해야 다음으로 넘어갑니다.

아래 widget에서 모델 역할을 해보고, 다양한 todo payload를 제출해 어떤 것이 검증을 통과하고 어떤 것이 거부되는지 확인하세요.

Nag reminder: 3회 연속 업데이트 없으면 한 번 찌르기

todo 도구를 줘도 모델은 가끔 목록 업데이트를 "잊습니다"—많은 일을 했는데 in_progress가 여전히 2번째 항목에 머물러 있는 경우입니다. s03의 방법은 매우 단순한 카운터입니다:

rounds_since_todo = 0
while True:
    response = LLM(messages, tools)
    ...
    used_todo = any(b.name == "todo" for b in tool_uses)
    rounds_since_todo = 0 if used_todo else rounds_since_todo + 1
    if rounds_since_todo >= 3:
        results.append({"type":"text", "text":"<reminder>Update your todos.</reminder>"})

카운트가 3에 달하면 다음 라운드의 user 메시지에 reminder를 끼워 넣습니다. 모델이 이것을 보면 본능적으로 todo를 업데이트합니다. 이는 공학적 수단으로 연성 제약("업데이트를 유지해 주세요")을 강제 자극으로 바꾸는 것입니다.

이 패턴의 이름은?

agent 설계 세계에서 이것은 structured self-planning with soft nudges라고 합니다—모델에게 반드시 써야 하는 구조화된 상태를 주고, 때에 맞는 reminder로 보완하는 것입니다. 실제 Claude Code 코드에서도 유사한 패턴을 사용하지만 더 절제되어 있습니다(빈도 낮음, 중립적 표현).

"매 단계 todo를 업데이트하라"를 system prompt에 쓰면 안 되나요? 쓸 수는 있지만, 모델이 대화가 길어질수록 system prompt의 일반 지시에 대한 복종도가 떨어집니다. 지시를 "반복 주입되는 reminder"로 분리하면 효과가 훨씬 안정적입니다.