길리랩blog

Claude Code 중첩 컨텍스트와 권한·서브에이전트 운영 설계

Claude Code의 중첩 컨텍스트, 세분화 권한, Auto Mode 분류기와 헤드리스 CI/CD 운영 구조를 실무 관점에서 다룬다.

2026-08-14 · 최초 발행 2026-08-02

Claude Code v2.1.170+에서 눈여겨볼 변화는 에이전트가 무엇을 읽고, 어떤 도구를 실행하며, 언제 작업을 다른 에이전트에 넘길지를 더 세밀하게 통제할 수 있게 됐다는 점이다. 중첩 .claude 디렉토리, Tool(param:value) 권한 문법, 강화된 Auto Mode 분류기는 각각 컨텍스트 격리와 최소 권한, 작업 분리를 담당한다. 헤드리스 실행과 CI/CD 통합까지 연결하면 대화형 코딩 도구를 넘어 자율 에이전트 운영 구조로 확장된다.

모노레포 안에서 컨텍스트 경계 나누기

기존 Claude Code는 프로젝트 루트의 단일 .claude/ 디렉토리를 인식했다. v2.1.170+에서는 디렉토리를 중첩할 수 있어, 모노레포의 각 서브프로젝트에 독립적인 지침과 스킬을 둘 수 있다.

monorepo/
├── .claude/
│   ├── CLAUDE.md          # 전역 프로젝트 지침
│   ├── skills/            # 전역 스킬 정의
│   └── settings.json      # 전역 권한 설정
├── backend/
│   └── .claude/
│       ├── CLAUDE.md      # 백엔드 특화 지침
│       └── skills/        # 백엔드 전용 스킬
└── frontend/
    └── .claude/
        ├── CLAUDE.md      # 프론트엔드 특화 지침
        └── skills/        # 프론트엔드 전용 스킬

컨텍스트는 현재 작업 디렉토리에서 시작해 부모 디렉토리 방향으로 역순 탐색한다. 하위 디렉토리의 설정은 상위 설정을 오버라이드하고, CLAUDE.md는 계층에 따라 병합된다.

⤢✕backend/frontend/전역 .claude/skills공통 스킬 로드현재 워킹 디렉토리?backend/.claude/skills 로드frontend/.claude/skills 로드백엔드 컨텍스트 에이전트 실행프론트엔드 컨텍스트 에이전트실행스킬 오버라이드 적용최종 실행 컨텍스트 확정

이 구조는 모듈 독립성의 관점에서 이해할 수 있다. 공통 지침은 루트에 두고 서비스에 특화된 스킬은 각 디렉토리에 가두면, 응집도를 높이면서 서비스 사이의 결합도를 낮출 수 있다. 예를 들어 데이터베이스 마이그레이션 스킬을 백엔드 디렉토리에만 배치하면 프론트엔드 에이전트에는 해당 스킬이 노출되지 않는다. 디렉토리 구조 자체가 최소 권한 경계로 기능하는 셈이다.

도구 허용을 명령과 경로까지 좁히기

v2.1.170 이전에는 도구 단위로 권한을 허용하거나 거부했다. 이 방식에서는 Bash를 허용하면 모든 bash 명령을 실행할 수 있으므로, 더 좁은 통제가 필요할 때 별도의 래퍼 스크립트를 사용해야 했다.

Tool(param:value) 문법은 도구 이름뿐 아니라 매개변수 값까지 정책에 포함한다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git push origin main)",
      "Read(/src/**)",
      "Write(/src/**/*.ts)",
      "mcp__filesystem__read_file(path:/workspace/*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Write(/etc/**)",
      "Write(/**/.env)"
    ]
  }
}

와일드카드는 glob 스타일을 따른다. *는 단일 경로 세그먼트, **는 여러 경로 세그먼트를 나타낸다. 정규식보다 정책을 읽기 쉽고 설정 실수의 여지도 줄일 수 있는 표현 방식이다.

권한 평가는 거부 규칙을 먼저 확인하는 흐름으로 구성된다. Deny에 일치하면 즉시 차단하고, 그렇지 않을 때 Allow를 검사한다. 어느 규칙에도 맞지 않으면 Auto Mode 여부에 따라 분류기 평가 또는 사용자 승인으로 넘어간다.

⤢✕YesNoYesNoYesNo에이전트 도구 호출 요청Tool(param:value) 파싱Deny 규칙 우선 매칭Deny 매칭?즉시 거부 (사용자 알림)Allow 규칙 매칭Allow 매칭?자동 허용 실행Auto Mode?분류기 평가 → 서브에이전트위임 여부 결정사용자 승인 요청승인 or 거부

Deny-first 방식은 시스템이 정책을 강제하고 사용자가 이를 우회하지 못하게 한다는 점에서 MAC(Mandatory Access Control)과 닮아 있다.

CI 에이전트에는 빌드와 검증에 필요한 동작만 열고, 배포나 환경 변경처럼 영향이 큰 작업은 명시적으로 막을 수 있다.

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Read(/project/**)",
      "Write(/project/src/**)",
      "Write(/project/tests/**)"
    ],
    "deny": [
      "Bash(npm publish *)",
      "Bash(git push * --force)",
      "Write(/project/.env*)",
      "Bash(curl * | bash)"
    ]
  }
}

이 정책에서는 빌드·테스트·린팅을 자율 실행할 수 있지만, 배포·강제 푸시·환경 파일 수정은 차단된다. 도구 전체를 닫지 않고 실제 작업에 필요한 범위만 여는 방식이다.

Auto Mode가 작업을 직접 처리할지 위임할지 판단하는 기준

Auto Mode는 사용자 요청을 분석해 서브에이전트를 스폰할지 결정한다. v2.1.170+에서는 이 분류기가 강화돼 단순 변경과 복합 작업, 병렬화 가능한 장기 작업을 더 세밀하게 구분한다.

⤢✕단순 파일 수정다중 파일 리팩토링장기 실행 태스크사용자 요청 수신요청 복잡도 분석 (분류기)작업 유형 분류직접 실행 (에이전트 스폰 없음)서브에이전트 스폰 결정병렬 서브에이전트 스폰서브에이전트 A: 파일 탐색서브에이전트 B: 코드 수정서브에이전트 C: 테스트 실행서브에이전트 D: 문서 업데이트결과 집계 & 오케스트레이션사용자에게 완료 보고

분류기가 보는 축은 복잡도, 병렬성, 리스크, 컨텍스트 유지 필요성이다. 복잡도 평가는 영향을 받는 파일 수와 의존성 깊이, 변경 범위를 기준으로 단순 작업과 복합 작업을 나눈다.

병렬성 평가는 작업 사이의 선후 관계를 가려낸다. 테스트 실행과 문서 업데이트는 함께 진행할 수 있지만, 코드를 수정한 뒤 그 결과를 검증하는 테스트는 순서가 필요하다. 파일 삭제나 데이터베이스 스키마 변경, 환경 설정 수정처럼 위험이 큰 동작에는 명시적 확인 단계가 삽입된다. 장기 작업에서는 컨텍스트 윈도우의 한계를 고려해 단일 세션을 유지할지 서브에이전트에 분산할지도 판단한다.

위임된 에이전트에는 오케스트레이터가 가진 권한 중 제한된 집합만 전달된다.

오케스트레이터 권한 집합 ⊇ 서브에이전트 권한 집합

서브에이전트가 오케스트레이터보다 넓은 권한을 요구하면 자동으로 거부된다. 오케스트레이터와 작업자 사이에 신뢰 경계를 두어 권한 에스컬레이션을 차단하는 구조다.

CI/CD에서 대화 없이 실행하는 에이전트

v2.1.170+가 지향하는 운용 방식에는 대화형 사용뿐 아니라 헤드리스 자율 배포도 포함된다. PR 이벤트가 오케스트레이터를 호출하면 변경사항 조회, 코드 리뷰와 테스트 위임, 결과 집계, PR 코멘트 작성까지 파이프라인에서 처리할 수 있다.

⤢✕"Git 저장소""서브에이전트: 테스트""서브에이전트: 코드 리뷰""오케스트레이터 에이전트""CI/CD 파이프라인""Git 저장소""서브에이전트: 테스트""서브에이전트: 코드 리뷰""오케스트레이터 에이전트""CI/CD 파이프라인"PR 이벤트 트리거 (headless 모드)PR 변경사항 페치코드 리뷰 위임테스트 실행 위임리뷰 결과 반환테스트 결과 반환PR 코멘트 작성결과 보고 (exit code)

GitHub Actions에서는 다음과 같이 헤드리스 리뷰 작업을 구성할 수 있다.

name: Claude Code Auto Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code Headless Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --headless \
            --permission-file .claude/ci-permissions.json \
            --auto-mode \
            "PR #${{ github.event.number }} 의 변경사항을 리뷰하고 
             코드 품질 이슈를 GitHub PR 코멘트로 작성하라"

--permission-file에는 CI 전용 정책 파일을 지정한다. 로컬 개발 환경에는 비교적 넓은 권한을 주고, 자동 실행되는 CI에는 필요한 범위만 허용하는 식으로 실행 환경을 분리할 수 있다.

사람의 승인 없이 진행되는 헤드리스 작업에서는 에이전트가 무엇을 했는지 추적할 수 있어야 한다. Claude Agent SDK는 도구 호출과 권한 결정, 서브에이전트 스폰 이벤트를 구조화된 JSON으로 기록한다.

{
  "timestamp": "2026-06-17T09:23:41Z",
  "session_id": "sess_abc123",
  "event_type": "tool_call",
  "tool": "Bash",
  "params": {"command": "npm test"},
  "permission_decision": "auto_allowed",
  "matched_rule": "Bash(npm test *)",
  "duration_ms": 4521,
  "exit_code": 0
}

이 기록은 책임 추적성(Accountability)을 확보하는 근거이며, 이상 행동 탐지와 포렌식 분석에도 활용할 수 있다.

코딩 에이전트를 비교할 때 볼 지점

2026년 현재 Claude Code v2.1.170+, OpenAI Codex CLI, Antigravity CLI의 기능 차이는 다음과 같이 정리된다.

기능 Claude Code v2.1.170+ OpenAI Codex CLI Antigravity (Google)
중첩 컨텍스트 디렉토리 지원 미지원 제한적 지원
세분화 권한 문법 Tool(param:value) + 와일드카드 도구 단위만 정책 파일 방식
서브에이전트 스폰 Auto Mode 분류기 수동 지정 내장 멀티에이전트
헤드리스 CI/CD 배포 공식 지원 베타 지원 지원
오픈소스 여부 부분 공개 클로즈드 제한 공개
컨텍스트 창 200K 토큰 128K 토큰 1M 토큰 (Gemini 기반)
MCP 표준 지원 완전 지원 미지원 제한적

Claude Code는 MCP(Model Context Protocol) 생태계 통합과 세분화된 권한 제어가 강점이다. Antigravity의 강점은 Gemini 기반 1M 토큰 컨텍스트 창이지만, 권한 제어의 세분성은 Claude Code보다 낮다. Codex CLI는 OpenAI 생태계 의존성이 높아 멀티 프로바이더 환경에서 유연성이 제한된다.

도구 선택은 단순 기능 목록보다 품질 특성에 맞춰 보는 편이 낫다. ISO/IEC 25010의 6가지 품질 특성에 대응시키면 다음과 같다.

  • 기능성: 코드 생성·리뷰·리팩토링·테스트 자동화 범위
  • 신뢰성: 권한 시스템의 견고성과 서브에이전트 실패 복구 메커니즘
  • 사용성: Tool(param:value)와 정책 파일 등 권한 설정 문법의 직관성
  • 효율성: 토큰 사용 최적화와 서브에이전트 병렬 처리 성능
  • 유지보수성: 중첩 컨텍스트 디렉토리를 이용한 스킬 모듈화 용이성
  • 이식성: MCP 표준을 통한 에이전트 도구 재사용성

이 평가 틀에서는 Claude Code v2.1.170+가 유지보수성과 이식성 측면에서 경쟁 도구보다 우위를 보인다.

자율성이 커질수록 권한 경계가 먼저다

2026년의 흐름은 코딩 에이전트의 자율성 수준이 Level 2(보조)에서 Level 3-4(조건부 자율·고도 자율)로 이동하는 것이다.

⤢✕(1) 현재: 보조 코딩 도구(2) 자율 PR 생성·리뷰(3) 아키텍처 설계 제안(4) 자율 배포 파이프라인(5) 자율 시스템 운영·장애 대응

보조 코딩에서 PR 생성과 리뷰, 아키텍처 제안, 배포와 운영으로 범위가 넓어질수록 세분화된 권한 제어와 감사 로그가 전제 조건이 된다. 에이전트가 자율적으로 처리할 수 있는 작업을 늘리는 것과 실행 경계를 정밀하게 제한하는 일은 함께 진행돼야 한다.

조직·프로젝트·세션으로 권한을 분리하기

엔터프라이즈 환경에서는 에이전트 권한을 3계층으로 나눌 수 있다. 조직 보안 팀은 프로덕션 DB 직접 쓰기나 외부 네트워크 요청처럼 절대 허용하지 않을 규칙을 전역 정책에 둔다. 프로젝트 리드는 특정 저장소 안의 쓰기처럼 프로젝트 범위의 권한을 정한다. 개별 개발자는 특정 스크립트의 1회 실행과 같은 임시 권한을 세션 정책으로 부여한다.

이 구조는 RBAC(Role-Based Access Control)과 연결된다. 전역 정책은 관리자 역할, 프로젝트 정책은 프로젝트 관리자 역할, 세션 정책은 일반 사용자 역할에 대응한다.

Auto Mode는 0(완전 수동)부터 5(완전 자율)까지 자동화 수준을 지원한다. 환경의 위험도와 승인 요구에 따라 다음처럼 배치할 수 있다.

수준 적용 환경 서브에이전트 스폰 사용자 확인 빈도
0-1 프로덕션 핫픽스 없음 모든 작업
2-3 개발 환경 일상 작업 단순 작업만 고위험 작업만
4 스테이징 자동화 복합 작업 포함 배포 단계만
5 CI/CD 완전 헤드리스 모든 작업 없음 (감사 로그만)

중첩 .claude 디렉토리는 프로젝트별 컨텍스트와 스킬을 분리하고, Tool(param:value)는 도구 실행 범위를 명령과 경로까지 좁힌다. Auto Mode 분류기는 그 경계 안에서 직접 실행과 서브에이전트 위임을 결정한다. 여기에 CI 전용 권한 파일과 감사 로그를 결합하면 모듈 독립성, 최소 권한, 역할 기반 접근 제어를 실제 코딩 에이전트 운영에 적용할 수 있다.

Sources

  • Anthropic Claude Code Release Notes v2.1.170+ (2026)
  • Claude Agent SDK Documentation — Headless Deployment Guide
  • Anthropic Model Context Protocol (MCP) Specification
  • ISO/IEC 25010:2023 — Software Product Quality Model
  • NIST SP 800-207 — Zero Trust Architecture
  • OpenAI Codex CLI Documentation (2026)
  • Google Antigravity CLI Technical Overview (2026)
  • 정보관리기술사 소프트웨어공학 및 보안 기출문제 분석 (2024-2026)
Claude Code코딩 에이전트권한 관리서브에이전트CI/CD