
설계서 1장으로 구현·리뷰·PR까지 — Claude Code로 오케스트레이터 Skill 만들기
요약
Claude Code를 활용해 설계서 한 장으로 구현부터 리뷰, PR까지 자동화하는 '오케스트레이터' 스킬 구축 사례를 소개합니다. 멀티 에이전트 환경에서 상태 관리를 위해 작업 진척도를 파일로 기록하는 '루프 엔지니어링'의 중요성을 강조합니다.
핵심 포인트
- 구현, 리뷰, 테스트를 서브 에이전트에게 맡기고 인간은 판단에 집중하는 워크플로우
- 세션 컨텍스트 유실을 방지하기 위해 작업 상태를 파일로 기록하는 상태 관리 전략
- workspace-plan 스킬을 통한 아키텍처, 계획, 로그 등의 문서화 자동화
- 루프 엔지니어링: 개발 플로우 전체를 자동화된 루프로 구성하는 방법론
용어 메모
오케스트레이터 (Orchestrator) / 지휘자: 스스로 구현하지 않고, 복수의 서브 에이전트 (Sub-agent)에게 지시를 내리고 결과를 확인하는 데 전념하는 역할 -
위임 (Delegation): 작업을 직접 수행하지 않고 서브 에이전트에게 맡기는 것 -
Contract: 프론트엔드와 백엔드가 공유하는 API의 타입 정의·스키마 -
동결 (Freeze): "이후에는 변경하지 않겠다"고 결정하여 확정하는 것 -
배리어 (Barrier): 그때까지의 작업이 모두 끝날 때까지 다음으로 진행할 수 없는 동기화 포인트 -
에스컬레이션 (Escalation): AI만으로 해결할 수 없는 문제를 인간의 판단으로 넘기는 것
구현을 AI 에이전트에게 맡기면, 이번에는 다른 문제가 발생합니다. 우리가 파악할 수 없는 속도로 코드가 늘어나 리뷰가 따라가지 못하게 되는 것입니다. 차이점(diff)을 전부 읽으려면 직접 쓰는 게 더 빠릅니다. 그렇다고 읽지 않고 머지(merge)할 수는 없습니다.
필자의 팀에서는 이를 역발상으로 해결했습니다. 구현도 리뷰도 테스트도 전부 서브 에이전트에게 맡기고, 메인 세션(및 인간)은 판단만 하는 체제입니다. 설계서를 작성하고 /workspace-plan orchestrate라고 입력하면, 구현 → 6관점 리뷰 → 수정 → 유닛 테스트 (Unit Test) → 최종 게이트 → PR 준비까지 진행되며, 인간이 등장하는 것은 5개의 확인 게이트뿐입니다.
Claude Code의 개발 책임자 Boris Cherny는 "my job is to write loops (내 직업은 루프를 쓰는 것이다)"라고 말했습니다¹. 본 기사는 이 "루프를 쓰는 것"을 개발 플로우 전체에 적용한 실례입니다. 루프 엔지니어링 (Loop Engineering)이라는 개념의 정리는 시리즈 제1회로 미루고, 여기서는 구현의 상세 내용에 집중하겠습니다.
참고로, 전제 조건이 되는 환경은 다음과 같습니다.
필자의 팀에서는 관리 화면·사용자용 프론트엔드 2개 (Next.js)·백엔드 API (NestJS)·Playwright E2E를 포함하는 모노레포 (Monorepo)를 운용하고 있으며,
.claude/skills에 18개의 스킬, .claude/agents에 12개의 서브 에이전트 정의를 두고 있습니다.
오케스트레이션(Orchestration) 이야기를 하기 전에, 그 토대가 되는 상태 관리(State Management)부터 설명하겠습니다. 멀티 에이전트(Multi-agent) 기사에서는 간과되기 쉽지만, 긴 플로우를 돌리기 위해서는 먼저 "지금 어디에 있는가"를 파일로 남길 수 있게 만드는 것이 우선입니다.
workspace-plan 스킬은 브랜치(branch)별로 .claude/workspace/{브랜치명}/을 나누고, 5개의 문서를 배치합니다.
| 파일 | 역할 |
|---|---|
overview.md | 개요·완성 조건 (설계서의 체크리스트가 전개됨) |
architecture.md | 아키텍처 설계 |
rollout-plan.md | 구현 계획과 체크리스트 |
worklog.md | 시계열 로그. 설계 판단의 근거와 교훈을 기록 |
known-issues.md | 기지(旣知)의 문제·미결 사항 |
이 스킬에는 모든 조작에 공통되는 가장 중요한 규칙이 하나 있습니다.
하나의 태스크/스텝이 끝날 때마다, 그때마다 워크스페이스 문서에 진척도를 반영한다 (작업 완료 = 문서 업데이트까지). 나중에 한꺼번에 쓰거나 기억에 의존하는 것은 금지.
세션의 기억(컨텍스트, Context)은 세션이 끝나면 사라집니다. 하지만 문서는 남습니다. 이 규칙 덕분에 세션이 끊겨도, 다음 날이어도, 다른 머신이어도, status 조작 하나로 "어디까지 진행되었고 무엇이 남아있는가"로 복귀할 수 있습니다. 머릿속의 상태를 파일로 써두는 것이야말로 긴 루프의 전제 조건입니다.
에픽 (Epic, 여러 티켓을 묶는 큰 작업 단위)은 부모 (tracker = 진척도를 모아서 보는 쪽) 워크스페이스와 자식 워크스페이스로 나눕니다.
포인트는 디렉토리를 중첩(nesting)시키지 않는 것입니다. 부모와 자식을 모두 플랫(flat)하게 나열하고, 부모-자식 관계는 문서 내의 상호 링크로 표현합니다. 자식이 독립된 브랜치·PR을 가질 수 있어야 한다는 점, git worktree와 충돌하지 않아야 한다는 점, 기존 조작 (init / status / update)을 그대로 사용할 수 있다는 점이 이유입니다. 자식의 진척도가 바뀌면 부모의 목록표에 반영(Roll-up)하며, status <부모>로 전체를 한눈에 확인할 수 있습니다.
orchestrate 조작의 대원칙은 이 한 문장입니다.
메인은 지휘자에 철저한다. 구현·리뷰·테스트를 직접 쓰지 않는다. 반드시 서브 에이전트에게 위임한다.
메인 세션이 수행해도 되는 것은 다음 6가지뿐입니다.
- 설계서·워크스페이스의 읽기 및 파악
- 서브 에이전트(Sub-agent)에게 지시 내리기
- 돌아온 요약(Summary)의 통합 및 판단
- 워크스페이스 업데이트
- 사용자 확인 게이트(User confirmation gate)
- 플로우 분기 제어
왜 이렇게까지 제한하는 것일까요? 하나는 메인의 컨텍스트(Context)를 판단을 위해 남겨두고 싶기 때문입니다. 구현의 생로그(Raw log), 거대한 diff, 테스트 실패 출력은 토큰(Token)의 덩어리이며, 이를 메인에 계속 쌓아 올리면 플로우 후반부로 갈수록 판단의 질이 떨어지고 비용도 급증합니다. 무거운 작업을 서브 에이전트의 별도 컨텍스트로 격리해 버리면, 메인으로 돌아오는 것은 '요약'만으로 충분합니다.
또 다른 이유는 고가 모델의 사고를 '분해'와 '검수(돌아온 결과의 검품)'에만 사용하고 싶기 때문입니다. 무엇을 어떻게 나눌 것인가, 돌아온 결과가 올바른가. 결국 이 부분이 가장 머리를 써야 하는 작업이며, 최상위 모델을 할당할 가치가 있는 곳이기도 합니다.
| 역할 | agent | 모델 |
|---|---|---|
| 프론트엔드 구현 | frontend-implementer | 상위 (opus) |
| 백엔드 구현 | backend-implementer | 상위 (opus) |
| 테스트 구현 | test-implementer | 상위 (opus) |
| FE 리뷰: 규약 / 품질 / UX | fe-review-convention / fe-review-quality / fe-review-ux | 상위 (opus) |
| BE 리뷰: 규약 / 보안 / 품질 | be-review-convention / be-review-security / be-review-quality | 상위 (opus) |
| Figma 가져오기 / Storybook 촬영 / 시각적 비교 | figma-fetch / storybook-shoot / figma-compare (제4회에서 상세 기술) | 가져오기·촬영은 표준 (sonnet), 시각적 비교는 상위 (opus) |
모델 배분 방침은 심플합니다. 코드의 읽기·쓰기나 지적 판단이 필요한 역할은 모두 상위 모델, 기계적인 가져오기·촬영만 표준 모델입니다. 지휘자 역할을 수행하는 메인 세션도 최상위 모델을 전제로 합니다 (필자의 팀에서는 지휘자 계열의 스킬에 "표준 모델로 기동되었다면 상위 모델로의 전환을 권장한다. 단, 중단시키지는 않는다"라는 주의사항을 넣어두었습니다). 토큰 소비 내역도 이 표와 같으며, 지배적인 것은 구현 3개와 리뷰 6개(모두 상위 모델)입니다.
리뷰가 6개나 있는 이유는 1 에이전트 = 1 관점으로 좁혔기 때문입니다. "규약도 버그도 UX도 전부 봐줘"라고 부탁하면 주의력이 분산됩니다. 관점을 좁힌 에이전트를 병렬로 실행하고, 지적 사항을 메인이 통합하는 편이 속도는 명확하게 빨라지며 탐지 정밀도도 높아진다고 생각합니다 (탐지율 자체에 대한 비교 측정은 아직 하지 않았습니다).
리뷰 에이전트의 정의는 예를 들어 다음과 같은 형태입니다 (발췌).
---
name: fe-review-convention
description: 프론트엔드 구현을 「설계 규약 준수」 관점에서만 엄격하게 리뷰한다.
...
"수정은 하지 않는다·지적만 한다"도 중요한 설계입니다. 리뷰어에게 수정까지 시키면, 지적 사항의 정리(관점 간 중복된 지적을 합치거나, 충돌하는 지적 중 어느 쪽을 택할지 결정하는 작업)를 메인이 수행하기 전에 코드가 바뀌어 버립니다.
또 하나 은근히 효과적인 장치가 있습니다. 각 에이전트가 사용하는 모델은 agent 정의의 frontmatter에만 쓰고, 스킬 측에는 일절 쓰지 않는 것입니다 (앞선 편성표의 모델 열은 이 frontmatter의 model:을 모은 것입니다). 같은 정보를 두 곳에 쓰면 한쪽만 업데이트되어 모순이 발생하는 '드리프트(Drift)'가 반드시 일어납니다. 팀 전체에서 "유일한 진실 공급원(Single source of truth)은 어디인가"를 파일 단위로 정해두는 것은 스킬 운용의 기본이라고 생각합니다.
구현 측면의 보충을 하나 하자면, 서브 에이전트의 기동은 Claude Code의 Agent 툴로 수행합니다 (이전에는 Task라는 이름이었습니다). 스킬의 frontmatter allowed-tools에 Agent를 포함해 두면 기동할 때마다 발생하는 허가 확인을 생략할 수 있습니다. 단, allowed-tools
이는 '사전 승인'일 뿐 이용 가능 여부를 제어하는 것은 아닙니다. 위임할 수 있는지 여부 자체를 결정하는 것은 서브 에이전트(Sub-agent) 정의 측의 tools 란에 Agent가 있는지 여부입니다 (여기서 생략하면, 해당 에이전트는 손자 에이전트를 기동할 수 없습니다).
서브 에이전트는 메인 대화(컨텍스트, Context)를 인계받지 않습니다. 따라서 플로우에는 "각 에이전트에게 설계서 경로·대상 범위·담당 구체적 스텝을 매번 명시적으로 전달한다"라는 규칙이 있습니다. 실제 지시는 예를 들어 다음과 같은 형태가 됩니다 (형식은 실제 운용되는 것, 내용은 샘플).
당신은 backend-implementer입니다. 다음을 구현해 주세요.
- 설계서: .claude/workspace/TICKET-123/orchestration.md (가장 먼저 읽을 것)
- 대상 범위: 신청 API 신설 (POST /applications).
...
'반환하는 것'을 제한하는 이유는 앞서 언급한 바와 같이 메인 컨텍스트를 보호하기 위해서입니다. 이 문구를 지휘자가 Agent 툴의 prompt에 그대로 전달하여 서브 에이전트를 기동하는 것——그것이 '위임'의 실체입니다.
플로우 전체는 3단계 구성입니다. 그림 중의 '배리어(Barrier)'는 그때까지의 작업이 모두 갖춰질 때까지 다음으로 진행할 수 없는 동기화 포인트(Synchronization point)를 가리킵니다.
(색상 구분: 노랑=인간의 확인 게이트 / 청록=서브 에이전트의 작업 / 파랑=지휘자가 다루는 공정 / 보라=학습 계열. 👤 게이트는 그림에 상시 플로우의 2곳만 그려져 있으며, 나머지 3곳 — 중단 시·P0/P1 잔류 판단 시·Contract 변경 시 — 는 예외 분기로 등장합니다)
설계서를 읽고, 워크스페이스를 정비하고, 그리고 **공유 패키지의 타입(Type)·API Contract·DB 스키마를 여기서 동결(Freeze)**합니다. 공유물을 확정한 후, 전체 계획(페이즈 순서·병렬 트랙·기동할 에이전트)을 사용자에게 제시하고 시작 신호를 기다립니다.
Contract의 동결이 다음 페이즈 병렬화의 전제 조건입니다. 이곳을 확정하지 않고 BE/FE를 병렬로 실행하면, 나중에 타입이 바뀌어 FE가 통째로 재작업(Retake)하게 됩니다.
Contract 확정 후, BE와 FE는 서로 독립적입니다 (FE는 Contract의 타입에만 의존하며, BE의 내부 구현에는 의존하지 않습니다). 거기서 2개의 트랙을 병렬로 진행합니다. 각 트랙 내부에서는 "구현 → 3관점 리뷰 → 수정 → 유닛 테스트"를 순차적으로 흘려보내며, 동일한 종류의 공정은 하나로 묶어 동시에 기동합니다 (리뷰는 최대 BE3 + FE3 = 6체 동시).
트랙 내부가 직렬인 이유는 동일한 파일을 건드리기 때문이고, 트랙 간이 병렬인 이유는 디렉토리가 나누어져 있기 때문입니다. 이 판단은 빠른 참조표로서 스킬에 고정되어 있습니다 (발췌).
| 공정 | 병렬/직렬 | 근거 |
|---|---|---|
| 공유 Contract·DB 스키마 확정 | 직렬 (배리어) | FE/BE 양측의 전제. 경합하기 쉬우므로 단독 확정 |
| BE 구현 ↔ FE 구현 | 병렬 | FE는 Contract 타입에만 의존. 별도 디렉토리 |
| 리뷰 (BE3+FE3 관점) | 병렬 | 읽기 전용·부작용(Side effect) 없음 |
| 수정 루프 | 트랙 내부는 직렬 | 동일 파일 편집의 경합 회피 |
| 최종 게이트 | 직렬 (배리어) | 모든 트랙이 끝난 후, 앱 횡단 디그레션(Degradation)을 감지 |
"헷갈리면 직렬로 처리한다(안전 우선)"라는 규칙도 포함되어 있습니다.
양쪽 트랙이 모두 완료되면, 변경하지 않은 앱을 포함하여 모든 앱의 typecheck와 유닛 테스트를 실행합니다. 이번에 건드리지 않은 앱을 생략하지 않는 이유는, 공유 패키지를 통해 다른 앱의 타입이 깨지거나 기존 기능이 망가지는 것(디그레션)을 감지하기 위해서입니다. 하나라도 실패하면 PR로 진행하지 않고, 해당 implementer에게 되돌려 보냅니다.
게이트를 통과하면, 운용 메트릭(Metric) 기록과 회고(Retrospective, 학습 반영)를 수행하고, 사용자의 승인을 얻은 후 commit / PR을 생성합니다. 이 회고가 환경을 학습시키는 메커니즘의 입구인데, 그것은 제3회의 테마입니다.
이 플로우 정의를 읽어보면 곳곳에 묘하게 구체적인 주의사항이 있습니다. 예를 들어:
- 「공유 패키지의 Contract를 변경했다면 반드시 다시 빌드할 것. 오래된 dist 상태라면 백엔드가 기동 시 크래시(crash)되는 기지의 사고(known issue) 있음」 - 「Phase 1 도중에 Contract 변경이 필요해지면 Phase 0으로 돌아가 확정하고 다시 수행하며, FE 트랙으로 재동기화한다 (재작업(rework) 내용을 사용자에게 공유한다)"
이것들은 전부 실제로 겪었던 사고들입니다. 에이전트가 실수를 할 때마다, 같은 실수가 반복되지 않도록 플로우 정의(flow definition) 측에 영구적인 수정을 넣습니다. 하네스 엔지니어링(harness engineering)의 기본 동작을 플로우 정의 파일에 대해 지속해 온 결과가 바로 이 '묘한 구체성'입니다.
이 부분이 본 기사에서 가장 전달하고 싶은 내용입니다. 이 장에서는 리뷰와 수렴 판정을 담당하는 검증 메커니즘 전체를 **Verifier (평가기)**라고 부릅니다.
AI에게 리뷰와 수정 루프를 돌리게 할 때, 최대의 사고는 '작동하지 않는 것'이 아닙니다. 수렴하지 않는 루프와, 수렴한 척하는 것입니다. 수정이 또 다른 문제를 낳고, 그것을 고치면 원래 문제가 재발합니다. 혹은 3회 정도 돌린 끝에 "대체로 대응 완료되었습니다"라고 보고해 옵니다. 방치하면 토큰만 낭비되고 품질은 올라가지 않습니다.
그래서 리뷰 수정 루프에는 기준이 아닌 강제 규칙으로서 수렴 조건을 정의하고 있습니다.
① 상한 3회의 하드 리미트(hard limit). 회차는 횟수로 계산합니다 (주 N = N번째 반려 수정 + N+1번째 리뷰. 예를 들어 주 1은 '1번째 수정과 그 확인을 위한 2번째 리뷰'까지를 의미합니다). 3회 내에 P0/P1이 사라지지 않으면 계속하지 않고, 남은 지적 리스트를 첨부하여 사용자에게 에스컬레이션(escalation)합니다.
② 지적 대장. 각 회차의 종료 시점에 모든 지적 사항을 연번 ID·관점·중요도·상태(open/fixed/wontfix)의 대장으로서 worklog에 기록합니다. 재리뷰 시에는 이전 회차의 대장을 에이전트에게 전달하여, '같은 지적인지 아니면 다른 지적인지'를 ID로 판정합니다. 대장이 없으면 표현만 바뀌었을 뿐인 동일한 지적을 '새로운 지적'으로 간주하게 되어 수렴 판정을 할 수 없습니다.
실제 대장은 다음과 같은 형태입니다 (워크로그에서 발췌·마스킹 완료).
### 지적 대장 (주 1·연번 ID/관점/중요도/상태)
- BE-P0-1 [security] 메일 확인 API가 토큰 내의 사용자와 URL 측의 계정을
대조하지 않아, 타인의 계정을 확인할 수 있음. open → 수정 필요
...
③ 정체 감지. 이전 회차보다 P0/P1의 잔여 수가 줄어들지 않았다면, 상한에 도달하기 전이라도 즉시 에스컬레이션합니다. 같은 접근 방식의 반복은 해결책이 되지 않습니다.
④ 진동 감지. 동일 지적(대장 ID로 판정)이 2회 연속 남거나, 수정이 A↔B 사이를 왕복(한쪽을 고치면 다른 쪽이 망가짐)하게 되면 '진동'으로 간주하고 그 자리에서 중단합니다.
⑤ 우회로 봉쇄. 중단을 "대체로 대응 완료", "실용상 문제 없음" 등으로 말을 바꾸어 완료 보고하는 것을 금지합니다. 미결된 P0/P1은 known-issues에 기록한 후 사용자의 판단을 구합니다. P1을 남겨둔 채 앞으로 나아갈 판단을 할 수 있는 것은 사용자뿐이며, 지휘자(AI)의 독단은 허용하지 않습니다. 덧붙이자면, 중요도 강등(P1→P2) 또한 사용자의 승인 사항입니다. 강등은 문제를 묵인하는 온상이 되기 때문입니다.
⑤번이 기묘해 보일 수도 있지만, 실운용에서는 가장 중요했습니다. LLM에는 "완료라고 보고하고 싶어 하는" 편향(bias)이 있습니다. 규칙은 성선설을 바탕으로 작성해서는 안 됩니다. "~를 금지"할 뿐만 아니라 "~라는 말바꾸기를 금지"하기까지 작성해야 비로소 규칙으로서 기능합니다.
여기까지는 필자의 팀 이야기였습니다. 그렇다고 해도 이 패턴 자체가 저희 모노레포(monorepo) 전용인 것은 아닙니다. 자신의 업무에 적용한다면 어떻게 될지, 절차로 분해해 보겠습니다.
orchestrate의 입력은 템플릿에 따른 설계서 1장입니다. 장 구성은 다음과 같습니다.
# 오케스트레이션 설계서: TICKET-123 {제목}
## 1. 목표 / 배경
## 2. 대상 범위 (Scope) ← 어떤 패키지·앱을 다룰 것인가
...
이 설계서는 §1의 5개 파일과는 별개의 입력용 문서로, 워크스페이스 내(.claude/workspace/{브랜치명}/orchestration.md) 또는 설계서 보관 장소(docs/plans/)에 두고 경로를 전달하여 실행합니다. 완성 조건은 실행 시 overview.md로 전개됩니다.
작성할 때 가장 중요한 것은 "2. 대상 범위"와 "3. 대상 외"입니다. 이곳이 에이전트(Agent)에 대한 지시의 경계가 됩니다. 대상 외 범위를 명시하지 않으면, 에이전트는 "하는 김에 이것도 고쳐두었습니다"라는 행동을 합니다. 선의에 의한 스코프(Scope) 외 구현은 리뷰 비용을 조용히 불리는 사고입니다.
자신의 태스크를 루프(Loop) 워크플로우에 녹여낼 때의 순서입니다.
Step 1: 공정을 "직렬 필수"와 "병렬 가능"으로 나눈다. 판단 기준은 두 가지만 있습니다. 동일한 파일이나 결과물을 만지는가. 이전 공정의 확정이 전제되어 있는가. 둘 다 'No'라면 병렬로 진행할 수 있습니다. 병렬화 전에 "동결해야 할 공유물"(타입, 스키마, 규약, 용어집)을 특정하는 것이 요령입니다.
Step 2: 각 공정을 "구현계"와 "검증계" 에이전트에 할당한다. 검증계는 관점을 하나로 좁히면 정밀도가 올라갑니다. "전부 봐줘"는 "아무것도 보지 마"와 거의 동의어입니다.
Step 3: 인간의 확인 게이트(Gate)를 둘 위치를 결정한다. 필자의 팀에서는 전 장의 수렴 규칙(5개 항목)과는 별개로, 확인 게이트를 5곳에 고정하고 있습니다. ①착수 전(전체 계획 제시 후) ②리뷰 수정 루프의 종료 시점 ③P0/P1을 남겨두고 진행할 판단이 필요할 때 ④동결했을 터인 공유물에 변경이 필요해졌을 때 ⑤commit/PR 전. 역으로 말하면, 이 외에는 AI의 판단에 따라 연속 실행을 허용하고 있습니다. 게이트를 좁히기 때문에 자동화가 돌아가고, 게이트가 있기 때문에 안심하고 맡길 수 있습니다. 두 가지 모두 필요합니다.
Step 4: 루프의 "멈추는 방식"을 먼저 설계한다. 상한 반복 횟수, 정체·진동의 정의, 에스컬레이션(Escalation) 대상. 전 장에서 언급했듯이, 이곳을 설계하지 않은 루프는 사고로 이어집니다. 돌리는 방법보다 멈추는 방법이 우선입니다.
개발 이외에도 동일한 형식을 사용할 수 있습니다. 예를 들어 블로그 기사 작성이라면 "구성안 동결(Phase 0) → 본문 집필 ∥ 팩트 체크(Phase 1) → 퇴고 리뷰 → 수정 → 공개 전 체크리스트(Phase 2)"라는 동일한 형태의 루프를 구성할 수 있습니다. 솔직히 고백하자면, 이 시리즈 자체도 거의 이 형식을 따라 만들고 있습니다. 구성안을 확정한 후 집필하고, 페르소나가 다른 리뷰 에이전트를 병렬로 실행하여 지적 사항을 반영했습니다.
트랙의 병렬과는 별개로, 브랜치 자체의 병렬도 운용하고 있습니다. orchestrate를 --worktree 플래그와 함께 실행하면, git worktree(하나의 리포지토리에서 여러 작업 디렉토리를 병행하여 가질 수 있는 Git 표준 기능)로 별도의 작업 트리를 만들고, slot 번호를 할당하여 환경별로 분리합니다.
분리하는 대상은 세 가지 충돌입니다. ①파일 충돌(worktree로 별도 디렉토리) ②포트 충돌(slot × 100 오프셋) ③실행 환경 충돌(Docker Compose의 프로젝트 이름과 DB 볼륨을 slot별로 구분). 또한 실행 시 본체(로컬 개발 환경)의 DB를 pg_dump | pg_restore로 복제하므로, 시드(Seed) 투입 없이 평소 개발 DB와 동일한 데이터 상태로 병행 작업에 들어갈 수 있습니다.
이를 통해 "브랜치 A에서 orchestrate를 돌리면서 브랜치 B의 동작 확인을 하는 것"이 한 대의 머신에서 가능해집니다. 상세 내용은 별도 기사로 다룰 예정이므로 여기서는 개요만 설명하겠습니다.
지휘자 패턴의 본질은 한 문장으로 요약할 수 있습니다. 높은 성능의 모델은 "분해"와 "검수"에만 사용하고, 작업은 위임한다.
솔직히 말씀드리면, 이 체제는 저렴하지 않습니다. 리뷰에만 상위 모델 에이전트가 최대 6개, 수정 루프는 최대 3회까지 돌아갑니다. 컨텍스트 격리로 비용을 억제하고는 있지만, 상위 모델을 전제로 한 설계이기에 저가형 모델로 교체하면 "말바꾸기 금지"와 같은 메타 룰(Meta-rule) 준수나 리뷰 정밀도부터 저하됩니다. 도입 시에는 우선 한 가지 태스크를 흘려보내며 자신들의 예산 규모와 대조해 보시는 것을 추천합니다.
도입 시 체크리스트를 남겨둡니다.
- 메인 세션의 역할을 6개(파악·지시·통합·기록·게이트·분기)로 제한하고 있는가
- 병렬화 전에 "동결해야 할 공유물"을 특정했는가
- 리뷰 에이전트는 관점을 하나로 좁히고 있는가 (수정은 시키지 않고 지적만 하게 하고 있는가)
- 루프의 상한·정체·진동·에스컬레이션을 정의했는가
- "대체로 대응 완료"와 같은 말바꾸기 완료 보고를 명문으로 금지했는가
- 진행 상황을 세션 외의 문서에 매 스텝 기록해 두고 있는가

orchestrate 실행 중인 모습(재구성 이미지). Phase 0에서 공유물을 동결하고, Phase 1에서 구현·리뷰 워커가 병렬로 기동한다
자, 이 흐름의 Phase 2에는 「retrospective (회고/학습 반영)」라는 단계가 있었습니다. 리뷰에서 나온 지적 사항은 해당 태스크에서 수정하고 끝내는 것이 아닙니다. 다음 태스크에서 동일한 지적이 나오지 않도록, 환경(environment) 측으로 다시 쓰여집니다(write-back). 다음번에는 이 자기 학습 루프(self-learning loop)의 구현 — 추가 전용 로그, 빈번한 위반 랭킹, 예방적 DoD (Definition of Done), 실측 메트릭스 — 에 대해 자세히 살펴보겠습니다.
-
Loop Engineering 입문 (suwash)
-
Loop Engineering이란 — #Harness Engineering (Qiita)
-
엔지니어의 Agent Loop를 정비하는 기술 (karamage)
-
Claude Code로 Harness Engineering을 실천하기 (sasadango28)
Addy Osmani의 「Loop Engineering」(https://addyo.substack.com/p/loop-engineering) 내에서 인용된 인터뷰 발언. ↩
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기