자유로운 요청, 의도적인 배포: 인간 참여형(Human-in-the-Loop) AI 제품 변경을 위한 아키텍처

코딩 에이전트(Coding agents)는 이제 문장 하나만으로 실제 코드베이스를 변경할 수 있게 되었습니다. 업계의 다음 움직임은 명확해 보입니다: 요청을 생산 환경(production)까지 전송하는 것입니다. 티켓(Ticket) 입력, 풀 리퀘스트(Pull request) 출력, 병합(merge), 배포(deploy).

저는 이것이 차이점(diff)을 읽지 못하는 사람이 요청한 변경 사항에 대한 잘못된 기본값이라고 생각합니다. 모델 자체가 나쁘기 때문이 아닙니다. 작은 제품 변경의 느린 부분은 타이핑 자체가 아니었으며, 마지막 단계인 '사람이 결정하는 것'은 저렴하고 유지할 가치가 있습니다.

본 글에서는 이러한 주장을 펼치고, Butterneck에서 인간을 병목 지점(bottleneck)으로 만들지 않으면서도 루프에 참여시키는 데 사용하는 구체적인 아키텍처를 제시합니다.

작은 변경이 실제로 시간을 소비하는 곳

'버튼 문구를 'Book a call'로 바꿔줘'라는 요청을 예로 들어보겠습니다. 수정은 한 줄입니다. 하지만 시간은 그 주변의 모든 것에 쓰입니다: 어느 페이지인지, 어떤 버튼인지, 스크린샷, 누군가 파일을 찾고, 링크를 보내 확인해 달라고 하고, 답장하고, 또 다른 미세 조정이 필요합니다.

또는 설명과 함께 수십 개의 댓글 및 세 개의 첨부 파일이 있는 티켓을 생각해 보세요. 개발자는 그중 어떤 댓글이 실제 요청인지 파악해야 합니다.

에이전트는 바로 이런 작업에 능숙합니다: 컨텍스트를 읽고 수정하는 것입니다. '배포하기로 결정하는 것'을 자동화하면 어쩌면 1분을 절약할 수 있습니다. 또한 고객이 발견하기 전에 잘못된 변경 사항을 잡아내는 검토 단계를 제거해 줍니다.

설계할 가치가 있는 세 가지 속성

비개발자도 에이전트에게 변경 요청을 하도록 하려면, 시스템은 다음 세 가지가 필요하다고 주장하고 싶습니다.

요청이 대상 옆에서 이루어져야 한다. 요청하는 사람은 기억에 의존하여 제품을 설명하는 것이 아니라, 실행 중인 제품을 보고 있어야 합니다.
변경 사항이 실제가 되기 전에 보여야 한다. 아무도 배포하지 않아도, 그들은 같은 화면에서 즉시 결과를 봐야 합니다.
개발자가 유일한 배포 경로여야 한다. 에이전트는 파일을 수정할 수 있습니다. 오직 사람만이 그것들을 실제로 작동하게 만들 수 있습니다.

이 중 어느 것도 새로운 AI가 필요한 것은 아닙니다. 이것들은 인프라(plumbing) 결정 사항입니다.

아키텍처

Butterneck이 이 세 가지 속성을 어떻게 구현하는지 보여드리겠습니다. 구체적으로 설명하겠습니다.

1. 에이전트는 코드가 이미 존재하는 곳에서 실행된다

데몬(daemon)이 개발자 장치에서 실행됩니다. 개발자는 하나 이상의 프로젝트 폴더를 연결합니다. 각 폴더는 메인 체크아웃, 새로 클론된 폴더, 또는 작업 복사본을 건드리지 않고 여러 요청을 실행할 수 있는 .worktrees/ 아래의 git worktree일 수 있습니다.

요청이 도착하면 브릿지의 채팅 서버가 개발자가 이미 사용하는 코딩 CLI(Cursor, Claude Code, Antigravity 등)를 해당 폴더에 한정된 일회성 자식 프로세스로 시작합니다. Butterneck은 모델을 배포하지 않습니다. 개발자의 기존 에이전트와 그 제공자 약관이 적용됩니다.

왜 로컬인가요? 프로젝트는 이미 실제 종속성, 데이터 및 개발 서버가 있는 곳에서 실행되고 있습니다. 동기화할 클라우드 환경이 없습니다.

2. 사람들이 이미 존재하는 곳으로 요청이 들어옵니다

두 가지 진입점이 있습니다:

실시간 미리 보기(live preview)에 임베딩된 채팅 위젯입니다. 이 위젯은 메시지와 함께 페이지 URL을 전송하므로, "이 버튼"이 참조 대상(referent)을 갖게 됩니다.
butterneck 레이블이 지정된 Jira Cloud 티켓입니다. 제목, 설명, 댓글 및 첨부 파일이 요청이 됩니다. 미리 보기 링크가 포함된 메모는 해당 티켓으로 다시 게시됩니다.

스레드에서 개발자가 답장하는 것은 에이전트를 트리거하지 않으므로, 개발자는 또 다른 편집을 시작하지 않고도 요청자에게 이야기할 수 있습니다.

3. 미리 보기는 실행 중인 개발 서버입니다

브릿지는 앱을 시작하고 서버는 브릿지의 WebSocket을 통해 트래픽(핫 리로드 소켓 포함)을 전달하는 공개 공유 URL을 발행합니다. 에이전트가 파일을 저장하면, 개발 서버가 다시 로드되고 요청자가 이를 볼 수 있습니다.

이는 배포 단계 없이 속성 2를 제공한다는 것을 의미합니다. 또한 에이전트는 턴(turn) 중간에 프로덕션 빌드를 절대 실행하지 않도록 지시받으며, 개발 서버 자체가 미리 보기입니다.

4. 계층화된 가드레일(Guardrails in layers)

범위(Scope). 시스템 프롬프트에는 필수 파일 접근 섹션이 있습니다. 첨부된 폴더만 가능하며 외부 폴더는 안 됩니다.
비밀 정보(Secrets). 내장 무시 목록(.env, .env.*, 그리고 모든 하위 폴더의 동일한 항목)은 항상 팀 정의 글로브(globs)와 병합되어 해당 섹션에 포함됩니다. 에이전트는 이러한 경로가 필요한 요청 부분은 모두 거부하도록 지시받습니다.
되돌리기(Undo). 매 턴 전에 작업 공간을 스냅샷 처리합니다 (사용 가능한 경우 git을 통해, 그렇지 않으면 파일 복사로 처리). 턴을 중지하면 에이전트가 종료되고 스냅샷이 복원됩니다.
신뢰도(Confidence). 에이전트는 모든 변경 사항에 숨겨진 신뢰 수준(매우 낮음부터 매우 높음까지)을 포함하며, 이는 팀에게 태그 형태로 표시되어 검토자가 어디를 더 주의 깊게 봐야 할지 알 수 있게 합니다.
접근 권한(Access). 개발자는 누가 요청을 보낼 수 있는지 선택합니다: 지정된 목록 또는 링크를 가진 모든 사람입니다.

레이어 1과 2에 대한 솔직한 설명: 이들은 에이전트에 대한 지침과 CLI의 작업 공간 설정이며, CLI는 대화형 권한 프롬프트가 건너뛴 상태로 실행됩니다. 이는 OS 샌드박스(sandbox)와 같지 않습니다. 만약 강력한 격리가 필요하다면, 프로덕션 비밀 정보가 없는 머신이나 계정에서 브리지를 실행해야 합니다. 과장하기보다는 명확하게 말하는 것이 낫다고 생각합니다.

5. 병합 버튼은 존재하지 않는다

브리지나 채팅 서버에는 푸시(push), 풀 리퀘스트(pull request), 병합(merge), 배포(deploy) 기능이 없습니다. 한 턴의 결과물은 폴더 내 수정된 파일, 대화 내용, 그리고 실시간 미리보기로 구성됩니다.

개발자는 이 세 가지를 모두 검토한 후, 팀의 일반적인 파이프라인(테스트, CI, 코드 리뷰가 온전하게 유지되는)을 통해 커밋하고 배포합니다. 또는 이를 폐기할 수도 있습니다.

"이제 병목 현상은 인간이 아닌가요?"

개발자의 업무는 '찾기, 편집, 링크 보내기, 기다리기, 반복하기'에서 '보기, 결정하기'로 바뀝니다. 그것이 트레이드오프(trade-off)입니다. 비용이 많이 드는 반복 작업은 에이전트와 요청자에게로 이동하며, 그들은 미리보기가 올바를 때까지 이를 반복합니다. 개발자는 최종적으로 한 번만 확인하게 됩니다.

티켓부터 병합까지 자동화를 원하는 팀이 존재하며, 이를 위한 도구도 있습니다. 이 디자인은 요청하는 사람이 코드를 검토할 수 없고 여전히 배포되는 것에 대한 책임자가 있는 팀을 위한 것입니다.

이것이 해결하지 못하는 것들

로컬 프로젝트 폴더가 필요합니다. 클라우드 IDE에서만 생활하는 팀은 적합하지 않습니다.
개발자를 대체하지는 못합니다. 개발자가 존재하고 결정한다고 가정합니다.
코드 컨텍스트는 여전히 코딩 CLI가 사용하는 어떤 AI 제공업체로 전송되며, 미리보기 트래픽은 Butterneck의 릴레이를 통과합니다. "로컬"이라는 것은 편집 및 런타임이 로컬이라는 의미이지, 기기 외부로 아무것도 나가지 않는다는 의미는 아닙니다.

마무리

인간 참여형(Human-in-the-Loop)은 모델이 더 좋아질 때까지 임시적인 지지대처럼 취급되는 경우가 많습니다. 저는 제품 변경의 경우 이것이 영구적인 설계 선택이라고 생각합니다. 즉, 자유롭게 요청하고, 즉시 미리보고, 의도적으로 배포하는 것입니다.

팀이 코딩 에이전트와 함께 작업하기를 원하는 방식이 이것이라면, Butterneck에서 butterneck.com을 통해 무료 스타터 플랜을 제공합니다.