research

Anthropic Initializer + Coding Agent 패턴

Anthropic Initializer + Coding Agent 패턴

출처: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents (2025.11)

문제: Long-running agent의 두 가지 실패 패턴

  1. One-shot 시도: agent가 한 번에 너무 많이 하려 한다. 컨텍스트 중간에 기능이 반쯤 구현된 채 끝나고, 다음 세션 agent가 무슨 일이 있었는지 추측하느라 시간 낭비.
  2. 조기 완료 선언: 진행이 됐을 때 나중 agent가 둘러보고 "충분히 됐다"고 선언해버림.

핵심 원인: 새 세션이 시작되면 이전 세션의 기억이 없다.

해결책 구조

Initializer Agent (첫 번째 세션만)

역할: 이후 모든 coding agent가 필요로 하는 환경을 구축한다.

생성하는 것들:

  • init.sh — dev server 실행 스크립트
  • claude-progress.txt — agent 간 handoff 파일
  • feature_list.json — 전체 feature 목록 (전부 passes: false로 시작)
  • 초기 git commit
{
  "category": "functional",
  "description": "New chat button creates a fresh conversation",
  "steps": [
    "Navigate to main interface",
    "Click the 'New Chat' button",
    "Verify a new conversation is created",
    "Check that chat area shows welcome state",
    "Verify conversation appears in sidebar"
  ],
  "passes": false
}

왜 JSON인가: Markdown보다 agent가 부적절하게 수정하거나 덮어쓸 가능성이 낮다.

Coding Agent (이후 모든 세션)

매 세션 시작 시 수행하는 steps:

  1. pwd — 작업 디렉토리 확인
  2. claude-progress.txt + git log 읽기 — 현재 상태 파악
  3. feature_list.json 읽기 — 완료 안 된 최우선 feature 선택
  4. init.sh 실행 — dev server 시작
  5. 기본 기능 end-to-end 테스트 — broken state 있으면 먼저 수정
  6. 새 feature 구현 (하나씩)
  7. 세션 종료 시 git commit + progress 파일 업데이트

핵심 설계 원칙

1. Incremental progress (한 번에 하나씩)

한 번에 하나의 feature만 작업하도록 강제. → "한 번에 너무 많이 하려는" 경향을 구조적으로 차단.

2. Clean state 마무리

세션을 끝낼 때 main branch에 merge 가능한 상태로:

  • 큰 버그 없음
  • 코드 정돈 + 문서화
  • 다른 개발자가 새 feature 바로 시작 가능

git commit + progress 파일 업데이트를 강제해서 달성.

3. 테스트는 인간처럼

Unit test / curl만으론 end-to-end 검증이 안 됨. Puppeteer MCP 같은 브라우저 자동화 도구를 주면 인간 사용자처럼 테스트 가능. → 코드만으론 안 보이는 버그를 잡을 수 있음.

4. Feature는 passes 변경으로만 수정

"passes 필드를 변경하는 것 외에 테스트를 제거하거나 편집하는 것은 허용되지 않는다"를 강하게 명시.

실패 패턴과 해결책

| 문제 | Initializer | Coding Agent | |---|---|---| | 너무 일찍 완료 선언 | feature list JSON 생성 | 매 세션 feature list 읽고 하나 선택 | | 버그 있는 상태로 세션 종료 | git repo + progress 파일 초기화 | 시작 시 읽기, 종료 시 commit + update | | feature를 너무 빨리 done 표시 | feature list JSON 생성 | self-verify 후에만 passes: true | | app 실행 방법 파악에 시간 낭비 | init.sh 작성 | 세션 시작 시 init.sh 읽기 |

인간의 역할

이 패턴에서 인간은:

  • 처음에 Initializer에게 뭘 만들지 설명
  • claude-progress.txt + git log로 전체 맥락 투명하게 추적
  • y/n 블랙박스가 아니라 파일 기반으로 진행 상황 파악 가능

미해결 문제

  • 단일 범용 coding agent vs. 전문 agent (testing agent, QA agent, cleanup agent) 중 어느 게 나은가?
  • 이 패턴이 full-stack web app 이외의 영역(과학 연구, 금융 모델링 등)에 어떻게 일반화되는가?

코드 예시

https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding

관련 개념

Feature List vs. Skill — 다른 개념

Feature list JSON = "무엇을" (상태 추적)

할 일 목록 + 완료 여부. agent가 "아직 안 한 일이 뭐가 있지?"를 파악.

Skill (AGENTS.md, docs/) = "어떻게" (방법론)

아키텍처, 컨벤션, 제약. agent가 "이 종류의 작업을 어떻게 잘 할 수 있지?"를 파악.

전체 파일 역할 분담

| 파일 | 역할 | 질문 | |---|---|---| | feature_list.json | 할 일 목록 + 진행 상태 | "무엇을?" | | AGENTS.md / docs/ | 아키텍처, 컨벤션, 제약 | "어떻게?" | | init.sh | 실행 환경 설정 | "어떤 환경에서?" | | claude-progress.txt | 히스토리, 맥락 | "지금까지 뭘 했지?" |

왜 분리가 중요한가

  • Feature list만 있고 skill 없음 → 뭘 만들지는 알지만, 일관성 없는 구현
  • Skill만 있고 feature list 없음 → 어떻게 하는지는 알지만, 조기 완료 선언 문제
  • 둘 다 있어야 agent가 올바르게 작동

전체 구조 요약 (Mental Model)

feature_list.json   →  목표 (무엇을)       agent 읽기/쓰기
tool calls          →  도구 (수단)         agent 실행
skill / docs/       →  방법론 (어떻게)     agent 읽기
init.sh             →  환경 (어디서)       agent 실행
claude-progress.txt →  맥락/히스토리       agent 읽기/쓰기, 인간 관찰

인간은 claude-progress.txt와 git log를 관찰하는 위치. 직접 쓰는 건 agent, 인간은 읽으면서 "지금 어디까지 왔나"를 파악. → 인간 전용 도구가 아니라, 인간과 agent가 공유하는 handoff 문서.

← research 목록으로홈으로