휴먼 인 더 루프(Human-in-the-loop) 코딩 에이전트는 보통 하나의 설정처럼 설명됩니다. 편집 전에 도구가 먼저 물어보는 모드 말이죠. 하지만 그것은 하나의 루프일 뿐이며, 가장 작은 단위입니다. 한 개발자의 터미널 안에서, 한 세션 동안만 작동하고, 세션이 끝나면 사라집니다. 모두가 Claude Code를 수동(Manual) 모드로 두었기 때문에 사람이 감독하고 있다고 착각하는 팀이 있다면, 그들이 감독하는 것은 키 입력이지 결과가 아닙니다.
이 가이드는 리뷰 워크플로를 다섯 개의 게이트로 정리합니다. 런타임 내부의 권한 프롬프트부터 공유 기록상의 수락 결정까지이며, 각 게이트에서 누가 결정하고 그 결정이 어디에 기록되는지를 설명합니다. 런타임 게이트는 도구 자체의 문서에서 가져왔습니다. 팀 게이트는 Sharkly를 사용합니다. 누군가의 스크롤백이 아니라 Task에 기록되기 때문입니다. 이 실무에 대한 정의가 먼저 필요하다면, AI 에이전트 프로젝트 관리 가이드에서 이 워크플로가 속한 루프를 다루고 있습니다.
TL;DR
코딩 에이전트를 위한 휴먼 인 더 루프 리뷰 워크플로에는 다섯 개의 게이트가 있습니다. 런타임의 권한 모드, 작업이 Task가 되기 전의 계획 확인, 실행이 언제 시작될 수 있는지 결정하는 실행 경계, 리뷰를 특정 담당자에게 라우팅하는 주의 신호, 그리고 그 담당자가 상태 변경으로 기록하는 수락입니다. 도구 설정인 게이트는 첫 번째뿐입니다. 나머지 네 개는 팀의 결정이며, 실질적인 의미를 가지려면 공유 기록이 필요합니다. 에이전트는 조사하고, 실행하고, 테스트하고, 보고합니다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 수락합니다.
게이트 1: 런타임 내부의 권한 모드
제대로 된 코딩 에이전트는 모두 승인 다이얼을 갖추고 있습니다. Claude Code의 권한 모드는 수동(Manual)로 표시되는 default에서 시작해 편집, 셸 명령, 네트워크 접근 전에 물어보는 단계, acceptEdits, plan, 그리고 분류기(classifier)라는 두 번째 모델이 여러분 대신 행동을 검토하는 auto, 격리된 컨테이너 전용인 bypassPermissions까지 이어집니다. Shift+Tab 또는 --permission-mode로 전환합니다. Codex는 /permissions 명령을 통해 같은 개념을 제공하며, 파일을 편집하거나 명령을 실행할 때 언제 물어보지 않고 진행할지를 설정합니다.
이 게이트는 필요하지만 충분하지는 않습니다. 세션별, 개발자별로 적용되며, 요구사항이 아니라 머신을 보호하고, 팀 동료가 읽을 수 있는 기록을 남기지 않습니다. Pro, Max, Team 요금제에서 Claude Code는 이제 기본적으로 auto 모드로 시작합니다. 분류기가 지친 사람이 예스를 누르는 것보다 더 빠르고 일관되기 때문에 합리적인 선택입니다. 교훈은 다이얼과 싸우지 말라는 것이 아니라, 다이얼을 리뷰라고 여기지 말라는 것입니다.
게이트 2: 계획 확인
첫 번째 팀 차원의 게이트는 코드가 존재하기 전에 일어납니다. Sharkly의 에이전트 채팅에서 플랜(Plan) 모드를 사용하면 에이전트가 검토할 작업을 제안하고, 계획된 Task와 하위 Task는 사람이 제안을 확인한 뒤에만 생성됩니다. 시작하지 않고 확인만 하거나, 확인과 동시에 시작할 수 있습니다.
여기서 범위가 결정되며, 비용이 저렴합니다. 제안된 하위 Task를 수정하는 데는 1분이 걸리지만, 요청하지 않은 리팩터링을 리뷰하는 데는 반나절이 걸립니다. 분석만 원한다면 Explore를 선택한 상태로 두세요. 리더가 목표를 해석하고 다른 에이전트 멤버를 참여시켜야 할 때는 Crew를 사용하고, 하나의 역할로 충분한 작업이라면 단일 에이전트를 사용해 절차를 생략하세요. AI 에이전트와 채팅하거나 Task 할당하기 가이드에서 세 가지 모드를 다룹니다.
게이트 3: 실행 경계
에이전트에게 할당된 Task는 Backlog에 있는 동안에는 시작되지 않습니다. 카테고리가 작업 준비 완료인 상태로 옮기는 것이 실행을 시작하는 행위이며, 완료(completed), 취소(canceled), 중복(duplicate) 카테고리는 최초 실행을 절대 시작하지 않습니다. 따라서 상태 카테고리는 사람이 의도적으로 조작하는 게이트이며, 보드에서 바로 확인할 수 있습니다.
이 게이트를 단순한 형식이 아니게 만드는 두 가지가 있습니다. 각 실행마다 격리된 디렉터리가 주어지고, 저장소 기반 실행은 새 워크트리를 준비하기 때문에, 승인된 실행이 아무도 승인하지 않은 실행에 피해를 줄 수 없습니다. 그리고 실행에는 Task 설명, 최근 댓글, 그리고 에이전트가 선택할 수 있는 상태를 제한하는 Task 유형 Workflow가 함께 전달됩니다. Workflow가 해당 상태를 허용하지 않으면 에이전트는 자신의 작업을 수락 완료로 표시할 수 없습니다. AI 코딩 에이전트와 함께 쓰는 Git 워크트리 글에서 격리 방식에 대해 설명합니다.
게이트 4: 주의 신호
에이전트는 실행을 두 가지 유용한 지점 중 하나에서 끝냅니다. 결과와 함께 끝나거나, 질문과 함께 끝나는 것입니다. Sharkly는 둘 모두를 명명합니다. 에이전트는 사람의 답변을 기다리거나 사람의 리뷰를 기다리는 상태로 Task를 남길 수 있으며, 실패하거나 차단된 작업은 주의 항목(attention item)으로 표시됩니다. 이러한 신호는 담당자를 위해 받은편지함(Inbox)의 주요(Primary) 섹션에 도착하며, 실행 실패는 모든 구독자가 아니라 할당된 담당자에게 전달됩니다.
여기서의 게이트는 라우팅이며, 대부분의 팀이 무심코 틀리는 지점입니다. 채널로 가는 리뷰는 아무에게도 가지 않습니다. Task에서 사람 담당자에게 가고 실행 로그가 한 번의 클릭으로 확인 가능한 리뷰는 나중에 책임을 물을 수 있는 사람에게 갑니다. AI 에이전트 받은편지함 가이드에서 큐 메커니즘을 다룹니다.
답장을 다는 것도 작업을 이어가는 방법입니다. 준비된 에이전트 담당자가 있는 Task에 멤버가 댓글을 남기면 또 다른 실행이 대기열에 추가될 수 있어서, 리뷰 피드백이 두 번째 프로세스를 시작하는 대신 같은 작업을 이어갑니다. 사람을 멘션하거나 전체 멘션을 사용하는 것만으로는 에이전트가 시작되지 않으므로, 사람 대 사람 대화가 에이전트를 깨우지 않습니다.
게이트 5: 기록상의 수락
수락은 사람이 증거를 읽은 뒤 Task 상태를 변경하는 것입니다. 다음 순서로 읽으세요. 설명에 있는 수락 기준, 에이전트가 실행한 검사와 남아 있는 불확실성을 명시한 에이전트의 댓글, 실행 로그, 그다음 diff 순서입니다. 로그에는 실행이 왜 대기열에 들어갔는지, 언제 시작하고 끝났는지, 도구 호출과 런타임 이벤트, 트리거 출처, 실패 세부 정보가 기록됩니다. 이는 변경 사항을 리뷰하는 것과 변경 사항에 대한 이야기를 리뷰하는 것의 차이입니다.
이 게이트를 보호하는 두 가지 규칙이 있습니다. 연결된 풀 리퀘스트를 병합해도 Task 상태는 바뀌지 않으므로, 병합이 수락으로 오해되지 않습니다. 그리고 완료된 Automation 실행은 그 실행을 설명할 뿐, 모든 후속 결과가 올바르다는 약속이 아닙니다. 두 가지 모두 제품 문서에서 바로 나온 것으로, 팀들이 완료(finished)와 올바름(correct)을 계속 혼동했기 때문에 존재합니다.
한 표로 보는 워크플로
| 게이트 | 답하는 질문 | 결정하는 사람 | 기록되는 위치 |
|---|---|---|---|
| 권한 모드 | 이 세션이 그것을 건드려도 되는가? | 개발자 | 공유되는 곳 없음 |
| 계획 확인 | 이것이 올바른 분해인가? | 제안에 대한 사람 | 확인된 하위 Task |
| 실행 경계 | 이 Task가 지금 실행되어도 되는가? | Backlog에서 옮기는 사람 | Activity의 상태 변경 |
| 주의 신호 | 누가 무엇을 살펴봐야 하는가? | Sharkly가 담당자에게 라우팅 | 받은편지함 주요 섹션과 Task |
| 수락 | 결과가 올바른가? | 사람 담당자 | 특정인의 상태 변경 |
게이트를 더 넓게 열어야 할 때
모든 Task가 다섯 번의 관문을 거칠 가치는 없으며, 그렇지 않은 척하는 것이야말로 리뷰가 형식이 되는 길입니다. 저장소 감사 같은 읽기 전용 작업에는 게이트 1과 게이트 5만 필요합니다. 테스트가 포함된 의존성 업데이트처럼 격리된 워크트리에서 되돌릴 수 있는 작업은 계획 확인을 건너뛸 수 있습니다. 일정에 따라 실행되는 Automation은 사람이 언제 리뷰하거나 결정해야 하는지를 지침에 명시해야 하며, 누구든 그 일정에 의존하기 전에 수동으로 실행하고 점검해야 합니다. Sharkly의 Automation 가이드에서 이를 다룹니다.
공개 인터페이스를 변경하거나, 데이터를 건드리거나, 명령 한 번으로 되돌릴 수 없는 작업에는 다섯 게이트를 모두 유지하세요. 그리고 어디서나 한 가지 규칙을 지키세요. 모든 에이전트 Task에는 이름이 지정된 사람 담당자를 두는 것입니다. Sharkly는 사람의 책임과 에이전트 실행을 의도적으로 분리하므로, 하나의 Task에 사람과 에이전트가 동시에 할당될 수 있습니다. 책임은 위임되지 않으며, 기록은 누가 그것을 지고 있는지 보여주어야 합니다.
휴먼 인 더 루프가 아닌 것
그것은 터미널을 지켜보는 사람이 아닙니다. 지친 리뷰어가 뒤에 앉아 있는 권한 프롬프트도 아닙니다. 그리고 완료(Completed)라고 적힌 상태도 아닙니다. Automation은 팀의 판단이 필요한 지점에서 멈추고, 완전한 컨텍스트와 검사 가능한 증거를 갖춘 결과물을 돌려줍니다. 이 한 문장이 워크플로 전체이며, 게이트는 그것이 강제되는 지점일 뿐입니다. Sharkly는 Claude Code, Codex 또는 다른 실행 도구를 대체하는 것이 아니라, 이러한 결정을 기록하는 계층입니다.
FAQ
Claude Code의 auto 모드는 루프에서 사람을 제거하나요? 권한 프롬프트에서 사람을 제거합니다. 분류기는 여러분의 요청에 대해 행동을 검토하지만, 결과가 요구사항을 충족했는지는 검토하지 않습니다. 게이트 2부터 5까지는 여전히 사람의 몫입니다.
실행 도중 에이전트를 어떻게 멈추나요? 대기 중이거나 실행 중인 실행은 취소할 수 있습니다. Task를 Canceled 또는 Duplicate 상태로 옮겨도 활성 실행이 중지됩니다. Completed로 옮기는 것은 중지되지 않으므로, 에이전트가 아직 작업 중이라면 먼저 취소하세요.
리뷰어는 누가 되어야 하나요? Task의 사람 담당자입니다. Sharkly는 리뷰 대기 및 실패 신호를 그 사람에게 보내므로, 모든 에이전트 Task에는 담당자를 한 명 지정해야 합니다. Sharkly의 에이전트 가이드에서 두 개의 할당 슬롯을 설명합니다.
새 Task 없이 리뷰 피드백을 에이전트에게 돌려줄 수 있나요? 네. Task에 댓글을 달면 할당된 에이전트에 대한 후속 실행이 대기열에 추가될 수 있으며, 빠르게 이어지는 댓글은 하나로 합쳐져 중복 실행이 생기지 않습니다.
