Claude Code 서브에이전트와 검증 하네스로 설계 신뢰도를 높인다

Claude가 “구현을 완료했습니다”라고 말해도 그게 맞다는 뜻은 아니다. 에이전트는 품질이 평범해도 자기 작업을 자신 있게 칭찬하는 경향이 있다. 그래서 좋은 구조는 책임을 잘게 나누고, 만든 것과 검증하는 것을 분리하며, 최종 결정권은 사람에게 남긴다. 앞 글에서 코어 루프와 Context·Permission·Tool 하네스를 다뤘다. 이번에는 서브에이전트, 세션 영속성, 검증 하네스를 본다

서브에이전트는 그룹 채팅이 아니다

서브에이전트를 여러 AI가 단체 채팅으로 대화하는 구조로 오해하기 쉽다. “너는 파일 볼게, 나는 테스트 볼게, 너는 리팩토링해” 같은 그림을 떠올린다. 실제 구조는 다르다. 메인 작업 공간과 분리된 작은 작업실을 따로 만들어, 거기서 독립적으로 일하게 하는 구조다

여기서 두 용어를 먼저 정리한다. Parent Context는 메인 Claude Code 세션이 보고 있는 전체 작업의 맥락이다. 지금까지의 대화, 프로젝트 규칙, 읽은 파일, 수정한 파일 목록, 실행한 명령 결과, 현재 목표가 모두 여기에 담긴다. transcript는 작업 기록 파일이다. 어떤 대화를 했고 어떤 도구를 썼고 어떤 결과가 나왔는지 남긴 로그다

서브에이전트는 부모가 특정 작업만 떼어 맡기는 보조 작업자다. 흐름은 이렇다

Parent Agent (메인 작업 공간)
  └─ 특정 작업만 위임
        Subagent (분리된 작업실)
          - 자기 작업만 독립적으로 수행
          - 별도 transcript에 기록
          - 끝나면 요약 결과만 반환
  ← 요약 결과 수신

서브에이전트는 자기 작업 기록 전체를 부모에게 넘기지 않는다. 요약만 돌려준다

왜 분리하는가

모든 에이전트가 같은 컨텍스트를 공유하면 두 가지 문제가 생긴다

첫째, 컨텍스트 오염이다. Claude Code의 컨텍스트 윈도우는 한계가 있다. 서브에이전트가 읽은 모든 파일, 실패한 시도, 중간 추측까지 부모로 들어오면 Parent Context가 거대해진다. 그러면 부모가 중요한 정보를 놓치거나 오래된 맥락에 끌려간다. 서브에이전트가 자기 작업은 따로 하고 요약만 반환하면, 부모는 깨끗한 컨텍스트를 유지한다

둘째, 권한 격리다. 서브에이전트가 생겼다고 부모의 모든 권한을 그대로 물려받는 건 아니다. 부모는 전체 방향을 정하고 사용자와 상호작용하며 최종 판단을 내린다. 서브에이전트는 제한된 작업만, 필요한 컨텍스트만 쓴다. 이렇게 해야 서브에이전트가 과한 권한으로 폭주하는 것을 막는다

예를 들어 테스트 실패 원인을 찾는 작업이라면, 서브에이전트가 이 파일이 원인인지 저 파일이 원인인지 따로 시험하고 로그를 확인하고 가설을 바꿔 본다. 그 모든 시행착오를 부모에게 넘기지 않고, 최종 원인과 추천만 요약해 돌려준다

책임 분리는 좋은 설계의 다른 이름

서브에이전트가 큰 작업에서 작은 작업을 떼어 내듯, 좋은 설계도 큰 책임을 작은 책임으로 나눈다. 배송비 계산기를 설계한다면 이렇게 나눈다

DeliveryFeeService (조립과 흐름)
  ├─ 입력 검증        (음수 거리, 빈 도시, 잘못된 고객 타입)
  ├─ 기본 배송비 계산  (도시·거리 기반)
  ├─ 추가 요금 계산    (날씨, 시간대)
  ├─ 할인 계산        (멤버십, 쿠폰, 무료 배송 기준)
  └─ 결과 반환        (최종 배송비, 음수 금지)

나쁜 설계는 이 모든 책임을 하나의 거대한 함수에 몰아넣는 것이다. 함수는 입력을 받아 출력을 내보내는 단위다. 한 함수가 검증도 하고 계산도 하고 할인도 하고 결과까지 만들면, 한 군데를 고칠 때 전체를 건드리게 된다. 유지보수 비용이 오르고, 정책 하나가 바뀔 때마다 함수 전체를 다시 읽어야 한다. 책임을 나눠 두면 날씨 정책이 바뀔 때 추가 요금 모듈만 손대면 된다

append-only JSONL – 기록은 덮어쓰지 않는다

Claude Code는 대화와 작업 기록을 계속 저장한다. 기존 기록을 지우고 새로 쓰는 방식이 아니라, 끝에 계속 이어붙이는 방식이다. 이 방식 덕분에 이전 세션을 다시 열거나, 복사해 이어가거나, 특정 시점으로 되감을 수 있다

JSONL은 JSON Lines의 줄임말이다. 한 줄에 하나의 기록을 JSON 형태로 저장한다. 세션은 대략 이런 줄들이 쌓인 구조다

1. User Prompt          "배송비 계산기 만들어줘"
2. Assistant Response    파일을 읽고 Order 클래스를 제안
3. Tool Use              파일 읽기
4. Tool Result           읽은 내용
5. Assistant Response    클래스 설계 제안
6. User Feedback         "비 오는 날 추가 요금 넣어줘"
7. New Decision          이전 설계를 수정하기로 결정

여기서 3번 제안이 마음에 안 들어도, 3번을 지우고 다시 쓰지 않는다. 아래에 “이전 설계를 수정함”이라는 새 줄을 붙인다. 기존 줄은 그대로 두고 새 줄만 추가한다. 이것이 append-only 규칙이다. 기존 데이터를 수정하지 않으니 잠금이나 손상 위험이 없고, 전체 이력이 감사 가능한 상태로 남는다

한 가지 주의할 점이 있다. 세션을 되감거나 복사할 수는 있지만, 이전에 허용했던 위험한 권한까지 그대로 복원되지는 않는다. 기록은 이어지되 권한은 다시 확인한다

생성과 평가를 분리하라

논문은 에이전트가 자기 작업을 과신하는 경향 때문에 생성(Generation)과 평가(Evaluation)를 분리해야 한다고 말한다. 신뢰할 수 있는 루프는 맥락 수집, 액션 수행, 결과 검증을 모두 포함한다

배송비 계산기로 보면 두 일은 이렇게 갈린다

구분하는 일
Generation정책 구현, 검증기 구현, 서비스 구현
Evaluation정상 주문 테스트, 비 오는 날 요금 테스트, 무료 배송 기준 테스트

“구현했다”는 말과 “맞게 동작한다”는 말은 다르다. 만든 쪽과 검증하는 쪽을 분리해야 과신을 걸러낼 수 있다

Layered Control – 안전은 한 겹이 아니다

Claude Code는 안전을 한 장치에만 맡기지 않는다. 위험한 행동은 처음부터 모델에게 보이지 않게 하고, 보이더라도 권한을 확인하고, 권한이 있어도 샌드박스 안에서 실행하고, 그 사이를 훅이 가로막는다. 여러 겹의 통제가 겹쳐 있다

User Prompt
  → Tool Pre-filtering   위험·미허용 도구를 모델에게 아예 안 보여줌
  → Permission Rule      액션마다 허용/확인/거부 판단
  → Auto Safety Classifier  ML 기반으로 위험도 추가 판단
  → Pre-tool-use Hooks   도구 실행 전후 개입
  → Shell Sandbox        파일·네트워크 접근 범위 제한
  → Tool Execution       실제 실행
  → Session Transcript   기록 (임시 권한은 다음 세션에 자동 승계 안 함)

공항 보안과 닮았다. 항공권을 확인하고, 여권을 확인하고, 수하물을 검사하고, 몸수색을 하고, 탑승구에서 다시 확인한다. 한 번이 아니라 여러 단계에서 반복해 확인한다

이 발상을 배송비 계산기 검증에 옮기면 다섯 겹의 레이어가 된다

레이어검증 내용
1. 타입입력 타입을 제한한다
2. 입력음수 금액 금지, 음수 거리 금지, 도시 필수
3. 정책무료 배송 기준, 할인 적용 순서, 요금 적용 조건
4. 결과최종 배송비는 음수가 될 수 없다
5. 테스트happy path와 예외 케이스를 함께 검증

안전장치를 하나에 의존하지 않고 여러 겹으로 겹치는 것이 핵심이다

최종 결정권은 사람에게 있다

논문이 꼽은 Claude Code의 다섯 가지 설계 동기는 인간 결정 권한, 안전과 보안, 신뢰할 수 있는 실행, 능력 증폭, 맥락 적응성이다. 이 중 인간 결정 권한이 deny-first 평가, 점진적 신뢰 스펙트럼, append-only 상태, 외부화된 정책, 규칙보다 가치를 끌어낸다

사람은 액션을 관찰하고, 승인하거나 거부하고, 진행 중인 작업을 중단하고, 사후에 감사할 수 있다. Claude가 아무리 강해져도 최종 의사결정권은 사람에게 남는다. 설계에서도 마찬가지다. Claude는 설계를 제안할 수 있지만, 어떤 요구사항을 받아들이고 어떤 제약을 우선하고 어떤 패턴이 과한지 판단하는 일은 사람의 몫이다. Claude가 만든 결과를 두고 이 설계가 지금 요구사항에 맞는지, 과하게 복잡하지는 않은지, 검증이 가능한지를 따지는 능력이 곧 설계자의 권한이다

정리

한 줄로 요약하면, 신뢰할 수 있는 설계는 책임을 나누고 생성과 평가를 분리하며 최종 판단을 사람이 쥔다. Claude가 “완료했습니다”라고 말하면, 바로 받아들이지 말고 검증 레이어를 통과했는지부터 확인하면 된다. 만든 사람과 검증하는 사람이 같으면 과신을 거를 수 없다

출처와 참고자료