파트 1: 에이전트 팀과 함께 커피 로스터 구축하기

이 시리즈를 통해 저는 직접 코드를 타이핑하는 대신 AI 에이전트 팀과 함께 실제 소프트웨어를 구축하는 것이 어떠했는지, 그리고 솔직하게 어디에서 효과적이었고 어디에서 그렇지 않았는지, 그리고 그 작업이 실제로 무엇이 되었는지 공유하고자 합니다. 우리가 만든 것은 커피 로스터 컨트롤러(coffee roaster controller)인데, 로스터가 가열 요소와 팬이 있는 뜨거운 드럼이라는 점과 조작을 잘못하면 배치를 태워버리거나 더 심각한 상황이 발생할 수 있다는 점을 기억한다면 장난감처럼 들리지 않을 것입니다. 그것이 핵심입니다. 저는 틀렸을 때 대가가 따르는 구축을 원했습니다. 왜냐하면 바로 그 지점에 에이전트에게 위임하는 것에 대한 흥미로운 질문들이 존재하기 때문입니다.

이 포스트들은 튜토리얼(tutorials)이 아닙니다. 그보다는 현장 보고서에 가깝습니다. 즉, 구성 요소들이 어떻게 결합되는지, 중요했던 결정은 무엇이었는지, 그리고 제가 가진 증거(receipts)들에 대한 개요입니다. 이전 포스트를 참조하고 다음에 올 내용을 안내할 것이므로, 전체 흐름을 따라가거나 관심 있는 부분만 골라 읽을 수 있습니다.

우리가 만드는 것

프로젝트 이름은 RoastPilot입니다. 이 프로젝트는 Hottop 홈 커피 로스터를 투입(charge, 원두가 들어가는 순간)부터 배출(drop, 원두가 나오는 순간)까지 구동하며, 원두 온도, 상승률(RoR, Rate of Rise, 온도가 올라가는 속도)을 모니터링하고, 1차 크랙(FC, First Crack, 발달 단계의 시작을 알리는 가청 팝 소리)을 감지합니다. 로스팅은 하나의 곡선이며, 좋은 로스팅은 적절한 시점에 적절한 모양을 갖추는 곡선입니다.

운영자는 이 모든 것을 작은 웹 대시보드에서 실시간으로 확인합니다. 그려지는 곡선, 현재 단계, 1차 크랙이 발생한 후의 발달 시간 및 비율, 그리고 중요한 몇 가지 제어 장치들을 볼 수 있습니다. 이는 의도적으로 최소한의 인터페이스로 설계되었습니다. 열과 팬은 다이얼이 아닌 읽기 전용(read-outs)으로 표시되는데, 이 기계에서 그것들은 컨트롤러의 역할이지 인간(또는 모델)이 로스팅 중간에 수동으로 조절하기를 원하는 것이 아니기 때문입니다.

실시간 대시보드. LLM Advisory라고 표시된 패널은 모델의 최신 권장 사항(recommendation)이며, 그 아래의 결정 이력(decision history)은 안전 정책(safety policy)이 각 권장 사항에 대해 어떻게 조치했는지를 보여줍니다. (모의 데이터를 사용한 디자인 프로토타입이며, 실제 배포된 판결은 ALLOW / CLAMP / REJECT로 표시됩니다.)

로스팅이 완료되면 동일한 데이터가 나중에 다시 읽을 수 있는 기록이 됩니다. 전체 곡선(curve), 주요 지점(milestones), 핵심 수치(headline numbers), 그리고 모델이 내린 모든 권장 사항과 그에 따라 어떤 일이 일어났는지에 대한 전체 추적(trace) 정보가 포함됩니다.

완료된 로스팅. 하단의 결정 추적(decision trace)은 제가 가장 중요하게 생각하는 부분입니다. 검토를 위해 보관된 모든 상담(consult), 권장 사항(recommendation), 그리고 판결(verdict)이 포함되어 있습니다.

이것은 표면적인 모습일 뿐입니다. 이 시리즈가 존재하는 이유는 그 이면에 있으며, 이는 제가 전체 과정에서 강조할 단어인 'harness(제어/활용)'와 관련이 있습니다. 이 이야기에는 실제로 두 가지 harness가 있으며, 지금 이를 구분해 둘 가치가 있습니다. **런타임 harness (runtime harness)**는 로스팅을 실행하고 모델의 조언이 엄격한 제한 범위 내에 머물도록 유지하는 컨트롤러, 어드바이저(advisor) 및 안전 시스템입니다. **빌드 harness (build harness)**는 애초에 에이전트 팀이 해당 소프트웨어를 구축하도록 유도(steer)한 방식입니다. 이 포스트는 두 가지를 모두 소개하며, 시리즈는 이 둘 사이를 오가며 진행됩니다. 다음 두 섹션에서는 작업이 어떻게 수행되었는지부터 시작하여, 그 결과물인 소프트웨어의 형태 순으로 각각을 차례대로 다룹니다.

아이디어: 에이전트 팀을 이끄는 PM

저는 앉아서 이 코드를 작성하지 않았습니다. 저는 Claude Code 에이전트들로 구성된 작은 팀의 프로덕트 매니저 (PM)이자 아키텍트 (architect)로서 일했으며, 제 역할은 에이전트들이 구축을 수행하는 동안 계획, 결정, 그리고 판단 (judgment calls)을 책임지는 것이었습니다. 인간은 단순한 조회 (lookup)로 환원되지 않는 일들을 위해 루프 안에 머무르는데, 실제로 이는 놀라울 정도로 구체적인 목록을 형성합니다.

작업은 세 가지 형태로 배분되었으며, 이들 사이에서 의도적으로 선택하는 과정이 기술 (craft)의 대부분을 차지했습니다.

• 단일 서브 에이전트 (A single sub-agent): 독립적인 하나의 스토리를 위해, 시작부터 풀 리퀘스트 (pull request)까지 한 명의 소유자가 담당합니다.
• 에이전트 팀 (An agent team): 공통된 기반이 마련된 후, 여러 조각을 진정으로 병렬로 구축할 수 있을 때 페이지나 인터페이스당 한 명의 팀원을 배치합니다.
• 동적 워크플로우 (A dynamic workflow): 작업이 여러 항목에 대해 반복 가능한 파이프라인 (build, review, verify)인 경우이며, 제어 흐름 (control flow)이 모델의 재량에 맡겨지기보다 결정론적 (deterministic)이기를 원할 때 사용합니다.

각 방식을 선택하는 이유와, 작업을 확장하는 것이 정확히 잘못된 선택이었던 경우들에 대해서는 시리즈의 후반부 포스트에서 자세히 다룹니다. 지금 당장의 핵심은 바로 그 '자리' 자체입니다. 에이전트들이 타이핑을 수행함에 따라, 병목 현상 (bottleneck)은 더 이상 코드 생성 (code generation)이 아닙니다. 그것은 바로 판단 (judgment), 메모리 (memory), 그리고 검증 (verification)입니다. 이 포스트들의 상당 부분은 실제로 이 세 가지에 관한 것입니다.

                          당신
            아키텍트 / 도메인 소유자 / 의사 결정자
                       │  ▲
...

운영 모델: 당신은 PM 자리를 조종하고, PM 자리는 각 작업에 적합한 형태를 선택하며, 모든 것은 동일한 공유된 진실 (shared truth)에 기록되므로 어떤 에이전트도 다른 에이전트의 채팅 기록에 의존하지 않습니다.

상위 수준 아키텍처: 결정론적 컨트롤러, 조언자로서의 LLM

시스템에는 다른 모든 것의 기준이 되는 하나의 불변 법칙(invariant)이 있으며, 이는 많은 에이전트형 AI (agentic AI) 관련 글들이 지향하는 바와 정반대이기 때문에 명확히 밝혀둘 가치가 있습니다. 컨트롤러(controller)가 루프(loop)를 소유하며, 거대 언어 모델 (LLM)은 오직 조언만 합니다. 결정론적 컨트롤러 (deterministic controller)는 정해진 틱(tick)에 맞춰 로스팅을 실행하고, 센서를 읽으며, 기계가 무엇을 할지 결정합니다. LLM은 권장 사항을 위해 자문을 구하며, 타입이 지정된 데이터 (typed data)를 반환하고, 그 권장 사항이 하드웨어로 직접 연결되는 일은 결코 없습니다. 모델에서 오든 운영자로부터 오든 모든 명령은 먼저 안전 정책 (safety policy)을 통과하며, 이 정책은 명령을 허용하거나, 허용 범위 내로 제한하거나, 혹은 완전히 거부할 수 있습니다.

따라서 모델은 자신이 넘어설 수 없는 단단한 상자 안에 위치합니다. 이는 야망의 부족이 아니라 설계의 의도입니다. 잘못된 판단이 뜨거운 드럼 안의 원두 배치를 망치는 것을 의미할 때, 레버를 잡고 있는 것은 영리하지 않더라도 예측 가능한 존재여야 하며, 영리한 존재는 상자가 거부할 수 있는 의견을 제시하는 역할이어야 합니다. 이 시리즈의 후반부에 등장할 더 날카로운 전환점 중 하나는, 모델에게 더 많은 권한을 주는 것이 아니라 더 적은 권한을 주고, 더 많은 제어권을 결정론적 계층 (deterministic layer)으로 옮기도록 가르쳐준 로스팅 경험입니다. 여기서 스포일러를 하지는 않겠지만, 위의 구조는 그 이야기를 위한 설정입니다.

전체 시스템을 한 페이지로 나타낸 것. 외부 루프는 기계를 소유하는 결정론적 컨트롤러이며, 내부 루프는 LLM의 조언 단계입니다. LLM의 출력은 타입이 지정된 결정 (typed decision)으로 돌아오며, 컨트롤러는 명령이 로스터에 도달하기 전에 이를 안전 게이트 (safety-gate)를 통해 검증합니다. 모델은 Pi(라즈베리 파이)를 기반으로 작동하는 유일한 부분입니다.

세 가지 규칙이 그 상자(box)를 닫아두고 있으며, 이것이 이 시스템을 단순히 LLM(대규모 언어 모델)이 포함된 앱이 아닌 하네스 (harness)로 만드는 요소입니다. 첫째, 기계에 대한 모든 쓰기 작업은 예외 경로 없이 안전 정책 (safety policy)을 통과합니다. 따라서 모델이나 운영자 모두 정책이 이를 확인하고 허용, 제한 또는 거부하지 않고서는 열기나 팬을 조절할 수 없습니다. 둘째, 어드바이저 (advisor)에게는 결코 실행 도구가 직접 전달되지 않습니다. 어드바이저는 오직 타입이 지정된 조언 (typed advice)만을 반환하므로, 혼란에 빠지거나 적대적인 모델이라 할지라도 하드웨어에 직접 접근할 수 있는 경로가 없습니다. 셋째, 재시작 시 열기나 팬이 자동으로 재개되지 않습니다. 만약 로스팅 중간에 소프트웨어가 다시 가동된다면, 추측하는 대신 멈춰서 운영자에게 물어봅니다. 뜨거운 드럼을 가정하에 재가동하는 것은 바로 이 설계가 방지하고자 하는 '확신에 찬 잘못된 움직임'이기 때문입니다.

이 시점에서 몇 가지 솔직한 경계선을 정해두고자 합니다. 여러분이 이를 넘어서서 추측하기보다는 제가 먼저 명확히 설정하는 편이 낫기 때문입니다. 이것은 완성된 제품이 아니라 진행 중인 빌드 (build)입니다. LLM은 오직 조언 역할만 수행하며 하드웨어를 직접 제어하지 않습니다. 저는 결정론적 (determinism) 백분율을 인용하거나 무엇인가를 완전히 자율적 (autonomous)이라고 부르지 않을 것이며, 실제 기계에서 엔드 투 엔드 (end-to-end)로 검증되기 전까지는 프로덕션 준비가 되었다 (production-ready)고 말하지 않을 것입니다. 검증되지 않은 작업에 대해서는 그렇다고 명시하겠습니다.

시리즈에서 다루는 내용

우리가 어디로 가고 있는지 알 수 있도록, 앞으로 진행될 내용의 대략적인 형태를 소개합니다:

• Claude Code에서 팀이 실제로 어떻게 연결되어 있는지: 역할(roles)과 어떤 도구가 계획(plan)을 보유하는지에 대하여.
• 팀을 구성한 후 작업이 조직되는 방식: 공유 메모리(shared memory)로서의 계획 리포지토리(plan repo), 그리고 작업을 나누는 올바른 기준은 전문 분야(discipline)가 아니라 어떤 파일들이 충돌(collide)하는지여야 하는 이유.
• 빌드 자체 도구가 포착한 것들: 인간과 리뷰가 놓쳤던 부분들, 단순히 테스트를 건너뛰는 것이 아니라 조용히 실패를 숨기고 있었던 테스트를 포함하여.
• 이러한 방식으로 빌드를 실행하는 데 드는 비용: 정직하게 측정된 비용.
• 가장 깊이 있는 기술적 이야기: 실제 로스팅 과정을 테스트 세트로 재현하여 로스트 어드바이저(roast advisor)를 선택하고, 이를 실제 뜨거운 기계에 적용하여 오프라인 평가(offline eval)가 볼 수 없었던 것을 찾아내는 과정.
• 이 모든 것이 안전이 중요한 취미 프로젝트를 넘어 어떻게 일반화될 수 있는지: 일반적인 제품 작업에 대한 두 번째 사례 연구와 함께.

로스터는 테스트 케이스일 뿐입니다. 실제 주제는 일하는 방식입니다. 다음 포스트에서는 Claude Code에서 팀이 어떻게 구성되는지, 그리고 그 빌딩 블록(building blocks) 중 어떤 것이 최종적으로 계획을 보유하게 되는지에 대해 구체적으로 다룹니다.