2강. 클로드 코드 에이전트 기초 | 클로드 코드 에이전틱 자동화 20강 · 중급 — NUGUNA

🎯 학습 목표

이 강을 마치면 클로드 코드(Claude Code)가 제공하는 권한 모드(Permission Mode)의 종류와 차이를 이해하고, 사람이 매번 승인하지 않아도 자동으로 실행되는 비대화형(non-interactive) 실행 방식을 명령어 수준에서 사용할 수 있습니다. 또한 자동으로 실행된 에이전트가 무엇을 했는지 로그로 확인하는 방법과, --dangerously-skip-permissions 같은 강력한 옵션을 안전하게 다루기 위한 설계 원칙을 설명할 수 있습니다. 1강에서 "에이전틱 AI는 목표만 주면 스스로 계획·실행·검증을 반복한다"고 배웠다면, 이번 강은 그 반복을 클로드 코드에서 실제로 어떻게 켜고 끄고 제어하는지에 대한 강의입니다.

🤔 왜 권한 제어가 에이전트의 핵심인가

이 섹션에서는 클로드 코드가 왜 "얼마나 자동으로 실행할지"를 세밀하게 제어하는 구조를 갖추고 있는지 살펴보겠습니다.

클로드 코드는 기본적으로 파일을 수정하거나, 셸 명령을 실행하거나, 네트워크 요청을 보내는 것 같은 행동을 하기 전에 사람에게 승인을 요청하도록 설계되어 있습니다. 이는 1강에서 강조한 "에이전틱 AI는 완전 자동이 아니며 사람의 승인이 중요하다"는 원칙이 실제 제품에 구현된 형태입니다. 그런데 이 승인 절차가 매번 발생하면, 반복 작업을 완전히 자동화하려는 목적에는 방해가 됩니다. 예를 들어 매일 밤 자동으로 테스트를 돌리고 실패를 고치는 파이프라인을 만들고 싶다면, 사람이 화면 앞에 앉아 승인 버튼을 누르고 있을 수는 없습니다.

그래서 클로드 코드는 "얼마나 자동으로 실행할 것인가"를 여러 단계로 나눈 권한 모드 체계를 제공합니다. 완전히 사람이 매 행동을 검토하는 모드부터, 안전한 편집만 자동 승인하는 모드, 특정 도구만 미리 승인해두는 모드, 그리고 모든 승인 절차를 건너뛰는 모드까지 스펙트럼으로 존재합니다. 이 스펙트럼을 이해하는 것이 클로드 코드를 에이전트로 안전하게 운용하는 출발점입니다.

💡 핵심 개념 — 권한 모드와 비대화형 실행

이 섹션에서는 클로드 코드의 권한 모드 종류와, 사람 없이 실행되는 비대화형 모드의 구조를 자세히 설명하겠습니다.

공식 문서에 따르면 클로드 코드는 다음과 같은 권한 모드를 제공합니다.

모드	승인 없이 실행되는 범위	적합한 상황
`default`	읽기 작업만	처음 사용, 민감한 작업
`acceptEdits`	읽기 + 파일 편집 + 기본 파일 명령(mkdir·mv·cp 등)	검토 중인 코드 반복 작업
`plan`	읽기 위주(변경 전 분석)	수정 전 코드베이스 탐색
`auto`	백그라운드 안전 검사와 함께 대부분 자동	장시간 작업, 승인 피로 감소
`dontAsk`	사전 승인된 도구만	잠금된 CI·스크립트 환경
`bypassPermissions`	모든 작업	격리된 컨테이너·VM 전용

이 중 bypassPermissions 모드가 --dangerously-skip-permissions 플래그와 동일한 동작입니다. 이 플래그를 켜면 파일 수정, 명령 실행 같은 모든 도구 호출이 승인 절차 없이 즉시 실행됩니다. 흔히 "YOLO 모드"라고도 불립니다. 다만 rm -rf /나 rm -rf ~처럼 파일시스템 루트나 홈 디렉터리를 통째로 지우는 명령은 이 모드에서도 안전장치로 여전히 승인을 요구합니다.

다음으로 비대화형(non-interactive) 실행은 사람이 터미널 앞에 앉아 있지 않아도 클로드 코드가 한 번의 명령으로 작업을 끝까지 수행하고 종료하는 방식입니다. 클로드 코드에서는 -p(또는 --print) 플래그를 붙이면 이 모드로 동작합니다. 이 모드는 스크립트, CI 파이프라인, 예약 작업처럼 사람의 입력을 기다릴 수 없는 환경에서 사용하도록 설계되었습니다. 작업이 성공하면 종료 코드 0을, 실패하면 0이 아닌 종료 코드를 반환하므로 스크립트가 성공·실패를 코드 레벨에서 분기할 수 있습니다.

💻 실전 사례 — 명령어로 자율 실행하고 로그 확인하기

이 섹션에서는 실제로 클로드 코드를 비대화형으로 실행하고, 그 결과를 로그로 확인하는 방법을 명령어와 함께 살펴보겠습니다.

가장 기본적인 형태는 프롬프트를 인자로 넘기는 것입니다.

claude -p "auth.py의 버그를 찾아서 고쳐줘" --allowedTools "Read,Edit,Bash"

--allowedTools는 특정 도구를 승인 절차 없이 쓰도록 미리 허용하는 옵션입니다. 위 예시는 파일 읽기·편집·셸 실행 세 가지 도구만 자동 승인하고 나머지는 여전히 사람의 확인을 요구합니다. 잠금된 CI 환경처럼 사전 승인된 도구 외에는 절대 실행하면 안 되는 상황에서는 --permission-mode dontAsk를 함께 사용합니다.

claude -p "테스트를 실행하고 실패를 고쳐줘" --permission-mode acceptEdits

완전히 격리된 컨테이너나 VM처럼 클로드 코드가 호스트 시스템에 피해를 줄 수 없는 환경이라면 모든 승인을 건너뛸 수 있습니다.

claude --dangerously-skip-permissions -p "리팩터링 작업을 끝까지 진행해줘"

에이전트가 실제로 무엇을 했는지 확인하려면 --output-format 옵션으로 결과를 구조화된 형태로 받을 수 있습니다. json으로 지정하면 최종 응답과 세션 ID, 비용 추정치(total_cost_usd) 등이 담긴 JSON을 받고, stream-json으로 지정하면 도구 호출과 응답 생성 과정이 한 줄씩 실시간 이벤트로 출력됩니다.

claude -p "이 프로젝트를 요약해줘" --output-format json | jq -r '.result'

이런 방식으로 저장한 로그는 나중에 "에이전트가 어떤 파일을 건드렸는지", "어떤 명령을 실행했는지"를 사람이 다시 검토할 수 있는 근거 자료가 됩니다. 앞서 1강 주의사항에서 강조했듯, 에이전트의 자기 보고를 그대로 믿기보다 이런 실행 로그를 직접 확인하는 습관이 중요합니다.

⚠️ 자주 하는 실수와 주의점

이 섹션에서는 자율 실행 옵션을 다룰 때 실무에서 자주 발생하는 실수를 짚어보겠습니다.

첫 번째는 --dangerously-skip-permissions를 일반 개발 환경에서 습관적으로 켜두는 것입니다. 공식 문서는 이 모드를 인터넷이 차단된 컨테이너나 VM 같은 격리된 환경에서만 사용하라고 명시하고 있으며, 프롬프트 인젝션이나 의도치 않은 행동에 대해 아무런 보호 장치도 제공하지 않는다고 경고합니다. 즉 외부 데이터(웹페이지, 이슈 코멘트 등)에 악의적인 지시가 숨어 있을 경우, 이 모드에서는 별다른 제지 없이 그 지시가 그대로 실행될 위험이 있습니다.

두 번째는 root 권한으로 이 옵션을 실행하려는 시도입니다. 리눅스·macOS에서는 root나 sudo 권한으로 --dangerously-skip-permissions를 실행하면 보안상의 이유로 시작 자체가 거부됩니다. 컨테이너 안에서 자동화하고 싶다면 데브 컨테이너 설정을 사용해 non-root 사용자로 실행하는 것이 권장되는 방식입니다.

세 번째는 dontAsk와 bypassPermissions를 혼동하는 것입니다. dontAsk는 사전에 명시적으로 허용한 도구만 승인 없이 실행되고 그 외에는 여전히 막히는 반면, bypassPermissions는 사실상 모든 것을 허용합니다. CI처럼 예측 가능한 범위 안에서만 자동화하고 싶다면 dontAsk가 훨씬 안전한 선택입니다.

🚀 심화 — 안전한 에이전트 설계 원칙

더 알고 싶은 분들을 위해, 자율 실행 권한을 설계할 때 실무에서 지켜야 할 원칙을 정리하겠습니다.

첫째, 최소 권한 원칙입니다. "일단 다 허용하고 문제가 생기면 그때 막는다"가 아니라, 그 작업에 실제로 필요한 도구만 --allowedTools로 좁혀서 허용하는 방향이 안전합니다. 예를 들어 커밋 메시지를 작성하는 작업이라면 Bash(git diff *), Bash(git commit *)처럼 특정 git 하위 명령만 허용 범위를 지정할 수 있습니다.

둘째, 실행 환경의 격리입니다. 되돌리기 어려운 권한(bypassPermissions)을 쓸수록, 그 세션이 망가뜨릴 수 있는 범위를 컨테이너나 VM 같은 일회용 환경으로 좁혀야 합니다. 문제가 생기면 환경 자체를 버리고 새로 만들 수 있어야 안전합니다.

셋째, 결과의 사후 검증입니다. 비대화형으로 돌린 세션의 --output-format json 로그를 남겨두고, 무엇을 수정했는지 나중에 diff나 로그로 다시 확인하는 절차를 자동화 파이프라인 안에 포함시켜야 합니다. 이 원칙들은 이후 4강(스케줄된 에이전트)과 18강(에러 처리와 재시도 전략)에서 실제 자동화 설계에 그대로 이어집니다.

📝 핵심 요약

클로드 코드는 default부터 bypassPermissions까지 여러 단계의 권한 모드로 자동화 범위를 조절합니다.
-p(--print) 플래그로 비대화형 실행이 가능하며, 종료 코드로 성공·실패를 판별할 수 있습니다.
--allowedTools는 특정 도구만, --permission-mode dontAsk는 사전 승인된 도구만 자동 실행하도록 범위를 좁힙니다.
--dangerously-skip-permissions(bypassPermissions)는 모든 승인을 건너뛰므로 격리된 컨테이너·VM 밖에서는 사용하지 않아야 합니다.
--output-format json·stream-json으로 에이전트의 실행 로그를 구조화된 형태로 남기고 사후 검증할 수 있습니다.

다음 강에서는 이렇게 실행한 명령을 한 번으로 끝내지 않고 일정한 간격으로 자동 반복시키는 /loop 기능을 다루겠습니다.

클로드 코드 에이전트 기초