에이전트 역할 분리 — 입력을 좁혀 성공 기준을 가른다

언제: 실패를 기계적으로 열거할 수 있고, 그걸 반복해서 고쳐야 할 때.

같은 모델이라도 입력이 다르면 무엇을 성공으로 보는지가 갈린다. 구현자는 원본과 자기 추론을 받아 머지되기를 원하고, 리뷰어는 diff 만 받고 이 코드는 틀렸다고 가정하라는 지시를 받아 버그를 찾기를 원한다. 그래서 입력 자체를 잘라야 한다. 64개 병렬은 결과지 원인이 아니다 — 일을 성립시킨 건 컨텍스트 비대칭, 기계적으로 생성되는 큐, 언어를 바꿔도 통하는 합격 판정 기준(테스트 오라클) 셋이다. 판정 기준이 없으면 여기서 멈춘다: Bun 의 Rust 포팅에는 4,174개 파일 6만여 개 expect() 의 TypeScript 테스트가 있었고 스킵·삭제가 0개였다. 없으면 리뷰어를 둘 붙여도 검증되지 않은 코드를 빠르게 생산할 뿐이라, 실패를 열거 가능한 상태(타입 에러 목록·스냅샷·시각 회귀)를 먼저 만든다.

한꺼번에 세우지 않는다. 1 adversarial-reviewer 하나만 만들어 memory: project 로 몇 주 돌린다 — 도구는 Read·Grep·Glob 뿐, diff 하나를 받아 틀린 이유만 찾고 최소 3개의 실패 시나리오를 낸다. 2 쌓인 지적 패턴이 거절 규칙 목록이 된다: 한 문단짜리 주석으로 우회를 정당화하면 코드가 틀린 것, 스텁·TODO·조건부 비활성화로 컴파일만 통과시킨 건 미완성, 테스트를 고쳐 통과시킨 변경은 무조건 거절. 3 그 뒤에 porter(구현, isolation: worktree)와 fixer(지적만 반영, 새 기능 금지)를 붙인다. porter 의 변경은 .work/<id>.diff 로 나가고 리뷰어는 diff 경로와 원본 경로만 받는다. 큐는 세션 밖에서 돈다 — 실패 목록을 파일로 만들고 claude -p 를 반복한다.

확인: 리뷰어가 tsc·eslint가 통과시키는 지점을 잡고 있는가. 그게 이 역할의 존재 가치 전부다 — effect 의존성의 의미 변화, 이벤트 핸들러의 eager/lazy, ??와 ||의 단축평가 차이, 리렌더 타이밍, 정리 함수 누락. 린터가 잡을 걸 잡고 있으면 프롬프트가 헐거운 것이다.

컨텍스트 비대칭은 저절로 유지되지 않는다 — 위임 프롬프트를 부모가 쓰므로 그냥 두면 구현 근거를 요약해 리뷰어에게 넘긴다. .work/<id>.diff 를 경유시키고 리뷰어에게는 diff 경로와 원본 경로만 준다는 걸 CLAUDE.md 규약으로 박는다. 역할 분리를 프롬프트로 하면 무너지니 리뷰어 tools 에서 Edit·Write 를 빼 권한으로 막는다. 같은 모델 둘은 실패 상관관계가 높아 리뷰어를 둘 둘 거면 하나는 model 을 다르게 준다. -p(비대화형)에서는 fork mode 가 꺼져 subagent 가 포그라운드로 도는 경우가 있어 병렬은 셸에서 잡는다. 병목은 모델이 아니라 디스크 IOPS 였다 — 느린 grep 하나가 디스크를 몇 분씩 얼렸다.

#claude-code#subagent#code-review#llm
#579

에이전트 코딩 환경 — 워크트리·포트·자격증명

언제 — 워크트리를 여럿 띄웠는데 서로의 서버를 죽이거나, 의존성 검증이 거짓 통과하거나, 새 워크트리에서 첫 명령이 실패할 때.

질문 아니오 예
24시간 켜진 별도 호스트가 있나 R8 폐기 R8까지
폰·외부 머신에서 세션을 이어받나 R4를 localhost 포트 격리로 축소 R4를 프록시 + tailnet URL로
네이티브 API(Vision·Swift 바인딩)에 의존하나 R5의 컨테이너 격리 가능 컨테이너 불가 — 호스트 직접 실행 + 토큰 축소로만

실행 순서: R6 dotfiles 리포(나머지 전부의 저장소) → R5-1 토큰 축소(30분·1회·효과 최대, 격리 설계를 기다릴 이유가 없다) → R1 워크트리 위치(훅 하나) → R2·R3(R1 의 setup() 채우기) → R7 설계 결정 → R4 프리뷰 서버(외부 접근이면 프록시) → R5-2 실행 격리(네이티브 의존이면 컨테이너 불가) → R8 원격 호스트(24시간 호스트가 있을 때만). 각 단계가 독립적으로 가치를 내므로 중간에 멈춰도 된다. 프로젝트 종류가 섞이면 격리 정책도 프로젝트별로 가른다 — 단일 정책은 가장 약한 쪽으로 수렴한다. 유통기한: R1 의 절반은 언젠가 설정 한 줄로 대체되지만 R2·R3·R5·R7 은 워크플로 설계 문제라 대체되지 않는다.

R1. 워크트리를 프로젝트 밖으로

기본 위치 <project>/.claude/worktrees/<name> 은 프로젝트 안이라, 워크트리에서 node_modules 해석이 상위 프로젝트까지 올라가 의존성 삭제·다운그레이드 검증이 거짓 통과하고, tsc project references·vitest glob·rg·find 같은 재귀 도구가 전부 워크트리로 들어간다. AGENTS.md 에 적는 건 확률적 층이라 WorktreeCreate·WorktreeRemove 훅으로 내린다 — 이 훅은 기본 git 동작을 증강이 아니라 대체한다. 훅은 ~/.worktrees/<project>/<name> 에 만든다. stdout 은 경로 한 줄 전용이라 git worktree add 를 포함한 다른 출력은 전부 >&2 로 보내고, 비영 종료는 생성 중단이며 JSON 반환도 못 한다. 훅은 settings.local.json 이 아니라 settings.json 에 둔다.

확인 — 훅에 WorktreeCreate 입력을 직접 넣으면 경로 한 줄만 나온다. 그 워크트리에서 의존성을 resolve 하면 워크트리 안 경로가 나온다 — 밖이면 격리가 안 된 것이다.

R2. 워크트리별 결정적 포트

브랜치(워크트리) 이름을 shasum 으로 해시해 숫자만 6자리 뽑고, 6000 으로 나눈 나머지에 3100 을 더해 PORT 로 .env.local 에 쓴다. 같은 브랜치는 항상 같은 포트라 재현되고 URL 을 기억할 수 있다. macOS 엔 md5sum 이 없으니 shasum·cksum 을 쓴다. 10# 은 선행 0 을 8진수로 읽어 간헐적으로 죽는 걸 막는다. 해시 충돌은 드물지만 결정적이라 한 번 나면 그 브랜치쌍은 영원히 충돌한다.

R3. gitignore 된 파일 승계

새 워크트리엔 .env·로컬 인증서·빌드 캐시가 없어 에이전트가 첫 명령에서 실패하고 원인을 추측하다 세션 절반을 태운다. 승계 목록을 리포의 .worktreeinclude 에 선언하고 훅이 rsync 로 복사한 뒤 pnpm install 한다. 심링크는 금지 — 워크트리에서 값을 바꾸면 메인과 다른 워크트리 전부가 동시에 오염된다. 승계 목록이 곧 유출 경로라 자격증명을 넣으면 워크트리 개수만큼 사본이 늘므로 WorktreeRemove 에서 확실히 지운다. 설치가 오래 걸리면 훅 timeout 을 늘린다 — 타임아웃은 생성 실패다.

R4. 프리뷰 서버 규약

에이전트가 주는 URL 은 실제로 열려야 하고 secure context 여야 한다(crypto.subtle·클립보드·서비스 워커). 로컬 전용이면 http://localhost:<port> 가 이미 secure context 라 R2 포트만 있으면 되고, AGENTS.md 에 .env.local 의 PORT 를 쓰고 점유돼 있으면 죽이지 말고 보고하라고만 적는다. 외부 접근이면 0.0.0.0 바인딩 + IP 접근은 secure context 가 아니다. 프로젝트 dev 스크립트를 고치지 말고(환경 관례가 리포에 침투한다) 래퍼 바이너리를 만들어 하네스가 부르게 한다. 이 규약은 확률적 층이라 결정적으로 하려면 PreToolUse 훅에서 dev 명령을 잡아 차단하거나 래퍼로 치환한다.

R5. 자격증명 축소가 먼저다

VM 으로 파일시스템 경계를 그어도 그 안에 전권 토큰을 넣으면 토큰은 계정 전체에 닿는다 — 실제 폭발 반경은 VM 이 아니라 계정이다. 위협은 사고만이 아니라 prompt injection 이다: 이슈 본문·PR 코멘트·의존성 README 를 읽는 순간 외부 텍스트가 명령이 된다. 순서: 1 토큰 축소(30분·1회) — fine-grained PAT, 대상 리포만, Contents·PR·Issues 만 read/write, Workflows 와 Administration 제외, 만료일. 2 실행 격리 — 순수 웹/Node 만 devcontainer 에서 bypassPermissions, 네이티브 의존은 컨테이너 불가라 기본 권한. 3 주입 표면 좁히기 — 신뢰할 수 없는 텍스트를 읽는 세션과 쓰기 권한 세션을 나눈다. 컨테이너를 미룰 때 비용이 거의 없는 토큰 축소까지 미루지 않는다.

확인 — gh auth status 로 스코프를 본다.

R6·R7. 전역 설정과 설계 결정을 세션 밖으로

R6: settings.json·훅·스킬·AGENTS.md 가 홈에 흩어져 이력도 백업도 없다. private 리포 하나 + 심링크로 끝난다 — 머신이 하나면 chezmoi 는 과잉이지만 이력과 백업은 머신 수와 무관하다. 하네스가 파일을 rename 으로 대체하면 심링크가 깨지니 ls -l 로 확인하고, .gitignore 에 .local.json·.env·credentials 를 넣고 첫 커밋 전 git diff –cached 를 훑는다. R7: 트랜스크립트가 설계 결정의 유일한 기록일 때 세션 히스토리 백업은 틀린 프레이밍이다 — 신호 대 잡음비가 최악이라 참조 대상이 안 된다. 기각한 대안이 있었을 때만 코드와 같은 커밋에 docs/decisions/NNNN-slug.md 를 추가한다: 맥락·결정·기각한 대안과 이유·결과, 한 화면 이내, 결론만.

확인 — 나중에 “왜 이렇게 했지?“를 물었을 때 리포 안에서 답이 나오면 성공. git log 와 트랜스크립트를 뒤져야 하면 실패.

R8. 원격 호스트 (조건부)

24시간 켜진 호스트가 있으면 Tailscale 로 SSH·HTTPS 를 호스트명으로 연다. 포트포워딩 대신 이걸 택하는 이유는 HTTPS 인증서로 secure context 를 얻기 때문이다. 랩탑을 닫아도 지속되려면 하네스의 원격 세션 모드를 쓰고 tmux 는 최후 수단이다. 머신이 둘이 되니 chezmoi 가 정당화된다. 다만 워크트리·포트를 아무리 격리해도 병렬화의 상한은 사람의 diff 리뷰 대역폭이다 — 4개 동시 실행은 4개의 리뷰 큐를 만들 뿐이니 병렬도를 올리기 전에 리뷰 처리량을 먼저 잰다.

#claude-code#git-worktree#hooks#dotfiles#security
#583

에이전트 신뢰 구축 — 검증 경로부터 자동 머지까지

# 원칙 위반 신호
P1 에이전트가 스스로 실행해서 확인할 수 없는 작업은 위임하지 않는다 스크린샷을 복붙하고 있다
P2 구현자와 검증자는 다른 컨텍스트여야 한다 “수정 완료했습니다”를 구현자가 말한다
P3 소프트 규칙(문서·프롬프트)은 신뢰의 근거가 아니다 CLAUDE.md 에 적었는데 안 지킨다
P4 가장 짧은 경로가 정답 경로가 되도록 설계한다 에이전트가 매번 우회로를 찾는다
P5 사람이 리뷰로 강제하는 불변식은 전부 코드 스멜이다 같은 지적을 두 번 했다

R00·R01. 거르고 구간 확정

먼저 R00 으로 거른다: 자동 검증이 닿지 않는 도메인(실제 예약·결제·외부 파트너), 규칙이 코드 밖에 있는 영역(규제), 강제 계층 13층을 바꿀 권한이 없는 코드베이스는 자동화 대상에서 뺀다 — 방법론을 약화하지 않고 대상을 좁힌다. 남은 곳에서 구간을 오른다. 0 불신(출력을 매번 다 읽음, 병렬 01) → R02 검증 스킬과 R03 feature map. 1 관찰(툴 콜을 읽으며 실패 수집, 병렬 13) → R04 실패 모드 승격과 R05 eval. 2 위임(검증 경로가 있고 판정을 에이전트가 냄, 병렬 38) → R06 강제 계층, R07 리뷰를 하드 제약으로, R08 그린필드 가드레일. 3 자동화(하드 제약이 CI·hook 에, 병렬 8+) → R09 병렬화 기준. 4 무감독(자동 머지 후 사후 리뷰) → R10 자동 머지 진입 조건. 신뢰는 인프라의 결과라 순서를 건너뛰면 토큰만 태운다. 판정 질문: 지금 PR 을 읽지 않고 머지하면 문제를 며칠 뒤에 아는가 — 모르면 구간 0.

확인 — “지금 에이전트가 만든 PR 을 읽지 않고 머지한다면, 문제가 생겼을 때 며칠 뒤에 알게 되는가?” “모른다”면 구간 0이다.

R02. 검증 스킬 부트스트랩

먼저 사람이 손으로 한 번 한다: dev 서버 기동 → 특정 화면 도달 → 관찰. 여기서 막히면 에이전트도 막힌다. 재료는 헤드리스 기동 명령, 조작 채널(CDP·Playwright MCP), 관찰 채널(콘솔·네트워크·DOM 스냅샷). 그 과정을 boot.sh·snapshot.sh 로 스크립트화해 .claude/skills/verify-app/ 으로 감싸고, 출력 계약을 고정한다. cannot_verify 를 1급 값으로 둔다 — 없으면 pass/fail 을 억지로 고른다. evidence 에 코드 인용이 들어가면 검증이 아니다. 구현 에이전트를 같이 만들지 않는다 — 검증 스킬을 다듬을 동기가 사라진다. 트레이스 수집도 처음엔 넣지 않는다.

{
  "verdict": "pass | fail | cannot_verify",
  "steps_taken": ["실제 실행한 명령"],
  "evidence": ["관찰한 원문 출력"],
  "unverified": ["실행으로 확인 못 한 항목"]
}

확인 — 같은 버그를 3번 던졌을 때 steps_taken 이 일관되면 통과.

R03. feature map

검증 스킬만 있으면 에이전트는 앱을 실행할 수는 있지만 그 앱이 뭔지 모른다. 라우팅 정의와 최상위 레이아웃부터 읽고, 전부가 아니라 문의가 많은 화면 10개만 기록한다. 화면마다 사용자가 부르는 이름(컴포넌트명 아님), 도달 경로(URL + 클릭 순서), 선택자(없으면 없음), 담당 디렉터리, 진입 조건(인증·권한·데이터 상태). 진짜 산출물은 선택자 없음 목록이다 — 검증 자동화가 어디서 막히는지가 거기 나오고, 그게 다음 스프린트의 작업이다.

R04. 실패 모드를 스킬로 승격

툴 콜과 thinking 블록을 펼쳐 읽고 실패를 다섯 유형으로 나눈다. 미탐색(읽지도 않고 원인 단언) → 스킬: 추측 전 검색 강제. 조기 확신(첫 가설을 검증 없이 채택) → 스킬: 가설 2개 + 배제 근거. 도달 실패(UI 에서 기능까지 못 감) → R03 보강. 도구 부재 → R02 확장. 범위 이탈(시키지 않은 리팩터링) → R06 하드 제약. 같은 유형이 3회 이상 나올 때만 스킬로 만든다. 스킬 하나에 유형 하나, 하지 마라보다 대신 이걸 해라, description 에 언제 쓰지 말아야 하는지 한 줄.

R05. eval 하네스

코디네이터가 기대 동작이 아니라 채점 항목으로 루브릭을 먼저 만든다. 서브에이전트를 각각 독립 디렉터리에서 실행하고, 다른 모델의 judge 로 채점한다 — 같은 모델은 자기 출력에 후하다. 점수를 기록하고 스킬을 고쳐 다시 돈다. 반복은 3회까지, 못 가면 스킬 설계를 의심한다. 에이전트는 평가받는 걸 감지하면 행동이 바뀌므로 디렉터리명·파일명·프롬프트 어디에도 eval·test·평가 를 넣지 않고 평범한 프로젝트 복제본처럼 보이게 한다.

R06. 강제 계층 배치

강제 수단을 강한 순서로 놓으면 1 코드베이스 구조(디렉터리 규약, feature 코로케이션 — 에이전트는 기존 패턴을 복사한다), 2 타입 시스템(strict, 브랜디드 타입), 3 CI·린트·의존성 검사, 4 hooks(PreToolUse 차단, 로컬), 여기까지 하드. 5 rules·skills·CLAUDE.md 는 소프트, 6 코드 리뷰는 최악. 5·6 만 있으면 무너지는 건 시간 문제다. hooks: PreToolUse 는 exit 2 로 차단하고 사유가 stderr 로 가 자가 수정된다, PostToolUse 는 변경 파일에 한정한다(전체 타입체크는 루프를 끊는다), SubagentStop 은 출력 계약 위반을 반려한다. 하드 후보: 신규 파일 useEffect 금지, 컴포넌트의 fetch 직접 호출 금지, feature 간 cross-import 금지, any·as 신규 추가 금지, 왜가 없는 주석 금지.

R07. 리뷰 코멘트를 하드 제약으로

같은 지적을 두 번 하는 순간이 트리거다. PR 코멘트에서 시작해 CLAUDE.md 규칙(소프트, 임시) → 린트·hook(하드, 목표) → 타입으로 표현 불가능하게(최선) → 구조적으로 제거(최고) 로 올린다. 판단은 위에서부터: 애초에 불가능하게 만들 수 있나(API 설계) → 타입으로 막을 수 있나 → 린트·hook 으로 막을 수 있나 → 셋 다 안 되면 정말 안 되는지, 귀찮은지 묻는다. 귀찮다면 아직 안 된 게 아니다.

R08. 그린필드 가드레일

브라운필드에는 이미 컨벤션과 가드레일이 있어 에이전트가 그걸 따른다. 그린필드에서 가드레일 없이 태스크를 주면 에이전트는 가장 편한 방법으로 풀고, 시간이 지나면 지름길에 최적화된 사람이 이해 못 하는 코드베이스가 남는다. 코드 한 줄 쓰기 전에: feature 코로케이션(작업의 80% 가 한 디렉터리에서), 의존성 경계 + CI 검사, 명사 정의(에이전트는 이름이 있는 것을 복사한다), strict 최대치(나중에 켜는 건 사실상 불가능), 최단 경로 = 정답 경로. 새 기능 하나를 시켜 건드린 디렉터리가 3개를 넘으면 구조가 잘못됐다.

확인 — 새 기능 하나를 시켜보고 몇 개 디렉터리를 건드렸는지 센다. 3개를 넘으면 구조가 잘못됐다.

R09. 병렬화 기준

서로 다른 feature 디렉터리나 다른 앱이면 동시에 돌린다. 공용 타입·디자인 토큰·API 클라이언트는 직렬로 강제한다 — 병렬 이득이 거의 없고 머지 충돌 비용만 는다. 마이그레이션·스키마 변경은 단독 실행. 동시 개수는 1시간에 리뷰 가능한 PR 수 곱하기 자동 검증 통과율을 넘지 않는다. 통과율이 50% 면 개수를 늘려도 사람 병목이 그대로라, 개수를 늘리기 전에 통과율을 올린다.

R10. 자동 머지 진입 조건

전제: 자동 머지 대상은 본인이 재설계한 코드베이스고, 같은 회사의 기존 코드베이스에는 하지 않는다(회귀가 계속 난다) — 자동 머지는 에이전트 신뢰의 결과가 아니라 아키텍처 저작권자의 특권이다. 여섯 가지가 전부 예여야 한다: 아키텍처를 설계했거나 완전히 이해한다, 위반 시 CI 가 빨개지는 하드 제약이 5개 이상, cannot_verify 비율 20% 미만, 롤백 5분 안, 장애를 24시간 안에 자동 인지, PR 이 원자적. 위험은 폭발 반경 × 발견 지연 × 되돌리기 비용이다. 내부 운영 도구는 가능, 공개 웹(SEO)은 인덱싱 회복이 느려 신중, 결제·예약·인증은 하지 않는다 — 실패한 사용자는 롤백으로 돌아오지 않는다. 영역마다 신뢰 수준이 달라도 된다.

#claude-code#agent#verification#hooks#code-review
#584