[Claude Code] claude code의 고급 기능 & 자동화 (심화)

앞선 글에서 Claude Code의 기본 개념과 사용법을 살펴봤다면,

이번 글에서는 CLI 플래그, 세션 관리, 에이전트 설정, 자동화 제어처럼 실제 실무에서 활용되는 고급 기능과 자동화 방식을 정리한다.

 

이 글은 Claude Code를 “써보는 단계”를 넘어 통제하며 사용하는 단계로 가기 위한 참고용 정리다.

 

☑️ CLI 참조

CLI 명령어

명령어	설명	예제
claude	대화형(REPL) 실행	claude
claude "query"	초기 질문을 입력한 뒤 대화형(REPL) 세션을 시작	claude "Summarize this repository"
claude -p "query"	한 번 질문하고 응답을 출력한 뒤 바로 종료	claude -p "List potential security issues"
cat file | claude -p "query"	파이프 입력 처리	cat error.log | claude -p "Explain the root cause"
claude -c	최근 대화 세션 계속 유지	claude -c
claude -c -p "query"	최근 대화를 사용, REPL은 열지 않고 응답 후 종료 CI/CD나 스크립트 자동화에서 자주 사용됨	claude -c -p "Suggest next refactoring steps"
claude -r "<session>" "query"	세션 ID 또는 이름을 지정해서 재개 이전 작업 맥락을 유지한 채 이어서 작업할 떄 유용	claude -r "payment-refactor" "Review remaining TODOs"

 

옵션	의미
-p	단발 실행
-c	최근 세션 계속
-r	특정 세션 재개

 

CLI 플래그

플래그	설명	예제
--add-dir	Claude가 접근할 수 있는 추가 작업 디렉토리 지정	claude --add-dir ../shared ../scripts
--session-id	대화에 명시적 세션 ID(UUID) 사용	claude --session-id "release-check-2026"
--continue, -c	현재 디렉토리의 최근 세션 재개	claude --continue
--resume, -r	특정 세션 ID 또는 이름으로 재개	claude --resume dashboard-migration
--fork-session	세션 재개 시 새 세션으로 분기	claude --resume dashboard-migration --fork-session
--agent	현재 세션에 사용할 에이전트 지정	claude --agent test-automator
--agents	JSON으로 사용자 정의 서브 에이전트 정의	claude --agents '{"docs":{"description":"Write docs","prompt":"You write API docs"}}'
--model	사용할 모델 지정	claude --model opus
--fallback-model	과부하 시 대체 모델 자동 사용	claude -p --fallback-model sonnet "Analyze build errors"
-tools	사용할 수 있는 도구 화이트리스트	claude --tools "Read,Grep"
--allowedTools	권한 확인 없이 실행 가능한 도구	claude --allowedTools "Read" "Bash(git diff:*)"
--disallowedTools	명시적으로 차단할 도구	claude --disallowedTools "Edit" "Bash(rm:*)"
--permission-mode	Ask / Plan / Auto-accept 중 시작 모드 지정	claude --permission-mode plan
--dangerously-skip-permissions	⚠️ 권한 확인을 완전히 생략	claude --dangerously-skip-permissions
--print, -p	대화형 모드 없이 출력만	claude -p "Summarize recent commits"
--output-format	출력 형식 지정	claude -p --output-format markdown "Write release notes"
--input-format	입력 형식 지정	claude -p --input-format stream-json
--system-promt	시스템 프롬프트 사용자 정의	claude --system-prompt "You are a security auditor"

► disallowedTools → allowedTools → tools 순으로 권한이 제한된다.

 

MCP 관련 플래그

플래그	설명	예제
--mcp-config	MCP 서버 설정 로드	claude --mcp-config ./mcp.local.json
--strict-mcp-config	지정한 MCP 설정만 사용	claude --strict-mcp-config --mcp-config ./mcp.prod.json
--chrome/ --no-chrome	Chrome 자동화 활성/비활성	claude --no-chrome

 

☑️ Agent / Sub-agent

: Claude는 상황에 따라 적절한 서브 에이전트를 자동으로 선택할 수 있으며,

  자동 호출이 되지 않는 경우 명시적으로 에이전트를 지정해 위임할 수 있다.

 

기본 개념

► 메인 에이전트(agent): Claude 세션에서 중심 역할 수행 

► 서브 에이전트(sub-agent): 리뷰 전용, 테스트 전용, 문서 적용 등 전문화된 역할을 수행하는 에이전트 

 

--agents의 기본 구조

필드	필수	설명
name	O	서브에이전트 이름, 키로 사용 된다.
description	O	서브에이전트를 호출해야 할 때를 설명하는 자연어 설명
prompt	O	서브에이전트의 동작을 안내하는 시스템 프롬프트 (역할·행동 규칙 정의)
tools	X	생략하면 메인 에이전트의 도구 권한을 상속
model	X	사용할 모델 별칭: sonnet, opus, 또는 haiku. 생략하면 기본 서브에이전트 모델 사용

 

유용한 Agent

► code-reviewer: 코드 품질, 보안, 유지보수성 관점에서 전문적인 코드 리뷰 수행 

► test-automator: 단위/통합/E2E 테스트를 포함한 종합 테스트 스위트 생성 

► debugger: 오류, 테스트 실패, 예상치 못한 동작에 대한 디버깅 전문가 

► error-detective: 에러 로그 분석 및 근본 원인 추적 전문가 

► docs-architect: 개발자 문서 작성 및 OpenAPI/Swagger 스펙 생성 

► architect-reviewer: 시스템 아키텍처 설계 및 기술적 의사결정 검토 

Sub - Agent 정의 방법

► CLI: 콘솔창에 json 형태로 입력해 사용 가능. 재시작시 사라짐 

► Json 파일 형식으로 정의 

► Yaml 파일 형식으로 정의 

claude --agents '{
  "test-automator": {
    "description": "Generates and maintains automated tests after code changes.",
    "prompt": "You are a test automation expert. Generate unit, integration, and edge-case tests. Do not modify production code.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

----

test-automator:
  description: Generates and maintains automated tests after code changes.
  prompt: |
    You are a test automation expert.
    Focus on unit, integration, and edge-case tests.
    Do not modify production code.
  tools:
    - Read
    - Grep
    - Glob
  model: sonnet

► 코드 리뷰 역할을 담당하는 서브 에이전트 

► 메인 에이전트가 "코드변경" 상황이라고 판단할 경우 자동 호출 

► 코드 품질, 보안 이슈를 집중적으로 판단. 

► 읽기, 코드 패턴 검색, 여러 파일 매칭, git 명령어 실행 가능 -> edit 권한을 부여하지 않았기에 리뷰에 집중 

► CLI로 정의한 에이전트는 세션 종료 시 사라지며, 파일(JSON/YAML)로 정의한 에이전트는 재사용 가능하다.

 

☑️ Hook

: Claude Code가 실행되는 과정에서 특정 이벤트 시점에 자동으로 실행되는 스크립트

: Hook 스크립트를 통해 프로젝트 외부 파일 접근, 위험한 시스템 명령 실행, 민감 정보가 담긴 파일 조작 등을 사전에 차단하거나 후처리 할 수 있다.

: 훅을 사용하면 LLM의 판단에 의존하지 않고, 항상 특정 작업이 실행되도록 보장할 수 있다

 

훅 이벤트 개요

훅 이벤트	언제 실행 되는지	역할
PreToolUse	도구 호출 전	차단 가능
PermissionRequest	권한 요청 전	허용/거부 제어 기능
PostToolUse	도구 호출 후	결과 후 처리, 로깅 등
UserPromptSubmit	사용자가 프롬프트 제출 시	입력 검증 및 전처리 가능
Notification	Claude가 알림 전송 시	데스크톱 알림 등
Stop	Claude 응답 완료 시	세션 종료 전 마무리 작업 수행
SubagentStop	서브에이전트 완료 시	후속 작업 트리거
PreCompact	컴팩트 작업 전	최적화 작업 가능
SessionStart	세션 시작/재개 시	초기 설정 실행
SessionEnd	세션 종료 시	정리 작업 실행

 

훅 기본 구조

: Hooks는 matcher 단위로 구성되며, 하나의 이벤트에 대해 여러 matcher와 hooks가 순차적으로 평가된다.

{
  // 코드 수정(Edit) 또는 파일 생성(Write) 이후 실행되는 포맷팅 훅
  "hooks": {
    "PostToolUse": [
      {
        // Edit 또는 Write 도구가 사용된 경우에만 반응
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { \
              read file_path; \
              if echo \"$file_path\" | grep -q '\\.ts$'; then \
                npx prettier --write \"$file_path\"; \
              fi; \
            }"
          }
        ]
      }
    ]
  }
}

► Claude Code가 TypeScript 파일(.ts)을 수정하거나 생성한 경우, 자동으로 prettier를 실행해 코드 포맷을 맞춘다.

 

[실행 순서]

이벤트, 언제 (Event) → 조건, 무엇에 반응하여 (matcher) → 실행 목적, 무엇을 할지ㅡ(hooks)

► EventName: 해당 이벤트가 발생하면 정의된 matcher를 순차적으로 검사한다.

► matcher:  도구 이름 필터 

► hooks: matcher가 일치하면 정의된 hooks가 실행되며, 여러 hooks는 병렬 실행될 수 있다.

 

☑️ 마무리

Claude Code, Agent, Hook은 각각 독립된 기능처럼 보이지만

실제로는 하나의 자동화 구조를 이루는 구성 요소다.

 

Claude Code는 AI가 실제 작업을 수행할 수 있는 실행 환경이고,

Agent는 그 안에서 무엇을 할지를 결정하는 역할 단위이며,

Hook은 그 작업이 언제, 어떻게 실행될 수 있는지를 통제한다.

 

이 세 가지를 함께 사용할 때,

Claude Code는 단순한 AI 도구를 넘어

신뢰 가능한 개발 자동화 플랫폼이 된다