클로드 코드 --agent: 세션 전체를 에이전트로 전환하기

클로드 코드에서 서브 에이전트를 쓰면 대화 도중에 특정 작업을 별도의 에이전트에게 위임할 수 있습니다. 코드 탐색은 Explore에게, 리뷰는 커스텀 에이전트에게 맡기는 식이죠. 그런데 가끔은 대화 중에 에이전트를 호출하는 게 아니라, 시작부터 끝까지 하나의 에이전트로 세션 전체를 운영하고 싶을 때가 있습니다.

“이번 세션은 코드 리뷰만 할 거야”라거나 “CI 파이프라인에서 린트 체크만 돌리고 싶어”라는 상황이요. 이럴 때 쓰는 게 바로 --agent 플래그입니다.

무엇이 달라지나

보통 클로드 코드를 실행하면 기본 시스템 프롬프트와 모든 도구가 갖춰진 범용 세션이 시작됩니다. --agent를 쓰면 이 기본 동작이 통째로 바뀌어요.

claude --agent code-reviewer

이렇게 시작하면 code-reviewer 에이전트의 설정이 세션 전체에 적용됩니다. 에이전트의 시스템 프롬프트가 기본 프롬프트를 대체하고 에이전트가 선언한 도구만 쓸 수 있어요. 모델과 권한 모드도 에이전트에 지정된 대로 동작하죠.

서브 에이전트와 비교하면 차이가 명확합니다. 서브 에이전트는 메인 대화 안에서 특정 작업을 위임받아 결과만 돌려주는 “부하 직원”이에요. 반면 --agent는 세션 자체의 정체성을 바꾸는 겁니다. 메인 대화 자체가 그 에이전트가 되는 거죠.

에이전트 파일 만들기

--agent에 넘길 에이전트는 마크다운 파일로 정의합니다. 서브 에이전트와 형식이 같아서 같은 파일을 공유할 수 있어요.

---
name: code-reviewer
description: 코드 변경사항을 리뷰하고 개선점을 제안합니다
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash(git diff:*)
  - Bash(git log:*)
permissionMode: plan
---

코드 리뷰어로서 코드 변경사항을 분석합니다.

## 리뷰 기준

- 버그 가능성이 있는 코드 패턴
- 성능에 영향을 줄 수 있는 변경
- 보안 취약점
- 코드 가독성과 유지보수성

## 출력 형식

각 이슈를 파일명, 라인 번호, 심각도(critical/warning/info)와 함께 보고합니다.

파일의 frontmatter에서 tools로 사용 가능한 도구를 제한하고 permissionMode로 권한을 설정합니다. 본문은 에이전트의 시스템 프롬프트가 됩니다.

에이전트 파일은 두 곳에 저장할 수 있어요. .claude/agents/에 넣으면 프로젝트 전용으로 Git에 커밋해서 팀과 공유할 수 있고, ~/.claude/agents/에 넣으면 모든 프로젝트에서 사용하는 개인용이 됩니다.

세션 시작하기

에이전트 파일을 만들었으면 --agent 플래그에 이름을 넘겨서 세션을 시작합니다.

claude --agent code-reviewer

이름은 파일명에서 .md 확장자를 뺀 것입니다. code-reviewer.md라면 code-reviewer가 되죠. 세션이 시작되면 터미널 배경색이 바뀌어서 일반 세션이 아니라 에이전트 세션이라는 걸 시각적으로 알 수 있어요.

다른 플래그와 조합해서 쓸 수도 있습니다.

# 모델을 오버라이드해서 시작
claude --agent code-reviewer --model opus

# 특정 세션을 에이전트로 재개
claude --agent code-reviewer --continue

# Git worktree에서 격리 실행
claude --agent code-reviewer --worktree

--model로 에이전트 파일에 지정된 모델을 덮어쓸 수 있고, --continue로 이전 세션을 이어서 할 수도 있습니다. --worktree를 붙이면 별도의 Git worktree에서 격리 실행되어 메인 브랜치에 영향을 주지 않아요.

비대화형 모드와 결합

--agent가 빛을 발하는 건 -p(print) 플래그와 결합할 때입니다. -p는 결과를 출력하고 바로 종료하는 비대화형 모드인데, 에이전트와 함께 쓰면 자동화 파이프라인을 구성할 수 있어요.

# PR의 변경사항을 리뷰해서 결과 출력
git diff main...HEAD | claude --agent code-reviewer -p "이 변경사항을 리뷰해줘"

파이프로 데이터를 넘기고 에이전트가 분석 결과를 출력하는 구조입니다. 사람이 터미널 앞에 없어도 돌아가니까 CI/CD 파이프라인이나 cron 작업에 쓰기 좋죠.

GitHub Actions에서 활용하는 예시도 살펴볼까요?

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

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Run code review
        run: |
          git diff origin/main...HEAD | claude \
            --agent code-reviewer \
            -p "이 PR의 변경사항을 리뷰해줘" \
            --output-format json

--output-format json을 추가하면 결과를 JSON으로 받아서 후속 처리도 할 수 있어요. GitHub Actions와의 더 자세한 통합 방법은 GitHub Actions 사용법을 참고하세요.

—agents와의 차이

이름이 비슷해서 헷갈리기 쉬운 --agents(복수형)라는 플래그도 있습니다. 둘은 용도가 완전히 다릅니다.

--agent는 기존에 만들어둔 에이전트 파일을 지정해서 세션 전체를 그 에이전트로 전환합니다. 반면 --agents는 JSON으로 새 서브 에이전트를 즉석에서 정의하는 거예요.

# --agent: 기존 에이전트로 세션 시작
claude --agent code-reviewer

# --agents: 임시 서브 에이전트를 JSON으로 정의
claude --agents '{
  "reviewer": {
    "description": "코드 리뷰",
    "prompt": "변경사항을 리뷰합니다"
  }
}'

--agent로 시작한 세션은 에이전트의 프롬프트와 도구 제한이 세션 전체에 적용되지만, --agents로 정의한 서브 에이전트는 메인 대화 중에 필요할 때만 호출됩니다. 정리하면 --agent는 “나는 이 에이전트다”이고, --agents는 “이 에이전트들을 부하로 쓸 수 있다”입니다.

기본 에이전트 설정

프로젝트에서 특정 에이전트를 항상 사용하고 싶다면 설정 파일에서 기본값을 지정할 수 있습니다.

{
  "agent": "code-reviewer"
}

이렇게 설정하면 해당 프로젝트에서 claude를 실행할 때마다 자동으로 code-reviewer 에이전트로 시작됩니다. 물론 CLI에서 --agent를 직접 지정하면 설정 파일보다 우선해요.

~/.claude/settings.json에 넣으면 모든 프로젝트에 기본 에이전트를 적용할 수도 있습니다. 다만 프로젝트마다 필요한 에이전트가 다를 테니 보통은 프로젝트 레벨 설정이 더 실용적이에요.

활용 예시

어떤 상황에서 --agent를 쓰면 좋을지 살펴보겠습니다.

코드베이스를 파악하는 단계에서 실수로 파일이 수정되는 걸 막고 싶다면 읽기 전용 탐색 에이전트가 유용합니다.

---
name: explorer
description: 코드베이스를 읽기 전용으로 탐색합니다
model: haiku
tools:
  - Read
  - Glob
  - Grep
  - Bash(find:*)
  - Bash(wc:*)
permissionMode: plan
---

코드베이스를 탐색하고 구조를 분석합니다.
파일을 수정하거나 생성하지 않습니다.

model: haiku로 빠르고 저렴한 모델을 쓰면서 쓰기 도구를 아예 빼버렸으니 안심하고 탐색할 수 있습니다.

테스트를 돌리고 실패한 항목을 분석해서 수정까지 해주는 테스트 전용 에이전트도 만들 수 있어요.

---
name: test-fixer
description: 테스트를 실행하고 실패한 항목을 수정합니다
tools:
  - Bash
  - Read
  - Edit
  - Glob
  - Grep
---

테스트를 실행하고 실패하는 테스트를 분석합니다.
실패 원인을 파악한 뒤 코드를 수정하여 테스트가 통과하도록 합니다.
테스트 코드 자체가 잘못된 경우가 아니라면 소스 코드를 수정합니다.

claude --agent test-fixer -p "전체 테스트를 돌리고 실패하는 것들을 고쳐줘"

코드를 읽어서 API 문서나 README를 자동으로 뽑아내는 문서 생성 에이전트도 생각해볼 수 있습니다.

claude --agent doc-writer -p "src/utils/ 디렉토리의 모든 함수에 대한 API 문서를 생성해줘"

이런 식으로 목적에 맞는 에이전트를 미리 만들어두면 매번 긴 프롬프트를 작성할 필요 없이 에이전트 이름만으로 원하는 작업을 시작할 수 있습니다.

마치며

--agent 플래그는 클로드 코드 세션의 정체성 자체를 바꾸는 도구입니다. 서브 에이전트가 대화 중에 작업을 위임하는 방식이라면, --agent는 처음부터 특정 역할에 맞춰진 세션을 여는 방식이에요. 특히 -p 플래그와 결합하면 CI/CD 파이프라인이나 자동화 스크립트에서 Claude를 특정 목적의 도구로 활용할 수 있습니다.

에이전트 파일을 .claude/agents/에 커밋해두면 팀원 모두가 같은 에이전트를 사용할 수 있으니, 코드 리뷰나 테스트 같은 반복 작업의 품질을 일관되게 유지하는 데도 도움이 됩니다. 여러 에이전트가 팀으로 협업하는 구조가 궁금하다면 에이전트 팀도 살펴보세요.

더 자세한 내용은 공식 CLI 레퍼런스를 참고하세요.