tunaFlow는 Claude, Codex, Gemini 같은 CLI 에이전트를 하나의 앱에서 오케스트레이션하는 데스크톱 클라이언트입니다. 아직 공개하지 않았고, 현재는 개인 테스트 프로젝트로 진행하고 있습니다.

이 시리즈는 그 과정에서 겪은 기술적 고민과 설계 결정을 공유하는 글입니다. 같은 방향으로 개발하시는 분들에게 0.1이라도 참고가 되었으면 좋겠습니다. 반박시 님들 말이 모두 맞습니다. 😁

이 글은 시리즈의 첫 번째 편(총 10편+)으로, "왜 오케스트레이션 레이어가 필요한지"에 대한 이야기입니다.

---

## Claude Code 하나면 되는 거 아닌가?

솔직히 말하면, 에이전트 하나만으로도 많은 것을 할 수 있습니다. Claude Code에 프로젝트를 열고 "이거 만들어줘"라고 하면 꽤 잘 만들어줍니다. Codex도, Gemini CLI도 마찬가지입니다.

그런데 프로젝트가 조금만 커지면 이런 상황이 생깁니다.

나: "인증 미들웨어 리팩토링 해줘"
Claude: (바로 코드 작성 시작)

나: "잠깐, 설계부터 하자"
Claude: "네, 다음과 같은 설계를 제안합니다..." (이미 3파일 수정한 뒤)
나: "리뷰도 해줘"
Claude: (자기가 짠 코드를 자기가 리뷰) "잘 짠 것 같습니다 ✅"

자기가 짠 코드를 자기가 리뷰하는 건 사람이 해도 잘 안 됩니다. 에이전트도 마찬가지입니다. 본인의 맥락과 판단이 이미 들어가 있기 때문에 객관적인 리뷰가 어렵습니다.

이건 에이전트의 능력 문제가 아니라 프로세스의 부재 문제입니다. 설계 → 구현 → 리뷰 → 수정이라는 기본적인 개발 프로세스를 에이전트에게 적용하는 구조가 없는 겁니다.

이 문제의식은 Stavros Korokithakis의 블로그 글에서 큰 영감을 받았습니다. Claude Code로 프로젝트를 진행하면서 자연스럽게 만들어간 워크플로우 - Plan을 먼저 세우고(opus), 승인 후 구현(sonnet)하고, 결과를 리뷰(codex)하는 흐름 - 를 보면서 "이걸 도구가 지원해야 하는 것 아닌가?"라는 생각이 tunaFlow 워크플로우 파이프라인의 출발점이 되었습니다.

---

## 그래서 만든 것: 오케스트레이션 레이어

tunaFlow는 에이전트를 직접 만드는 것이 아니라, 기존 에이전트(Claude Code, Codex, Gemini CLI 등)를 프로세스 안에서 조율하는 레이어입니다.

일반적인 사용:
사용자 ↔ Claude Code (1:1 대화)
tunaFlow:
  사용자 ↔ tunaFlow ↔ Claude Code Opus(Architect 역할)
                   ↔ Claude Code sonnet(Developer 역할)
                   ↔ Codex 5.4(Reviewer 역할)
                   ↔ Gemini (RT 토론 참가자 또는 블라인드 판별자)

핵심은 에이전트 자체를 개선하는 것이 아니라, 에이전트가 일하는 프로세스를 만들어주는 것입니다.

'### 에이전트를 직접 만들지 않는 이유

tunaFlow는 LLM API를 직접 호출하지 않습니다. Claude Code CLI, Codex CLI, Gemini CLI를 subprocess로 호출합니다.

// 실제 코드 (claude.rs)
let mut cmd = Command::new("claude");

cmd.arg("-p")
    .arg(&input.prompt)
    .arg("--output-format").arg("stream-json")
    .arg("--model").arg(model);

이렇게 하면 각 CLI가 가진 기능(파일 편집, 터미널 실행, MCP 연동 등)을 그대로 활용할 수 있습니다. SDK로 직접 API를 호출하면 채팅만 되지, 파일을 고치거나 테스트를 돌리는 건 전부 직접 구현해야 합니다.

트레이드오프가 있습니다. CLI subprocess 방식은 에이전트 내부를 들여다볼 수 없습니다. 어떤 tool을 호출했는지, 중간에 뭘 생각했는지 알기 어렵습니다(조금은 보입니다). 대신 각 CLI의 전체 기능을 공짜로 얻습니다.

---

## 어떤 구조인가

tunaFlow의 전체 구조는 이렇습니다.

┌─ Desktop App (Tauri 2) ──────────────────────────────┐
│                                                      │
│  React Frontend ←──Tauri IPC──→ Rust Backend         │
│  ├── Chat (메인 대화)           ├── Agent Adapters     │
│  ├── Workflow (Plan/Review)   │    ├── claude.rs     │
│  ├── Branch (대화 분기)         │    ├── codex.rs      │
│  ├── RT (에이전트 토론)          │    ├── gemini.rs     │
│  ├── Artifacts (산출물)        │    ├── openai_compat  │
│  └── Trace (실행 추적)          │    └── ...           │
│                               ├── ContextPack        │
│                               ├── SQLite (WAL)       │
│                               └── rawq, CRG          │
└──────────────────────────────────────────────────────┘
        ↓ subprocess
    ┌─────────┬──────────┬──────────┐
    │ claude  │  codex   │  gemini  │  ← 각 CLI 에이전트
    └─────────┴──────────┴──────────┘

Tauri 2 위에 React + Rust로 만든 데스크톱 앱입니다. 현재 Rust 25,894줄, TypeScript 24,419줄, 테스트 406개(Rust 230 + Frontend 176) 규모입니다.

### 핵심 기능 5가지

tunaFlow의 킬러 기능을 간단히 소개합니다. 각각은 이 시리즈의 이후 편에서 상세히 다룰 예정입니다.

1. 워크플로우 파이프라인 (→ 2편에서 상세)

Chat → Plan 승격 → 사용자 승인 → Developer 실행 → Review RT → Done
         ↑ 사람                             ↑ 사람 

Architect가 Plan을 만들고, 사용자가 승인하면 Developer가 구현하고, Reviewer가 검증합니다. 여기서 중요한 건 사람이 승인하는 지점이 명확하다는 것입니다. 에이전트가 마음대로 다 하는 구조가 아닙니다.(다 하면 큰일 납니다 😇)

2. Branch (대화 분기) (→ 3편에서 상세)

대화 중간에서 분기해서 독립적으로 실험하고, 결과가 좋으면 메인 대화에 병합합니다. git branch와 유사한 개념을 대화에 적용한 것입니다.

3. Roundtable (에이전트 토론) (→ 4편에서 상세)

여러 에이전트가 같은 주제로 토론합니다. Claude와 Codex, Gemini i가 각자 의견을 내고, 사용자가 판정합니다. 합의는 에이전트가 하는 것이 아니라 사람이 합니다.

4. ContextPack (맥락 조립) (→ [기 발행 포스트] 참고)

매 요청마다 에이전트에게 필요한 정보(프로젝트 정보, 계획, 코드 검색 결과, 장기 기억 등)를 조립해서 넘깁니다. 4개 엔진이 동일한 품질의 컨텍스트를 받도록 합니다.

5. 품질 보증 시스템 (→ 9편에서 상세)

에이전트가 같은 실수를 반복하면 자동으로 감지하고 에스컬레이션합니다. 리뷰 5번 실패하면 사람에게 "이거 설계부터 다시 봐야 할 것 같습니다"라고 알려줍니다.

---

## "Human with Agent" — 사람이 판단하고 에이전트가 실행한다

tunaFlow의 설계 철학은 한 문장으로 요약됩니다.

> 사람이 방향을 결정하고, 에이전트가 그 결정을 최적의 조건에서 실행한다.

"에이전트가 알아서 다 해준다"가 아닙니다. 에이전트는 실행을 잘하지만, 무엇을 할지 결정하는 것은 여전히 사람이 더 잘합니다. 특히 다음 영역에서:

- 아키텍처 결정: 에이전트의 학습 데이터에는 좋은 패턴과 나쁜 패턴이 섞여 있습니다

- 무엇을 안 할지: 에이전트는 "No"를 잘 못합니다. 요청하면 거의 다 해줍니다

- 전체 맥락에서의 판단: 에이전트는 현재 대화의 맥락만 봅니다. 비즈니스 맥락, 팀 상황, 일정 같은 건 모릅니다

그래서 tunaFlow의 모든 핵심 지점에는 사람이 개입하는 게이트가 있습니다.

Plan 승인:     "이 방향으로 갈까요?" → 사용자 승인/거부/수정요청
Review 판정:   "리뷰 결과입니다" → 사용자가 최종 확인
RT 라운드 판정: "토론 결과입니다" → 사용자가 정리/계속/종료 결정
Rework 판단:   "3번 실패했습니다" → 사용자가 방향 전환 결정

이게 "에이전트가 자동으로 다 해주는 것"과 결정적으로 다른 점입니다. 속도는 조금 느려지지만, 엉뚱한 방향으로 달려가는 것을 막을 수 있습니다.(하지만 인간지능이 엉뚱한 방향으로 가면 어쩔 수 없습니다)

---

## 엔진 아키텍처: 하나로도 되고, 여러 개도 된다

tunaFlow는 엔진(에이전트)을 최소 1개부터 최대 4-5개까지 조합할 수 있습니다.

중요한 건 Claude $20 Pro 플랜 하나로도 워크플로우 전체가 동작한다는 점입니다. 같은 Claude Sonnet 모델로 Architect/Developer/Reviewer를 돌려도, ContextPack과 Persona가 역할을 분리해줍니다.

Architect: claude --model claude-sonnet-4-6 + Architect Persona
Developer: claude --model claude-sonnet-4-6 + Developer Persona
Reviewer:  claude --model claude-sonnet-4-6 + Reviewer Persona
→ 같은 모델이지만 역할별 프롬프트가 다르므로 행동이 다릅니다

물론 엔진을 분리하면 더 좋습니다. Claude가 설계하고 Codex가 구현하면 각자의 강점을 살릴 수 있고, 비용도 분산됩니다. 하지만 진입 장벽을 낮추는 것도 중요합니다.

---

## 지금까지 배운 것

tunaFlow를 만들면서 얻은 중간 결론 몇 가지입니다.

### 1. 모델 품질보다 컨텍스트 품질이 더 중요하다

> "A lot of apparent 'model quality' is really context quality." — Sebastian Raschka

같은 모델에 같은 질문을 해도, 어떤 맥락을 함께 넘기느냐에 따라 결과가 크게 달라집니다. ContextPack을 잘 조립하면 Sonnet이 대충 던진 Opus보다 나은 결과를 냅니다. 이건 과장이 아니라 실제로 여러 번 경험한 것입니다.

### 2. 자동화와 자율은 다르다

워크플로우를 자동화하는 것과 에이전트에게 자율권을 주는 것은 다릅니다. tunaFlow는 프로세스를 자동화하되, 판단은 사람이 합니다. Plan 승인, Review 판정, Rework 결정 — 이 세 지점에서 사람이 개입합니다.

처음에는 "전부 자동이면 더 좋지 않을까"라고 생각했는데, 실사용에서 바로 문제가 드러났습니다. 에이전트가 잘못된 방향으로 달려가면 되돌리는 비용이 처음부터 사람이 확인하는 비용보다 훨씬 큽니다.

### 3. 에이전트에게 프로세스를 줘야 한다

Claude Code가 못하는 것이 아닙니다. Claude Code는 도구 실행 능력이 뛰어납니다. 부족한 것은 프로세스입니다. 설계 → 승인 → 구현 → 리뷰 → 수정이라는 기본적인 개발 플로우를 에이전트에게 적용하는 구조.

에이전트에게 더 좋은 모델을 주는 것보다, 더 좋은 프로세스를 주는 것이 결과를 더 크게 바꿉니다.

---

## 한계

솔직히 말하면 아직 한계가 많습니다.

- CLI subprocess 방식의 제약: 에이전트 내부 tool call을 관찰할 수 없습니다. 뭘 하고 있는지 stdout/stderr로 추정만 가능합니다

- 토큰 비용: 멀티 에이전트를 적극적으로 쓰면 비용이 빠르게 올라갑니다. 3명이 2라운드 토론하면 한 번에 ~30K 토큰입니다

- 프로세스의 오버헤드: 간단한 수정인데도 Plan → Approve → Dev → Review를 거치면 과도합니다. 상황에 따라 프로세스를 건너뛰는 유연성이 필요합니다

- RT의 합의 한계: 에이전트끼리 토론시켜봐도 진짜 "합의"는 잘 안 됩니다. 결국 사람이 정리해야 합니다

이 한계들은 이후 시리즈에서 각각 어떻게 대응하고 있는지(또는 아직 못 하고 있는지) 다룰 예정입니다.

---

## 다음 방향: 메타에이전트

현재 tunaFlow에서 프로세스를 관리하는 것은 사용자입니다. "다음에 뭘 할지", "Rework할지 방향을 바꿀지", "어떤 엔진이 적합한지"를 사람이 판단합니다.

앞으로는 이 프로세스 관리 자체를 돕는 메타에이전트를 도입할 계획입니다. 단, 여기서 중요한 구분이 있습니다. 메타에이전트는 Architect의 상위가 아닙니다.

- Architect는 "어떻게 만들 것인가"를 설계합니다 (기술적 분해)

- 메타에이전트는 "지금 무엇을 해야 하는가"를 제안합니다 (프로세스 판단)

예를 들면 이런 차이입니다.

메타에이전트: "auth 관련 Plan의 Rework 비율이 40%입니다.
              설계를 재검토하는 게 어떨까요?"
              → 프로젝트 상태 분석 + 우선순위 제안
Architect:    "인증 미들웨어를 OAuth2 PKCE로 전환하겠습니다.
              subtask 3개로 나누겠습니다."
              → 기술적 설계 + 분해

메타에이전트가 "설계를 재검토하세요"라고 제안할 수는 있지만, 실제로 Plan을 수정하는 것은 Architect의 몫이고, 그 수정을 승인하는 것은 사람의 몫입니다. 제안까지만. 결정은 사람이. tunaFlow의 "Human with Agent" 원칙은 메타에이전트에게도 동일하게 적용됩니다.

이 위계에 대한 상세한 논의는 시리즈 후반에서 다룰 예정입니다.

---

## 다음 편 예고

2편: "Plan → Dev → Review" — 워크플로우 파이프라인 구현기

에이전트 역할을 Architect/Developer/Reviewer로 분리하고, 승인 게이트를 넣고, Rework 루프를 만드는 과정에서의 설계 결정들을 다룹니다. "사람이 개입하는 지점을 어디로 잡았는가"가 핵심입니다.

---

## 시리즈 목록

1. 에이전트에게 프로세스를 줘라 — AOC를 만들면서 배운 것 (이 글)

2. Plan → Dev → Review — 워크플로우 파이프라인 구현기

3. 대화를 분기한다 — Branch 설계와 활용

4. 에이전트끼리 토론시키기 — Roundtable 설계와 한계

5. 대화가 길어지면 — 에이전트 장기 메모리 구현기

6. Claude $20으로 워크플로우 돌리기 — 엔진 아키텍처

7. 코드 구조를 에이전트에게 알려주기 — rawq + code-review-graph

8. 246개 스킬 중 필요한 것만 — 스킬 자동 적용 구현기

9. 에이전트가 같은 실수를 반복하면 — 품질 보증 설계

10. tunaFlow로 풀사이클 돌려보기 — 워크플로우 실전 테스트 회고

+ [기 발행] ContextPack — 멀티 에이전트 오케스트레이터의 컨텍스트 설계

---

## 레퍼런스

- Stavros Korokithakis — Claude Code로 프로젝트를 진행하면서 자연스럽게 형성된 워크플로우(Plan → 승인 → 구현 → 리뷰)가 tunaFlow 워크플로우 파이프라인의 근본 영감.

https://www.stavros.io/posts/building-with-claude-code/

- Sebastian Raschka — "Components of a Coding Agent" (2025): 코딩 에이전트의 6개 핵심 컴포넌트 분석. "model quality = context quality" 인용의 출처.

https://magazine.sebastianraschka.com/p/components-of-a-coding-agent

- Addy Osmani — "Orchestrating Coding Agents" (2025): 멀티 에이전트 오케스트레이션의 패턴, 스케일링, 품질 게이트 종합.

https://addyosmani.com/blog/code-agent-orchestra/

- tunaFlow 내부 문서

- CLAUDE.md — 프로젝트 핸드오프 문서 (현재 세션 22, DB v30)

- docs/ideas/techPostSeriesIdea.md — 시리즈 기획 문서