가드레일과 권한 모델

서브에이전트를 만들고 호출하는 법은 4장에서 손으로 익히게 된다. 그 전에, "이 에이전트가 무엇을 해도 되고 무엇은 안 되는가"를 먼저 정하지 않으면 실습 중에도 실무에서도 사고가 난다. 이 장은 2장에서 잠깐 언급했던 "가드레일"을 실제로 어떻게 설계하는지 다룬다.

왜 가드레일이 필요한가

2장에서 하네스를 "말이 마음대로 아무 방향으로나 달리지 않도록 잡아 주는 마구"에 비유했다. 가드레일은 그 마구 중에서도 특히 "이 방향으로는 절대 가면 안 된다"는 울타리에 해당한다. 서브에이전트가 파일을 읽고 요약하는 정도라면 실수해도 되돌리기 쉽지만, 파일을 삭제하거나 커밋·배포까지 자동으로 하게 되면 실수 하나가 되돌리기 어려운 결과로 이어진다.

문제는 "능력"과 "위험"이 같은 방향으로 커진다는 점이다. 에이전트에게 더 많은 도구·더 넓은 권한을 줄수록 처리할 수 있는 일은 늘어나지만, 잘못 판단했을 때의 피해 범위도 함께 늘어난다. 가드레일은 이 둘을 분리한다. "할 수 있는 일"은 넓게 열어 두되, "사람 확인 없이 실행해도 되는 일"은 좁게 제한하는 식이다.

위험 작업을 세 단계로 분류하기

모든 작업을 똑같은 강도로 통제하면 실무에서 쓸 수 없을 만큼 느려진다. 실제로는 작업을 되돌릴 수 있는 정도에 따라 세 단계로 나눠 다르게 다루는 것이 현실적이다.

이 3단계 분류는 이 핸드북이 참고한 워크스페이스 문서의 실제 규칙과도 일치한다. 5장에서 다룬 /sync 파이프라인이 .pem·.key·.env 같은 민감 파일을 커밋 직전에 가로막는 "Sensitive File Guard"나, 강제 푸시·--no-verify를 명시적으로 금지하는 규칙이 바로 파괴적 작업 단계에 해당하는 가드레일이다.

최소 권한 원칙 — tools 필드

4장 §2 실습에서 만든 reviewer 서브에이전트의 frontmatter를 다시 떠올려 보자. tools: Read, Grep처럼 허용할 도구를 명시적으로 나열했다. 이것이 서브에이전트 단위의 최소 권한 원칙이다. reviewer는 애초에 Write 도구가 없으므로, 프롬프트가 아무리 애매하게 해석돼도 파일을 수정할 방법 자체가 없다.

이 원칙을 실제 사고 시나리오로 보면 왜 중요한지 분명해진다. 만약 reviewer에게 Write 권한까지 습관적으로 열어 뒀다면, "이 파일을 검토하고 개선해줘"처럼 살짝 모호한 요청을 받았을 때 reviewer가 "개선"을 "직접 수정"으로 해석해 원본을 덮어쓸 수도 있다. tools 필드로 권한을 미리 좁혀 두면, 이런 해석 차이가 애초에 사고로 이어지지 않는다. 프롬프트 품질에 기대는 대신 구조적으로 막는 것이다.

사람 승인 게이트

2장에서 오케스트레이터를 "사용자와의 확인이 필요한 지점(게이트)에서 진행을 멈추는 역할"이라고 정의했다. 가드레일 설계에서 가장 중요한 질문은 "그 게이트를 정확히 어디에 둘 것인가"다. 너무 자주 멈추면 에이전트에게 일을 맡기는 의미가 없어지고, 너무 안 멈추면 파괴적 작업까지 조용히 지나가 버린다.

실무에서 검증된 기준은 단순하다. §2의 "파괴적/외부 영향" 단계에 해당하는 작업 직전에는 항상 멈추고, 그 아래 단계는 사후 검토로 충분하다. 예를 들어 /sync 파이프라인은 커밋·푸시·PR 생성까지는 자동으로 진행하지만, PR을 실제로 병합하거나 프로덕션에 배포하는 단계는 별도의 사람 승인을 요구하도록 설계돼 있다. "어디까지는 믿고 맡기고, 어디부터는 반드시 사람이 본다"는 경계선을 명시적으로 그어두는 것이 게이트 설계의 핵심이다.

격리 — worktree와 sandbox

4장 §2의 고급 시나리오(P-1)에서 "같은 Workspace에 에이전트 여러 개를 배정하면 인지적 중첩(cognitive overlap)이 생길 수 있다"고 경고했다. 이것도 가드레일의 한 형태다. 여러 에이전트가 같은 파일·같은 git 이력을 동시에 건드리면, 한 에이전트의 실수가 다른 에이전트의 작업 맥락까지 오염시킬 수 있다.

worktree(격리된 git 작업 디렉터리)나 별도 sandbox 환경에서 각 에이전트를 실행하면, 설령 한 에이전트가 잘못된 판단을 하더라도 그 영향이 자기 작업 공간 밖으로 새어 나가지 않는다. 병렬로 여러 에이전트를 굴릴 때는 "같은 공간을 공유하게 둘 것인가, 물리적으로 나눌 것인가"를 항상 먼저 결정해야 한다.

감사 로그와 관측성

가드레일이 사전 예방이라면, 감사 로그는 사후 추적이다. 완벽한 가드레일은 없으므로, 사고가 났을 때 "언제, 어떤 에이전트가, 어떤 도구로, 무엇을 했는지"를 되짚어볼 수 있는 최소한의 기록이 반드시 필요하다. 5장에서 다룬 memory/MEMORY.md가 세션 간 맥락을 기록하는 용도라면, TaskCompleted 훅으로 실행되는 audit.ts 같은 감사 스크립트는 "규칙을 어긴 변경이 있었는지"를 매번 기계적으로 검사하는 관측성 장치다. 참고로 이 워크스페이스의 훅 배선(2026-08-24 기준)을 정리하면, PreToolUse에서는 gateguard-fact-force.ts(Edit|Write|MultiEdit)와 agent-model-gate.ts(Agent)가, PostToolUse(Write|Edit)와 TeammateIdle에서는 post-write-lifecycle-check.ts가 동작하고, audit.ts는 작업 완료 시점(TaskCompleted)에 실행된다.