Loops & Graphs
Hanako · “Loops and Graphs” 실무 가이드

에이전트 감시는 그만.
마지막 한 단계만
승인한다.

중간 결과를 사람이 하나하나 검토하지 않아요. 품질은 실패할 수 있는 체크(Loop)와 작업 구조(Graph)가 맡고, 사람은 되돌리기 가장 어렵고 영향이 가장 큰 한 단계에만 들어가요.

↓ 스크롤

01 · Loop

Loop는
실패할 수 있는 체크예요.

생성하고, 체크하고, 고치고, 체크가 GREEN이 될 때까지 반복해요. 핵심은 체크를 작업보다 먼저 쓰는 것이에요. 프로그램이 판정할 수 있어야 해요.

생성produce 체크check 수정correct 반복repeat 현재 체크 대기

$ npm test → 대기

GREEN · 체크다

프로그램이 판정해요

  • ✓테스트 스위트가 exit 0
  • ✓모든 주장에 출처(파일:라인)가 붙어 있음
  • ✓diff가 계획에 적힌 파일만 건드림
NOT A CHECK · 체크가 아니다

느낌이에요

  • ✕“결과가 괜찮아 보인다”
  • ✕“모델이 자신 있다고 한다”
  • ✕“에러가 안 났다”: 에러가 없다고 정답은 아니에요
  • ✕다른 모델에게 “검토해줘”만 시키기: 낙관론자 둘의 합의일 뿐이에요

02 · Graph

“그리고 나서”는
엣지가 아니에요.

Graph는 어떤 작업 단위가 있고 어떻게 연결되는지를 정해요. 노드는 입력 하나, 출력 하나인 제한된 작업이에요. 엣지는 이 노드의 출력이 저 노드의 입력으로 실제로 들어갈 때만 있어요.

소요 시간
워커 3개가 차례로 돌아요: 3 단위 시간
“넘어가는 변수의 이름을
댈 수 있나요?”

화살표마다 물어보세요. 다음 단계가 이전 단계의 출력을 실제로 읽나요?
넘어가는 변수를 이름으로 댈 수 없으면 엣지가 없는 거예요. 그 둘은 병렬로 돌리면 돼요.

03 · 노드 4종

모든 파이프라인은
네 가지 노드로 그려요.

Splitter

분할

맨 앞에서 작업을 잘라요. 가장 중요한 결정이에요. 폴더 기준이 아니라 영향 범위(blast radius) 기준으로 잘라요.

Worker

작업자

단위 하나, 관점 하나, 독립된 컨텍스트. 컨텍스트를 공유시키면 결과가 한쪽으로 수렴해서 4번 비용을 내고 의견 1개를 얻어요.

Code node

코드

병합, 정렬, 중복 제거, 전후 비교처럼 정답이 하나인 변환은 모델이 아니라 코드가 해요.

Gate

관문

결과를 통과시키거나 만든 단계로 되돌려요. 여는 기준은 자신감이 아니라 영향 범위예요.

🧪
코드 노드 판별법

그 단계를 “판단 / 결정 / 평가 / 요약” 같은 단어 없이 설명할 수 있으면, 모델이 아니라 코드로 만들어요.

워커마다 컨텍스트를 따로 줘요

같은 대화 안에서 서브태스크를 돌리지 말고, 서브에이전트를 각각 띄우세요.

Worker Actx A
Worker Bctx B
Worker Cctx C
Worker Dctx D

04 · 원칙

Loop는 노드 안에.
Graph는 노드 사이에.

각 노드는 안에서 자기 체크가 GREEN이 될 때까지 혼자 돌아요. 노드끼리는 실제로 넘어가는 출력으로만 이어져요.

loop Worker A loop Merge (code) loop Gate

초록 호 = 노드 안의 loop · 파란 점선 = 노드 사이의 graph 엣지

05 · 되돌림 경로

되돌아가는 길은
두 개예요.

대부분은 짧은 길만 만들어요. 긴 길이 있어야 같은 실수가 다음 실행에서 다시 안 나와요.

Splitter브리프 Worker단위 생성 Gate통과/반려 Accepted통과 결과 correction edge · 이번 실행을 고침 learning edge · 이후 모든 실행을 고침
짧은 길 · Correction edge

실패한 단위를 만든 단계로

게이트가 실패한 단위를 그 단위를 만든 단계로 돌려보내요. 이번 실행을 고쳐요.

긴 길 · Learning edge

통과 결과에서 뽑은 제약을 splitter로

통과된 결과에서 제약 조건을 뽑아 splitter의 브리프에 넣어요. 이후 모든 실행을 고쳐요. 대부분 이걸 빼먹어요.

ACCEPTED utils slice ported, green on first pass DERIVED adapters preserve keyword args exactly LANDS IN the splitter's brief for every later slice

Claude Code에서는 이 DERIVED 한 줄을 CLAUDE.md의 “Learned constraints”에 쌓으면 돼요.

06 · 단위 반환

배치 말고,
실패한 단위만 돌려보내요.

4개 중 1개가 실패했으면 그 1개만 돌려보내요. 전체를 돌려보내면 멀쩡했던 3개가 “다르게” 다시 써지고, 결과가 수렴하지 않아요.

utils slice 1
→
handlers slice 2
GATE
adapters slice 3
→
models slice 4
→
handlers 재시도 0 / 3

돌려보낼 때는 다섯 줄을 같이 보내요

UNIT      handlers slice
VERDICT   red
REASON    test_auth_redirect failed
EVIDENCE  expected 302, got 200, handlers/auth.py:88
SCOPE     fix this file only, do not touch other slices
SCOPE가 없으면

수정 범위가 번져요

결국 아무도 리뷰하지 않은 거대한 diff가 돼요.

최대 3회

세 번 실패하면 계획 문제예요

단위 문제가 아니라 분할(splitter)이 잘못된 거예요. 사람에게 올려요.

07 · 게이트

게이트는 자신감이 아니라
영향 범위로 열어요.

모델 점수가 아무리 높아도, 되돌리기 어려운 작업은 자동으로 통과시키지 않아요.

OPEN

되돌리기 쉽고 국소적

자동 통과해도 돼요.

문구 변경 · 테스트 · 커버리지 있는 독립 함수

GATED

되돌리기 쉽지만 넓음

결정적 체크 통과와 깔끔한 실행 이력이 있을 때만 통과해요.

공용 유틸 · 스키마 추가 · 호출처 많은 코드

🔒
CLOSED

되돌리기 어려움

절대 자동 통과하지 않아요. 점수와 상관없이 사람이 승인해요.

마이그레이션 · 삭제 · 프로덕션 데이터 · 돈 이동

게이트가 믿는 근거, 우선순위 순

1
결정적 결과 (테스트 등)
2
이번 실행 경로
3
이 노드의 과거 롤백 빈도
4
모델 자기평가 (마지막)

08 · 실무 키트

복사해서
바로 쓰세요.

Claude Code 같은 코딩 에이전트에 그대로 붙여 넣는 블록 3개와, 지금 돌리는 파이프라인을 점검하는 체크리스트예요.

CLAUDE.md 규칙 블록

프로젝트 루트 CLAUDE.md나 ~/.claude/CLAUDE.md에 붙여 넣어요.

## 에이전트 작업 규칙 (Loop + Graph)
목표: 나는 중간 결과를 검토하지 않는다. 되돌리기 가장 어렵고 영향이 가장 큰 한 단계만 승인한다.

1. 체크 먼저
   - 작업 시작 전, 프로그램이 판정할 수 있는 완료 조건(GREEN 목록)을 먼저 써서 보여줄 것.
     예) 테스트 exit 0 / 모든 주장에 파일:라인 출처 / diff가 계획에 적힌 파일만 변경
   - "괜찮아 보임", "자신 있음", "에러 없음", "다른 모델이 검토함"은 체크가 아니다.
   - GREEN이 될 때까지 생성 → 체크 → 수정을 반복한다.

2. 엣지는 실제 데이터 흐름만
   - 단계 사이 화살표마다 "넘어가는 변수"의 이름을 댈 수 있는지 확인한다.
   - 이름을 댈 수 없으면 엣지가 아니다 → 병렬로 실행한다.
   - 병렬 작업은 서브에이전트로, 각자 독립된 컨텍스트에서 돌린다.

3. 코드로 할 일은 코드로
   - 병합·정렬·중복 제거·전후 비교처럼 정답이 하나인 변환은 모델 대신 스크립트로 처리한다.
   - "판단/결정/평가/요약" 없이 설명되는 단계는 코드다.

4. 분할은 blast radius 기준
   - 폴더가 아니라 영향 범위 기준으로 작업을 자른다.

5. 실패한 단위만 되돌린다
   - 배치 전체를 다시 쓰지 말고, 실패한 단위만 아래 형식으로 재시도한다.
     UNIT / VERDICT / REASON / EVIDENCE / SCOPE
   - SCOPE 밖의 파일은 건드리지 않는다.
   - 최대 3회. 3번 실패하면 멈추고 분할 계획을 다시 제안한 뒤 나에게 보고한다.

6. 게이트는 영향 범위로
   - 되돌리기 쉽고 국소적 (문구, 테스트, 커버리지 있는 독립 함수) → 자동 진행
   - 되돌리기 쉽지만 넓음 (공용 유틸, 스키마 추가, 호출처 많은 코드) → 결정적 체크 통과 + 깔끔한 실행 이력일 때만
   - 되돌리기 어려움 (마이그레이션, 삭제, 프로덕션 데이터, 돈 이동) → 점수와 무관하게 실행 전 멈추고 승인 요청
   - 판단 근거 우선순위: 결정적 결과 → 이번 실행 경로 → 과거 롤백 빈도 → 자기평가(마지막)

7. 배운 것은 남긴다
   - 통과된 결과에서 확정된 제약은 아래 "Learned constraints"에 한 줄씩 추가하고, 이후 작업 분할 시 반드시 반영한다.

## Learned constraints
- (예) adapters는 keyword args를 정확히 보존한다

작업 시작 프롬프트

새 작업을 맡길 때 첫 메시지로 보내요. 에이전트가 GREEN 조건과 그래프부터 그리게 해요.

작업: <여기에 할 일>

코드를 쓰기 전에 아래 5가지를 먼저 보여줘. 내가 확인하면 시작해.

1. GREEN 조건
   프로그램이 판정할 수 있는 완료 조건 3~5개.
   (예: `npm test` exit 0 / diff가 아래 파일 목록만 변경 / 모든 주장에 파일:라인 출처)
   "괜찮아 보임", "에러 없음" 같은 건 쓰지 마.

2. 분할 (Splitter)
   작업 단위 목록. 폴더가 아니라 blast radius 기준으로 나누고,
   각 단위에 [국소 / 넓음 / 되돌리기 어려움] 표시.

3. 엣지
   단위 사이 화살표마다 넘어가는 변수 이름.
   이름이 없으면 "병렬"로 표시하고 서브에이전트로 따로 돌릴 것.

4. 코드 노드
   병합·정렬·중복 제거·비교처럼 스크립트로 처리할 단계.

5. 승인 지점
   내가 승인해야 하는 단 하나의 단계 (되돌리기 가장 어렵고 영향이 가장 큰 것).
   그 외 단계는 GREEN이면 묻지 말고 진행.

반려 / 재시도 템플릿

에이전트 결과가 실패했을 때 그대로 채워서 보내요. 서브에이전트에게 지시할 때도 같아요.

UNIT      <실패한 단위 하나. 예: handlers slice>
VERDICT   red
REASON    <실패한 체크. 예: test_auth_redirect failed>
EVIDENCE  <기대값 vs 실제값, 파일:라인. 예: expected 302, got 200, handlers/auth.py:88>
SCOPE     이 파일만 수정할 것. 다른 단위는 건드리지 말 것.
ATTEMPT   <n> / 3

규칙: 3회째도 실패하면 더 고치지 말고 멈춰.
대신 분할 계획의 어디가 잘못됐는지 정리해서 보고해줘.
통과하면 이번 수정에서 확정된 제약을 한 줄로 뽑아서 CLAUDE.md "Learned constraints"에 추가해줘.

지금 파이프라인 점검

체크 상태는 이 브라우저에 저장돼요.

0 / 0

    09 · 적용 순서

    내일 아침,
    이 순서로 시작하세요.

    반복하는 작업 하나를 골라 splitter, 레인, merge, 게이트 하나, 되돌림 엣지 하나를 그려요. 그다음 이 순서로 만들어요.

    1

    게이트 먼저

    무엇이 GREEN인지, 어떤 레인은 자동이고 어떤 레인은 사람이 보는지부터 정해요.

    2

    레인 나누기

    blast radius 기준으로 자르고, 넘어가는 변수가 없는 단계는 병렬 레인으로 분리해요.

    3

    learning edge는 마지막

    통과된 결과가 쌓여야 제약을 뽑을 수 있어요. 쌓이면 splitter 브리프(CLAUDE.md)에 넣어요.

    4

    사람은 한 지점에만

    merge 승인, 또는 어떤 수정을 배포할지 고르는 것. 그거 하나만 해요.

    체크를 먼저 쓰세요.

    넘어가는 변수가 없으면, 엣지도 없어요.

    사람은 마지막 한 단계만.

    복사했어요