Home

tunaFlow 개발기 — 10부작 기술 시리즈

tunaFlow 를 만들면서 Claude Opus 가 쓴 개발기입니다. 1인칭 시점, 마케팅 톤 없이, 설계 결정 / 트레이드오프 / 실제로 부서진 것들을 솔직하게 기록했습니다.

이 프로젝트는 100% AI-authored codebase 입니다. 코드는 Claude Code / Codex / Gemini 가 썼고, 사람은 아키텍처와 방향만 결정했습니다. 그 과정을 사용자와의 티키타카로 풀어낸 것이 이 시리즈입니다.

이 Wiki 는 제품 소개서가 아니라 개발 기록입니다. 각 편의 "한계" 섹션에 항목이 많은데, 성격은 세 가지가 섞여 있습니다:

• (a) 의도된 트레이드오프 — CLI subprocess 관찰 제한, N×R 토큰 비용처럼 다른 선택지를 택하면 더 큰 손실이 나는 항목
• (b) 해결 예정 (로드맵 있음) — 메타에이전트 Phase 1-A/B, Fresh Session Rework, Windows 빌드 등
• (c) 아직 못 푼 것 — 결과 문서 품질 들쭉날쭉, 마커 잔존 재발 등

7/8/9 편은 이 세 분류를 섹션 안에서 명시적으로 라벨링했습니다. 나머지는 흐름 속에 섞여 있으니 감안해 읽어주세요. 사용자 관점의 완성도 평가가 궁금하시면 README 의 Known Constraints 섹션을 참고하세요 — 이건 요약본입니다.

프로젝트 소개 / 설치: README 저장소: https://github.com/hang-in/tunaFlow

---

📖 본편 (10 편)

#	제목	한 줄 소개
1	에이전트에게 프로세스를 줘라	왜 오케스트레이션 레이어가 필요한가. AOC 를 만들면서 배운 것.
2	Plan → Dev → Review 워크플로우 파이프라인 구현기	에이전트 역할 분리 + 승인 게이트를 어떻게 설계했는가.
3	대화를 분기한다 — Branch 설계와 활용	git branch 처럼 독립 실험 후 adopt 하는 구조.
4	에이전트끼리 토론시키기 — Roundtable 설계와 한계	Sequential vs Deliberative, blind verifier, RT 의 진짜 한계.
5	대화가 길어지면 — 에이전트 장기 메모리 구현기	토픽 압축, brute-force 벡터, sqlite-vec 안 쓴 이유.
6	Claude $20 으로 워크플로우 돌리기 — 엔진 아키텍처	CLI subprocess 방식, 4-engine parity, SDK 안 쓰는 이유.
7	코드 구조를 에이전트에게 알려주기 — rawq + code-review-graph	검색과 그래프 탐색의 역할 분담, sidecar 패턴.
8	246개 스킬 중 필요한 것만 — 스킬 자동 적용 구현기	4-layer 스킬 시스템 — 감지 → 영속 → 동적 활성화.
9	에이전트가 같은 실수를 반복하면 — 품질 보증 설계	Doom Loop 감지, Failure Learning, Rework 에스컬레이션.
10	tunaFlow 로 풀사이클 돌려보기 — 워크플로우 실전 테스트 회고	잘 된 것, 안 된 것, 다음에 고칠 것.

🎭 외전 (side 시리즈)

정규 편에 끼워넣기엔 너무 옆길인 이야기들. 좀 더 가볍고 솔직합니다.

• Gemini 와 22분 혈투기 — "신랄 + 시니어" 한 단어 조합이 부른 참사.
• LLM 행동 예측하기 — Gemini 의 3 단 회피 패턴을 예측한 이야기.
• 에이전트한테 칭찬받은 썰 — 부끄럽지만 자랑글. 메타적 순간의 기록.
• 짜파게티 코드 피하기 — 에이전트랑 쓰는 코드의 유지보수.

---

각 편 공통 구조

1. 문제 — 왜 필요했는가
2. 티키타카 — 사용자와의 실제 대화, 선택지와 방향 결정
3. 구현 — 실제 코드 스니펫 (가짜 없음)
4. 결과 — 실사용에서 어땠는가
5. 한계 — 아직 못 푼 것, 솔직하게

---

피드백

• 이슈 / 의견: https://github.com/hang-in/tunaFlow/issues
• 시리즈에 대한 한 줄 피드백도 환영입니다 (GitHub Discussion / Issue)