blog.ruahverce Vol · 2026 · Issue 001 — A field log of LLMs, RAG, and ML systems

Field Log · Entry

[Claude Code] AI 에이전트 과업 분해 — 큰 작업을 나누는 4가지 기준과 plan 에이전트 (2/8)

하네스 엔지니어링 시리즈 2편 오픈 그래프 카드

“이 앱 리팩토링해줘”라고 한 번에 던졌다가 두 시간 뒤에 엉뚱한 파일 30개가 수정돼 있던 경험, 한 번쯤 있을 겁니다. AI 에이전트의 실패는 능력 문제가 아니라 작업이 너무 컸기 때문인 경우가 많습니다.

이 글은 Claude Code·OpenCode 기반 에이전트에게 큰 작업을 어떻게 잘게 나눠 맡길 것인지 정리합니다. 결론부터 말하면, 좋은 분해는 검증 가능한 단위 × 컨텍스트 한도 × 의존성 구분 × 완료 기준의 4가지 조건을 모두 만족해야 하고, 실전에서는 OpenCode의 plan 에이전트(또는 Claude Code의 plan-only subagent)로 계획과 실행을 분리하는 패턴이 가장 효과적이었습니다.

이 글이 답하는 질문

  • AI 에이전트에게 큰 작업을 왜 한 번에 맡기면 실패하나?
  • 좋은 과업 분해의 4가지 조건은 무엇인가?
  • plan 에이전트와 메인 에이전트를 어떻게 분리하나?

”이거 다 해”는 왜 실패하나

AI에게 “이 앱을 리팩토링해줘”라고 던지면, 한 번에 너무 많은 파일을 건드리다가 중간에 맥락을 잃고 엉뚱한 결과를 냅니다. 컨텍스트 윈도우(AI가 한 번에 볼 수 있는 정보량)에는 한계가 있기 때문입니다.

Anthropic은 실제로 긴 작업에서 “환경 세팅용 initializer agent”와 “기능 단위로 전진하는 coding agent”를 분리하는 하네스를 제안합니다(Claude Code Best Practices — Anthropic). OpenAI도 큰 목표를 design → code → review → test 블록으로 쪼개 depth-first로 진행한다고 설명합니다(Practices for Governing Agentic AI Systems).

핵심은 간단합니다: AI가 한 번에 확실하게 처리할 수 있는 크기로 나누는 것.

좋은 분해의 4가지 조건

  1. 각 단위가 독립적으로 검증 가능 — 테스트를 돌릴 수 있는 크기
  2. 한 단위가 컨텍스트 윈도우를 넘기지 않음 — 너무 크면 중간에 잊음
  3. 순서와 병렬이 구분됨 — 뭐가 먼저여야 하고, 뭐가 동시에 가능한지
  4. 결과가 명확 — “완료”의 기준이 있어야 함

분해 템플릿

어떤 작업이든 아래 5개 질문으로 먼저 쪼갭니다:

1. 이 작업의 최종 결과물은 무엇인가?
2. 결과물을 만들려면 어떤 중간 산출물이 필요한가?
3. 각 중간 산출물은 독립적으로 테스트할 수 있는가?
4. 어떤 것이 먼저 되어야 다음 것이 가능한가? (의존성)
5. 병렬로 할 수 있는 것은 무엇인가?

실전에서 이 5개 질문을 한 시나리오에 적용하면 다음과 같습니다.

예시 — “블로그 검색 기능 추가”를 분해하면:

[단계 1] 검색 API 엔드포인트 설계 → 검증: API 스펙 문서 존재
[단계 2] DB 인덱스 추가 → 검증: 쿼리 성능 측정
[단계 3] 백엔드 검색 로직 구현 → 검증: 단위 테스트 통과
[단계 4] 프론트엔드 검색 UI → 검증: 컴포넌트 렌더링
[단계 5] 통합 테스트 → 검증: E2E 시나리오 통과

각 단계에 “검증”이 붙어 있는 게 핵심입니다. 검증이 없으면 “됐나?”를 판단할 수 없습니다.

CLAUDE.md에 분해 규칙 넣기

에이전트에게 매번 “잘게 나눠서 해”라고 말하는 대신, CLAUDE.md에 규칙으로 넣으면 됩니다. (CLAUDE.md의 전체 구조는 (3/8) 지식 구조화 참고)

# CLAUDE.md

## 작업 방식
- 새 기능을 구현할 때는 반드시 아래 순서를 따른다:
  1. 먼저 요구사항을 정리해서 plan.md에 기록
  2. 관련 코드를 읽고 영향 범위 파악
  3. 테스트를 먼저 작성 (TDD)
  4. 구현
  5. 테스트 통과 확인
  6. 커밋

- 한 번에 3개 이상의 파일을 동시에 수정하지 않는다
- 큰 리팩토링은 단계별 PR로 나눈다

이렇게 넣으면 에이전트가 알아서 이 순서를 따릅니다.

plan 에이전트 — 계획과 실행의 분리

plan 에이전트 플로우: 사용자 요청 → plan 에이전트가 코드 읽고 계획 수립 → 사용자 승인 → 메인 에이전트가 단계별 실행

OpenCode는 plan이라는 별도 에이전트를 제공합니다. 이 에이전트는 코드를 직접 수정하지 않고 읽기만 하면서 계획을 세웁니다.

@plan 이 프로젝트의 인증 시스템을 OAuth2로 마이그레이션하려면
어떤 순서로 해야 할까?

plan 에이전트가 코드를 읽고 단계별 계획을 작성하면, 이후 사용자가 각 단계를 하나씩 메인 에이전트에게 시킵니다.

도구별 비교:

도구계획 전용 에이전트특징
Claude Codesubagent + /plan 또는 plan permission-mode.claude/agents/planner.md에 tools.allow: [Read, Grep, Glob] + deny: [Write, Bash] 명시. 또는 claude --permission-mode plan으로 세션 단위 강제
OpenCode@plan 내장기본 제공. 읽기 전용 모드 강제
OpenClawplan 모드 라우팅workspace 격리로 계획자/실행자 분리

핵심은 **“같은 에이전트가 계획과 실행을 모두 하면 두 역할이 섞여서 맥락이 흐려진다”**는 원리입니다. 이 원리는 (7/8) 역할 분리 편에서 더 깊게 다룹니다. 각 단계 실행은 (5/8) 권한 설정의 plan 모드와 결합하면 더 안전합니다.

주의: 너무 잘게 나누면?

분해가 너무 세밀하면 오히려 오버헤드가 늘어납니다. “변수명 하나 바꾸기”를 위해 분석→계획→실행→검증 4단계를 밟을 필요는 없습니다.

안티패턴 예시:

  • “console.log 추가” 같은 1줄 변경에 계획→실행→검증 4단 루프
  • 같은 파일 안 3개 함수를 서로 다른 3개 세션으로 분리
  • 의존성이 거의 없는 독립 파일 수정을 직렬로 나열

경험칙: 30분 이상 걸릴 것 같으면 나누고, 5분 안에 끝날 것 같으면 그냥 합니다. 그 사이 영역은 “결과물이 독립 테스트 가능한가”로 판단합니다.

내가 실제로 부딪힌 문제와 해결 (1인칭 경험)

이 블로그 SEO 패치를 진행할 때도 처음에는 이미지, JSON-LD, robots, 사이트맵, About 신호까지 한 번에 보려 했습니다. 그런데 검증 포인트가 섞이자, 레이아웃은 좋아졌는데 사이트맵이 비거나, 글은 괜찮은데 메타 태그가 빠지는 식으로 확인 범위가 흐려졌습니다. 한꺼번에 많이 바꾸는 것이 속도를 높일 것 같았지만, 실제로는 어디서 문제가 생겼는지 찾는 시간이 더 길었습니다.

그래서 작업을 레이아웃 → 콘텐츠 → 메타데이터 → 빌드 검증처럼 독립적으로 확인 가능한 단위로 쪼갰습니다. 이렇게 나누고 나니 무엇이 먼저여야 하는지, 무엇이 병렬 가능한지가 훨씬 선명해졌습니다. 제 경험상 좋은 과업 분해는 화려한 계획표보다 중간 산출물을 바로 확인할 수 있느냐에서 갈립니다.

자주 묻는 질문 (FAQ)

Q1. 과업을 얼마나 잘게 나눠야 하나요? 이 글 본문의 30분/5분 경험칙을 보완하면, 판단의 핵심은 “중간 산출물이 하나라도 독립적으로 검증 가능한가”입니다. 5분 안에 끝날 변수명 변경 같은 작업에 4단계 분해를 적용하면 오버헤드가 작업보다 큽니다.

Q2. plan 에이전트를 쓰려면 꼭 OpenCode여야 하나요? 아닙니다. Claude Code에서도 subagent로 plan-only 역할을 만들 수 있습니다. tools.allow에 Read/Grep만 허용하고 Write/Bash를 차단하면 동일한 “계획자 ↔ 실행자” 분리를 구현할 수 있습니다. (관련: (7/8) 역할 분리 편)

Q3. 분해한 단계별로 세션을 나눠야 하나요? 1단계가 컨텍스트의 30% 이상을 잡아먹는 큰 변경이면 세션을 나누는 편이 안정적입니다. PROGRESS.md에 현재 단계를 명시하고 다음 세션에서 --continue 대신 새 세션으로 이어받으세요. (관련: (6/8) 메모리 패턴 편)

마무리

  • 좋은 분해는 검증 가능성·컨텍스트 한도·의존성·완료 기준 4가지를 모두 만족해야 합니다.
  • CLAUDE.md에 분해 규칙을 고정해 두면 에이전트가 매 세션 자동으로 따릅니다.
  • 계획과 실행을 다른 에이전트에 맡기는 것이 가장 효과적인 실전 패턴입니다.

다음에 읽으면 좋은 글

참고자료