AI 서비스 엔지니어링: Track A
7주차 · 멀티 에이전트 패턴
CodeCompose · 2026-09-04
시연 저장소 셋
따라 하지 않아도 됩니다. 화면으로 함께 봅니다
git clone https://github.com/2026-ai-service-engineering-a/week07-energy-agent.git
git clone https://github.com/2026-ai-service-engineering-a/week07-support-agent.git
git clone https://github.com/2026-ai-service-engineering-a/week07-coding-agent.git- 각 저장소는
docker compose up --build -d로 뜹니다. - 시연은 각 저장소의
demos/스크립트와 대시보드로 진행합니다. - 이 덱의 실행 결과는 같은 코드로 2026-08에 실제로 돌린 실측입니다.
신호 ①: 도구 선택 품질
5주차에서 이미 체감한 현상입니다
- 5주차의 규율: 좁게 준다. 목록이 길수록 선택 품질이 떨어집니다.
10_tool_selection.py에서 같은 10개 도구를 이름만 바꿔 등록했을 때 선택이 갈리는 것을 봤습니다.- 역할마다 필요한 도구만 쥐여 주면, 목록은 저절로 짧아집니다. 볼 수 없는 도구는 잘못 부를 수도 없습니다.
flowchart LR
subgraph ONE["도구 10개를 한 손에"]
A["에이전트"] --> t1["조회"] & t2["계산"] & t3["차트"] & t4["검색"] & t5["…6개 더"]
end
subgraph TWO["역할마다 필요한 만큼만"]
B["analyst"] --> u1["조회 4종"]
C["visualizer"] --> u2["make_chart"]
end
ONE -->|"나누면"| TWO
style A stroke:#d0453f
style B stroke:#0ca30c
style C stroke:#0ca30c신호 ③: 컨텍스트 팽창, 그리고 오염
6주차의 우상향 계단을 회수합니다
- 6주차 실측: 첫 스텝 810토큰이 여섯 스텝 만에 1,552토큰. 합계 7,400토큰 중 대부분이 같은 내용의 재전송이었습니다.
- 역할이 섞이면 거기에 오염이 얹힙니다. 분석용 원자료가 상담 단계까지 따라와, 뒤 작업이 앞 작업의 찌꺼기를 계속 실어 나릅니다.
flowchart LR
s1["스텝 1<br/>810tk"] --> s2["스텝 2<br/>1,116tk"] --> s3["…"] --> s6["스텝 6<br/>1,552tk"]
raw["분석 원자료"] -.->|"상담 단계까지 따라온다 (오염)"| s6
style raw stroke:#d0453f대가 셋
- 왕복이 늘어납니다. 에이전트 사이를 오갈 때마다 호출이 더해지고, 지연과 비용도 함께 늘어납니다.
- 상태 전달을 설계해야 합니다. 전부 넘기면 오염이 따라가고, 요약해서 넘기면 정보가 샙니다. 무엇을 넘길지가 곧 설계입니다.
- 라우팅이라는 새 실패 모드가 생깁니다. 도구를 잘못 고르면 결과가 이상해지지만, 일을 엉뚱한 에이전트에게 보내면 그럴듯한 답이 엉뚱한 근거 위에 세워집니다.
flowchart TB
S["나눈다"] --> a["왕복 증가<br/>호출 3회 → 5회"]
S --> b["상태 전달 설계<br/>전부? 요약만?"]
S --> c["라우팅 실수<br/>새 실패 모드"]supervisor와 handoff
flowchart LR
subgraph S["supervisor · 중앙이 조율한다"]
direction TB
U1(("사용자")) --> SV["supervisor"]
SV --> W1["분석 에이전트"]
SV --> W2["시각화 에이전트"]
W1 --> SV
W2 --> SV
SV --> U1
end
subgraph H["handoff · 제어권이 넘어간다"]
direction TB
U2(("사용자")) --> C["분류 에이전트"]
C -->|"이양"| B1["요금 에이전트"]
B1 -->|"이양"| B2["해지방어 에이전트"]
B2 --> U2
end
S ~~~ H코드 포인트: 그래프 선언
graph = StateGraph(State)
graph.add_node("supervisor", supervisor) # 노드 = 함수
graph.add_node("analyst", analyst)
graph.add_edge("analyst", "supervisor") # 일이 끝나면 중앙으로
graph.add_conditional_edges( # 분기는 조건부 엣지
"supervisor", route, ["analyst", "counselor", END])
app = graph.compile()
result = app.invoke({"question": "지난달 요금이 왜 이렇게 나왔나요?"})- 노드는 정하고, 엣지는 나른다.
- 6주차 루프의
if와for가 엣지 선언으로 옮겨 왔을 뿐입니다.
선언한 그래프는 스스로 그린다
print(app.get_graph().draw_mermaid()) 한 줄이면 그래프가 자기 그림을 내놓습니다
flowchart TD
S(["__start__"]) --> sup["supervisor"]
analyst["analyst"] -->|"add_edge"| sup
sup -.->|"route"| analyst
sup -.->|"route"| counselor["counselor"]
sup -.->|"route"| E(["__end__"])- 위 선언과 1:1입니다. 실선은 고정 엣지, 점선은 조건부 엣지.
- 문서용 그림을 따로 그려서 코드와 어긋나는 일이 없습니다. 그래프가 곧 그림이고, 그림이 곧 코드입니다.
시스템 구조: 컨테이너 셋에 볼륨 하나
flowchart LR
B["브라우저"] -->|":8501"| UI["ui<br/>상담 대시보드"]
UI --> APP["app<br/>FastAPI + LangGraph"]
APP --> DB[("db · PostgreSQL<br/>고객 3 × 24개월")]
APP -->|"completion"| LLM["LLM API<br/>(litellm)"]
APP -.->|"차트 png"| M[("media 볼륨")]
UI -.->|"바이트로 중계"| M- 4주차에서 익힌 compose 구성 그대로입니다. 새것은
media볼륨 하나 - LLM 호출은 전부 litellm입니다. 5주차의 그 한 줄입니다.
Part 2. v0.2 · supervisor로 나눈다
graph TD;
__start__([__start__]):::first
supervisor(supervisor)
analyst(analyst)
visualizer(visualizer)
counselor(counselor)
__end__([__end__]):::last
__start__ --> supervisor;
analyst --> supervisor;
counselor --> supervisor;
supervisor -.-> __end__;
supervisor -.-> analyst;
supervisor -.-> counselor;
supervisor -.-> visualizer;
visualizer --> supervisor;
classDef default fill:#f2f0ff,line-height:1.2
classDef first fill-opacity:0
classDef last fill:#bfb6fc모든 실선이 supervisor로 돌아옵니다. 하위 에이전트는 서로를 부르지 않습니다.
supervisor는 에이전트가 아니라 라우터다
# supervisor가 모델에게 받는 것은 이 한 줄이 전부다
{"next": "analyst", "why": "요금 내역을 먼저 조회해야 한다"}- supervisor는 일을 하지 않습니다. 다음에 누가 일할지만 정합니다.
- 그래서 도구가 없고, 답변도 쓰지 않습니다.
graph.add_conditional_edges("supervisor", lambda state: state["route"],
["analyst", "visualizer", "counselor", END])6주차의 “도구를 부를까 답할까”가 “누구에게 보낼까”로 바뀌었을 뿐입니다.
서브 에이전트의 안쪽은 6주차의 그 루프다
def _run_with_tools(system, question, customer_id, tool_names, agent):
"""하위 에이전트 하나의 작은 루프. (요약, 원자료, 트레이스, 호출 수)."""
messages = [{"role": "system", "content": system},
{"role": "user", "content": question}]
for _ in range(MAX_TOOL_ROUNDS): # 상한 3왕복
response = completion(model=pick_model(), messages=messages,
tools=tool_schemas(tool_names))
message = response.choices[0].message.model_dump()
messages.append(message)
if not message.get("tool_calls"): # 종료: 요약이 나왔다
return message.get("content") or "", data, trace, calls
for call in message["tool_calls"]:
raw = run_tool(call["function"]["name"],
call["function"]["arguments"], customer_id)
messages.append({"role": "tool", "tool_call_id": call["id"],
"content": raw}) # (기록 코드는 생략)
return "(도구 왕복 한도 초과)", data, trace, calls- 6주차에 손으로 짠 ReAct 루프와 같은 뼈대입니다.
- 서브 에이전트 자리에 들어가는 것이 여러분이 6주차에 만든 그 에이전트입니다.
나눌 때 실제로 나누는 것 세 가지
- 지침: 역할마다 자기 문장만 이고 갑니다
- 도구: analyst는 조회 도구 넷, visualizer는
make_chart하나만 봅니다. 볼 수 없는 도구는 잘못 부를 수도 없습니다 - 문맥: 하위 에이전트는 요약(findings)만 위로 올립니다. 도구가 물어온 원자료(data)는 상태에 쌓이되 프롬프트에는 실리지 않습니다
이 저장소는 시연을 위해 서브 에이전트를 일부러 얇게 만들었습니다. 실제 제품에서는 각 노드가 도구 열 개와 자기 하네스를 지닙니다.
flowchart LR
ONE["한 덩어리<br/>지침 + 도구 + 문맥"] --> g1["지침<br/>자기 문장만"]
ONE --> g2["도구<br/>필요한 것만"]
ONE --> g3["문맥<br/>요약만 위로"]실측: 같은 질문, 두 구조
=== 지난달 요금이 왜 이렇게 많이 나왔나요? ===
[single] 에이전트 1 · 지침 1,105자 · 컨텍스트 2,640자 · LLM 호출 3회
advisor 도구: compare_usage
advisor 도구: bill_breakdown
advisor 답변 작성
[supervisor] 에이전트 4 · 지침 199자 · 컨텍스트 466자 · LLM 호출 5회
supervisor 라우팅 → analyst (규칙: 자료가 없으면 분석부터)
analyst 도구 3회 · 분석 요약
supervisor 라우팅 → counselor
counselor 답변 작성
supervisor 라우팅 → done 같은 질문에 경로가 달라진다
=== ① 라우팅을 전부 LLM에게 맡김 ===
최근 1년 추이를 그래프로 보여주세요
그래프 3/3회 · LLM 호출 9~12회
경로: analyst → visualizer → counselor → done
경로: analyst → visualizer → counselor → visualizer → done
제 계약전력이 몇 kW인가요?
그래프 0/3회 · LLM 호출 3~6회
경로: analyst → counselor → done
경로: counselor → done같은 질문, 같은 코드, 같은 데이터인데 경로가 갈립니다.
두 번째가 더 무섭다
- 그래프를 두 번 그린 실행: counselor가 답을 쓴 뒤에 visualizer를 한 번 더 불렀습니다. 호출이 9회에서 12회로
- analyst를 건너뛴 실행: supervisor가 곧장 counselor를 불렀습니다. counselor에게는 도구가 없습니다. 자료를 한 번도 조회하지 않은 채 상담문을 쓴 것입니다.
flowchart LR
S["supervisor"] -.->|"건너뜀"| A["analyst<br/>조회 도구 4종"]
S ==>|"직행"| C["counselor<br/>도구 없음"]
C --> X["조회 없는 상담문<br/>출력만 보면 그럴듯"]
style X stroke:#d0453f
style C stroke:#d0453fPart 4. v1.0 · 하이브리드 라우팅
def _rule_route(state):
if state.get("answer"): # 답이 나왔으면 끝이다
return "done", "규칙: 답변이 나왔다"
if "analyst" not in done_agents: # 자료 없이 할 수 있는 것은 없다
return "analyst", "규칙: 자료가 없으면 분석부터"
if wants_chart(state["question"]) and "visualizer" not in done_agents:
return "visualizer", "규칙: 그래프를 명시적으로 요청했다"
return None # 애매하면 LLM에게 묻는다- supervisor를 더 똑똑하게 만들지 않았습니다.
- 판단이 필요 없는 자리를 골라 코드로 확정했습니다.
차트의 숫자는 어디서 오는가
make_chart는 몇 개월치를 그릴지와 제목만 받습니다. 수치는 받지 않습니다.- 도구가 db에서 직접 조회해 그립니다.
- LLM이 옮겨 적은 숫자로 그리면 막대 높이가 원본과 어긋날 수 있고, 그것은 화면에서 확인할 방법이 없는 종류의 오류입니다.
- 4주차의 “원본 한 벌” 규율과 같은 이유입니다.
flowchart LR
M["make_chart(months, title)"] --> DB["db 직접 조회"] --> OK["막대 = 원본"]
L["LLM이 옮겨 적은 수치"] -.-> NG["어긋나도 모른다"]
style OK stroke:#0ca30c
style NG stroke:#d0453f컨테이너 넷
4주차의 rag 컨테이너가 돌아왔습니다
flowchart LR
B["브라우저"] -->|":8501"| UI["ui<br/>상담 채팅"]
UI --> APP["app<br/>FastAPI + LangGraph"]
APP -->|"고객·청구·장애·문서 원본"| DB[("db · PostgreSQL<br/>+ 대화 체크포인트")]
APP -->|"조항 top-k"| RAG[("rag · Chroma<br/>벡터 + doc_id")]
APP -->|"completion · embedding"| LLM["LLM API<br/>(litellm)"]4주차에서 검색은 제품 자체였습니다. 여기서는 담당 하나가 쓰는 도구입니다.
Part 2. v0.2 · 제어권이 실제로 넘어간다
graph TD;
__start__([__start__]):::first
entry(entry)
triage(triage)
billing(billing)
tech(tech)
retention(retention)
__end__([__end__]):::last
__start__ --> entry;
entry -.-> triage;
entry -.-> billing;
triage -.-> billing;
triage -.-> tech;
triage -.-> retention;
billing -.-> retention;
billing -.-> __end__;
retention -.-> __end__;
classDef default fill:#f2f0ff,line-height:1.2
classDef first fill-opacity:0
classDef last fill:#bfb6fcsupervisor 그림과 나란히 놓고 보십시오. 되돌아오는 화살표가 없습니다. 대신 담당끼리 옆으로 잇는 화살표가 있습니다.
Command가 무엇인가
# 지금까지: 상태만 돌려주고, 이동은 엣지가 정한다
def supervisor(state):
return {"route": "analyst"} # 엣지가 이 값을 읽는다
# Command: 상태 갱신과 이동을 한 번에 돌려준다
def triage(state):
return Command(goto="billing",
update={"current_agent": "billing"})
| 조건부 엣지 | Command | |
|---|---|---|
| 이동을 정하는 곳 | 그래프(엣지 함수) | 노드 자신 |
| 어울리는 구조 | 중앙이 다음을 정하는 supervisor | 각자가 다음을 정하는 handoff |
요금 담당이 해지방어에게 넘길 때, 그 결정을 아는 것은 요금 담당뿐입니다. 중앙에 물어보지 않고 자기가 옮깁니다.
이양은 도구 호출이다
if called in HANDOFF_TARGETS: # 여기서 제어권이 넘어간다
target = HANDOFF_TARGETS[called]
return Command(goto=target, update={
"current_agent": target,
"handoffs": [{"from": name, "to": target, "reason": reason}],
"came_from": name,
})- 모델이
transfer_to_billing을 부르면 코드가 이동으로 바꿉니다. - 인자는 이유 한 줄뿐입니다.
- 5주차의 문장 그대로: 에이전트가 세계를 바꾸는 통로는 도구 호출입니다.
함께 넘어가는 것, 남는 것
- 넘어가는 것은 대화 전체입니다. supervisor는 요약만 올렸지만, 여기서는 받는 쪽이 고객의 말을 직접 읽습니다. 요약하는 사람이 중간에 없기 때문입니다.
- 담당은 체크포인터에 남습니다. 이것이 없으면 handoff가 아니라 한 번의 우회일 뿐입니다.
def entry(state):
current = state.get("current_agent") or ""
if current in ("billing", "tech", "retention"):
return Command(goto=current) # 접수를 거치지 않는다
return Command(goto="triage") 실측: 같은 대화, 두 구조
=== v0.1 분류만 ===
[고객] 이번 달 요금이 왜… 받은 사람: 접수 상담원
[고객] 그래서 얼마나… 받은 사람: 접수 상담원
[고객] 그냥 해지할래요. 받은 사람: 접수 상담원
=== v0.2 handoff ===
[고객] 이번 달 요금이 왜… 받은 사람: 요금 담당
[고객] 그래서 얼마나… 받은 사람: 요금 담당
[고객] 그냥 해지할래요. 받은 사람: 해지방어 담당
이양 기록
접수 상담원 → 요금 담당 (요금 과다 청구 및 납부 관련 문의)
요금 담당 → 해지방어 담당 (고객이 해지를 요청하여 이관)- 두 번째 턴에서 접수를 다시 거치지 않은 것이 체크포인터의 몫
- 세 번째 턴에서 요금 담당이 직접 넘긴 것이 handoff의 몫
함정: 매 턴 상태를 통째로 보내면 이양이 지워진다
def new_turn(customer_id, customer_name, message):
"""이어지는 턴이 들고 오는 것은 고객이 방금 한 말뿐이다."""
return {"messages": [{"role": "user", "content": message}],
"customer_id": customer_id, "customer_name": customer_name,
"turn_handoffs": 0, "came_from": ""}- 개발 중 실제로 겪은 사고입니다. 습관처럼
current_agent: ""를 함께 보냈더니, 체크포인터의 담당을 덮어써 매 턴 접수부터 다시 시작했습니다. - 화면상으로는 잘 도는 것처럼 보였고, 트레이스를 세어야 보였습니다.
- 상태에 남길 것과 매 턴 새로 보낼 것을 나누는 일이 설계의 일부입니다.
핑퐁, 말로만 넘김, 경로 흔들림
=== ① 규칙 없이 (v0.2) ===
[복합 문의] 요금도 이상하고 인터넷도 안 돼요.
이양 0회 · 말로만 넘김 2/3 · 되물음 1/3
[이어지는 불만] 너무 비싸네요. 그냥 해지할래요.
이양 2~4회 · 핑퐁 1/3 · 경로 2종
경로: 접수 → 요금 → 해지방어 → 요금 → 해지방어
[분류 불가] 저기요, 좀 답답해서 전화드렸어요.
이양 0회 · 말로만 넘김 3/3- 말로만 넘김: 도구를 부르지 않고 “연결해 드리겠습니다”라고만. v0.1로 되돌아간 셈인데, 답변만 보면 알 수 없습니다
- 핑퐁: 넘겨받은 담당이 “이건 저쪽 일”이라며 도로 넘깁니다. 한 턴 이양 상한이 없었다면 계속 돌았을 것입니다
Part 4. v0.3 · 기준 셋을 코드로
def _routing_plan(state, name):
# ② 방금 넘겨준 곳으로 되돌리지 않는다
back = transfer_tool_of(state.get("came_from"))
if back in allowed:
allowed.remove(back)
# ③ 두 갈래가 섞여 들어오면 접수는 넘기지 않고 되묻는다
if name == "triage" and len(topics_in(last_user_message)) >= 2:
return [], True, "규칙: 문의가 둘 이상이라 되묻는다"
# ① 접수의 출력은 언제나 도구 호출이다
return allowed, name == "triage", note4장과 같은 방식입니다. 프롬프트로 타이르지 않고, 판단이 필요 없는 자리를 코드가 가져옵니다.
Part 5. v1.0 · RAG가 부품이 된다
4주차에 제품이었던 것이 도구가 됩니다
- 요금·해지방어 담당에게 약관 검색 도구를 줍니다. 기술지원 담당에게는 주지 않습니다.
- 원본 한 벌 규율 그대로: 본문은 PostgreSQL
documents표에만, Chroma에는 벡터와doc_id만 - 색인이 통째로 날아가도
build_index.py한 번이면 복구됩니다.
[김누리] 데이터 초과 요금은 어떻게 계산되나요? 근거 조항도 알려주세요.
받은 사람: 요금 담당
검색: 제9조 2항 · 정책 D-1 · 제9조 3항 · 제7조 4항
인용: 제9조 2항 — 확인 5장이 남기는 것
- 넘긴다는 것은 도구 호출을
Command(goto=…)로 바꾸는 것이다 - 함께 넘어가는 것은 대화 전체. 요약하는 사람이 중간에 없다
- 담당은 체크포인터에 남는다. 매 턴 덮어쓰면 이양이 지워진다
- 망가지는 모양: 말로만 넘김, 핑퐁, 경로 흔들림
- 규칙 셋: 반드시 도구로, 되돌리지 않기, 섞이면 되묻기
- RAG는 부품이 된다. 인용은 번호로, 검증은 코드로
flowchart LR
A["transfer_to_*"] --> B["Command(goto)"] --> C["담당이 대화를 쥔다"] --> D["체크포인터에 남는다"]
D -.->|"매 턴 덮어쓰면"| X["매 턴 접수부터"]
style X stroke:#d0453f만드는 것과 만들어진 것
flowchart LR
B["브라우저"] -->|":8501"| UI["ui<br/>진행 대시보드"]
UI --> APP["app<br/>FastAPI + LangGraph"]
APP -->|"파일 · git"| WS[("workspace<br/>산출물 저장소")]
APP -->|"docker.sock"| D["도커 데몬<br/>(호스트)"]
D -.->|"별도 compose"| ART["산출물 웹 앱<br/>:8080"]
B -->|":8080"| ART- 산출물은 이 compose가 아니라 자기 compose로 따로 뜹니다.
- 대시보드가 죽어도 산출물은 돌고, 산출물을 내려도 대시보드는 남습니다.
- 만드는 것과 만들어진 것을 섞지 않는 것이 이 저장소의 첫 규율입니다.
Part 1. 경계를 먼저 긋는다
| 누가 쓰는가 | 왜 | |
|---|---|---|
app.py | backend 에이전트 | 제품 코드 |
static/index.html | frontend 에이전트 | 제품 코드 |
tests/test_api.py | tests 에이전트 | 제품 코드 |
| Dockerfile · compose · requirements | 골격 | 매번 흔들릴 이유가 없다 |
| 브랜치 · 커밋 · 머지 · 빌드 | 하네스 | 모델이 git을 부를 이유가 없다 |
- 소유권 밖의 파일에 쓰려 하면 코드가 거부합니다.
- 엔드포인트 규약(CONTRACT)은 골격이 정해 세 프롬프트에 그대로 실립니다.
flowchart TB
K["CONTRACT · 공유 규약"] --> b["backend → app.py"]
K --> f["frontend → index.html"]
K --> t["tests → test_api.py"]
H["골격·하네스<br/>Dockerfile · git · 빌드"] -.-|"모델이 만지지 않는다"| KPart 3. v0.2 · Send가 무엇인가
def fan_out(state):
"""여기가 v0.2의 전부다. 태스크마다 worker 하나씩."""
return [Send("worker", {"task": task, "spec": state["spec"], "index": index})
for index, task in enumerate(state["tasks"])]- 조건부 엣지는 지금까지 문자열 하나를 돌려주었습니다.
- 같은 자리에서
Send의 리스트를 돌려주면, 같은 노드가 여러 벌 동시에 뜹니다. - 페이로드는 그 실행분의 입력입니다. worker가 받는 것은 전체 상태가 아니라 자기 몫의 딕셔너리 하나입니다.
갈라졌다가 모인다
flowchart LR
P["planner<br/>태스크 3개"] --> F{{"fan_out<br/>Send 3개를 돌려준다"}}
F -->|"Send(worker, 태스크①)"| W1["worker<br/>backend"]
F -->|"Send(worker, 태스크②)"| W2["worker<br/>frontend"]
F -->|"Send(worker, 태스크③)"| W3["worker<br/>tests"]
W1 --> I["integrator<br/>results 가 합쳐져 도착"]
W2 --> I
W3 --> I돌아오는 길은 리듀서가 맡습니다. 세 worker의 {"results": [결과]}를
Annotated[list, operator.add]가 합칩니다.
병렬의 절반은 리듀서가 이미 하고 있었습니다.
미리 그린 엣지와 무엇이 다른가
| 미리 그린 병렬 엣지 | Send | |
|---|---|---|
| 개수 | 그래프를 짤 때 고정 | 실행 시점에 정해진다 |
| 각 실행의 입력 | 같은 상태 | 서로 다른 페이로드 |
| 어울리는 일 | 역할이 고정된 분업 | 목록을 훑는 일(map) |
SPEC이 태스크 다섯으로 쪼개지면 worker도 다섯이 됩니다. 그래프를 다시 그리지 않습니다. 계획이 역할을 만듭니다.
flowchart LR
subgraph FIX["미리 그린 엣지"]
s1["상태"] --> w1["worker A"]
s1 --> w2["worker B"]
end
subgraph RUN["Send"]
p["계획: tasks N건"] -->|"N개만큼 띄운다"| wn["worker × N<br/>각자 페이로드"]
end
FIX --> RUN브랜치와 작업 트리는 다른 것이다
flowchart TB
subgraph BAD["작업 트리 하나 · 브랜치만 셋"]
direction LR
G1[(".git")] --- D1["todo-app/<br/>파일 한 벌"]
D1 --- X["backend·frontend·tests가<br/>같은 파일을 밟는다"]
end
subgraph GOOD["worktree · 작업 트리 셋"]
direction LR
G2[(".git<br/>하나")] --- W1["todo-app/<br/>main"]
G2 --- W2[".worktrees/…-backend<br/>feature/backend"]
G2 --- W3[".worktrees/…-frontend<br/>feature/frontend"]
end
BAD ~~~ GOOD- 브랜치는 이름표이고, 작업 트리는 실제 파일이 놓인 디렉터리입니다.
- 셋이 동시에 checkout 하면 마지막으로 실행한 것이 이깁니다. 브랜치를 나눠도 파일은 한 벌뿐이기 때문입니다.
코드 포인트: worktree 격리
worktree = runner.project.add_worktree(task["role"], task["branch"])
try:
result = work_on(runner, task, payload["spec"], task["model"], worktree)
finally:
runner.project.remove_worktree(task["role"]) # 브랜치는 남고 디렉터리만 치운다git worktree add -b feature/backend /workspace/.worktrees/todo-app-backend main
git worktree remove --force /workspace/.worktrees/todo-app-backend같은 저장소에 작업 디렉터리를 하나 더 붙입니다. 커밋 이력은 공유하고 파일만 따로 씁니다.
실측: 순차와 병렬
=== v0.1 순차 ===
backend 2.0s → 3.9s ██████
frontend 3.9s → 8.6s ████████████████
tests 8.6s → 11.2s █████████
전체 13.4초 · $0.0086 · 기동 True
=== v0.2 병렬 (Send + worktree) ===
backend 2.5s → 4.8s █████████████
frontend 2.5s → 6.7s █████████████████████████
tests 2.5s → 4.9s ██████████████
전체 8.8초 · $0.0085 · 기동 True Part 4. v0.3 · 값을 먼저 묻는 문
6주차 budget guard의 진화형입니다
=== ① 상한 $0.05, 넉넉하다 ===
묻지 않고 끝까지 갔다 · 8.8초 · 실측 $0.0087
=== ② 상한 $0.005, 빠듯하다. 승인한다 ===
추정 합계 $0.0114 (상한 $0.0050)
사람이 승인한다 → 7.7초 · 실측 $0.0089
=== ③ 상한 $0.005, 빠듯하다. 중단한다 ===
비용 상한을 넘어 사용자가 중단했습니다
실측 $0.0011. planner 한 번뿐이다. worker는 돌지 않았다.- 6주차의 budget guard는 실행 중의 장부였습니다.
- 이 문은 실행 전의 추정이고, 넘으면 사람에게 묻습니다.
fixer는 테스트를 고쳤다
=== integrator가 로그를 읽고 한 파일을 고친다 ===
수정 1회차 · 고친 파일 ['tests/test_api.py'] → 테스트 True
비용: $0.0089 (수정은 상위 모델로)- 규약과 어긋난 쪽이 테스트였기 때문입니다. 무엇을 고칠지는 모델이 정하고, 한 번에 한 파일이라는 제약만 코드가 겁니다.
- 6주차 Reflexion의 되먹임이 실제 제품에서 어떻게 생기는지가 이 모양입니다.
계속 실패시키면: 수정 1회 · 재계획 1회 · 기동 False
비용 $0.0942 — 한도가 없었다면 여기서 멈추지 않았다. Part 6. v1.0 · 전체 실행
- SPEC을 고르고, 상한을 걸고, 실행하고, 승인하고, 결과를 봅니다.
- 마지막에는 에이전트가 만든 웹 앱이 8080에서 브라우저로 돕니다.
- 두 번의 시도가 git 이력에 그대로 남습니다. 브랜치와 커밋이 곧 작업 기록입니다.
* 41e1c81 (HEAD -> main) fix: app.py
| * cde5a7b (feature/backend-r2) backend: FastAPI 서버 구현
|/
* baf559f fix: app.py
| * f3c8b3f (feature/backend) backend: 메모리 기반 Todo API 구현
|/
* 488cab6 Scaffold the product skeleton 6장이 남기는 것
- “에이전트가 코드를 짠다”의 실체는
write_file하나와 평범한 git·docker - 병렬화의 어려움은 모델이 아니라 작업 공간에 있다. worktree가 격리한다
- 병렬로 버는 것은 시간뿐이다. 비용은 그대로다
- 비용은 실행 전에 묻는다. 거절할 수 있어야 문이다
- 실패하면 로그를 되먹여 한 파일씩 고치고, 안 되면 재계획하고, 한도를 넘으면 멈춘다
flowchart LR
I["실패 로그"] --> FX["fixer<br/>한 파일씩 ≤2"] --> J["다시 판정"]
J -.->|"그래도 실패"| RP["재계획 ≤1"] -.-> STOP["포기"]
style STOP stroke:#d0453f이번 주가 남기는 것
- 나누지 않는 것이 기본이다. 신호를 보고 나누고, 대가를 알고 나눈다
- 줄어드는 것은 총량이 아니라 한 번의 호출이 이고 가는 무게다
- 결과를 모아야 하면 supervisor, 담당이 바뀌면 handoff
- 라우팅은 흔들린다. 확실한 것은 코드가 정한다
- 병렬이 파는 물건은 시간뿐이다. 격리는 작업 공간에서 온다
- 서브 에이전트의 안쪽은 6주차의 그 루프다. 새것은 잇는 방법뿐이다
flowchart LR
L["6주차의 루프"] --> S["supervisor"] & H["handoff"] & P["병렬"]
S & H & P --> N["다음: 서버 안으로<br/>FastAPI"]