Claude Code로 개발 루프를 돌리는 방법: auto mode 권한 설정과 hook을 통한 검증

서론

CoWorker에서 보안 기술 리드를 맡고 있는 이토입니다.

Claude Code에 한 번 요청하여 답변을 기다리는 것을 넘어, 작업을 반복적으로 위임하는 방식이 당연해졌습니다.

• PR(Pull Request)을 올리면 CI를 지켜보고, 실패하면 수정해서 다시 push하기
• 여러 서브 에이전트를 병렬로 실행시켜 리뷰와 구현을 분담하기
• /loop 또는 스케줄 실행으로 밤 사이에 유지보수 작업을 끝내두기

여기서 이 방식을 루프 엔지니어링(loop engineering)이라고 부릅니다. 프롬프트를 한 번 잘 작성하는 기술과는 별개로, 무엇을 계기로 작업을 시작하고, 무엇을 완료로 간주하며, 어디에서 인간의 판단이 필요한지를 설계하는 기술입니다.

인간이 보고 있지 않은 시간에 작업을 진행하려면 권한 설정이 필수적입니다. 매번 허가 프롬프트에 멈춰있으면 루프를 돌릴 의미가 없기 때문입니다. Claude Code의 auto mode는 이 허가 대기 시간을 줄여줍니다.

하지만, auto mode만으로는 충분하지 않다고 생각합니다.

루프는 '멈추지 않는 것'과 '폭주하지 않는 것'을 별도의 레이어에서 설계해야 합니다.

auto mode는 전자를 지탱하는 부품입니다. 후자 중 '반드시 멈춰야 하는 것'은 분류기(classifier)가 아니라 규칙과 권한 설계로 막아야 합니다.

1. 루프 엔지니어링의 구성 요소

제가 일상적으로 돌리는 것은 다음 세 가지 종류의 루프입니다.

어떤 루프든 설계해야 할 요소는 같습니다.

• 트리거: 무엇으로 한 바퀴가 시작되는가
• 작업: 한 바퀴로 무엇을 하는가 (작을수록 좋음)
• 검증: 무엇을 '완료'로 간주할 것인가 (테스트, 빌드, 차이점 확인)
• 대기: CI나 외부 상태를 어떻게 기다릴 것인가
• 종료 조건: 언제 루프를 멈출 것인가
• 인간에게 되돌리는 지점: 어떤 작업/상황에서 인간의 판단을 구할 것인가

루프가 실패할 때는 거의 항상 이 6가지 중 하나가 모호합니다. 특히 빠지기 쉬운 것은 검증과 인간에게 되돌리는 지점입니다.

대기(4)를 sleep 연쇄나 전경에서의 폴링으로 작성하는 것이 철칙이 아닙니다. Claude Code에는 백그라운드 스크립트 출력을 단위로 받는 Monitor가 있습니다. 자체 페이스의 /loop에서는 Claude가 다음 시작까지의 대기 시간을 매번 선택합니다(Scheduled tasks).

2. 만약 auto mode가 없었다면

허가되지 않은 작업에서의 정지

/loop나 세션 내 스케줄 태스크는 세션의 권한 모드를 상속받습니다(Scheduled tasks). 즉, 수동 승인 모드의 세션에서 야간 루프를 설정하면, 사전에 허가되지 않은 작업을 만나는 시점에서 승인을 기다리게 되어 아침까지 아무것도 진행되지 않습니다.

수동 승인 모드에서도 허가된 명령어나 내장 읽기 전용 명령어는 확인 없이 실행할 수 있으며, dontAsk 모드나 대상을 좁힌 allowlist로도 무인으로 돌릴 수 있습니다(Permission modes). 멈추는 것은 사전에 허가되지 않아 승인이 필요한 작업입니다. 다만, 루프가 한 바퀴마다 무엇을 할지 미리 모두 나열하는 것은 어렵고, 인간이 옆에 있는 대화 작업이라면 몰라도, 루프와는 궁합이 좋지 않습니다.

--dangerously-skip-permissions

승인 피로감과 멈추는 것이 싫으면 전부 허가하면 된다고 생각하기 쉽습니다. 실제로 공식 블로그에서도 auto mode를 만든 동기로서 매번의 승인이 부담이 되고, 일부 개발자들이 --dangerously-skip-permissions에 빠졌던 것을 언급했습니다(공식 블로그).

저의 운영에서도 auto mode 이전에는 '승인 버튼을 누르는 작업'이 거의 반사적이었습니다. 내용을 읽지 않고 누르는 승인은 승인하지 않은 것과 같습니다. 인간의 리뷰는 횟수가 늘어날수록 형식화됩니다.

모드 비교

참고로, v2.1.283 이상에서는 터미널과 VS Code에서 시작할 때 기본값이 auto입니다. claude -p의 기본값은 여전히 default입니다.

bypassPermissions에 대해 공식 문서는 “프롬프트 주입(prompt injection)이나 의도치 않은 작업에 대한 보호가 전혀 없다”, “인터넷이 없는 격리 환경에서만 사용해야 한다”고 경고합니다. Linux・macOS에서는 인식된 샌드박스 외부에서 root / sudo로 시작하려고 하면 거부되며, 관리자가 조직 차원에서 비활성화할 수도 있습니다. 또한 auto 모드의 기본 차단 대상에는 승인도 샌드박스도 없는 자율 루프를 실행하는 것 자체가 포함됩니다. --dangerously-skip-permissions를 붙여 시작하는 경우 등이 해당됩니다. “루프 안에서 무제한의 루프를 일으키는 것”은 애초에 예상된 사용법이 아닙니다.

3. auto 모드의 심사

auto 모드에서는 인간 대신 분류기가 각 액션을 심사합니다. 공식 문서는 이를 “장시간 태스크, 승인 피로도 감소”에 사용하는 모드라고 설명합니다 (Permission modes).

루프에게 중요한 속성은 다음과 같습니다.

• 읽기 및 작업 디렉토리 내 편집은 분류기를 거치지 않고 자동으로 통과됩니다. 쉘(shell), 네트워크, 외부 쓰기 등이 분류기에 전달됩니다.
• 확인 질문으로 멈추지 않고 작업을 계속하도록 모델이 촉진합니다. 다만, 프롬프트나 스킬이 명시적으로 질문을 요구하는 경우에는 질문합니다.
• 서브 에이전트에도 동일한 안전망이 적용됩니다. 시작 전 태스크 설명, 실행 중 각 액션, 종료 시 결과물 3지점에서 심사됩니다. 서브 에이전트 측 설정으로는 권한 모드를 완화할 수 없습니다.
• 분류기가 보는 것은 사용자 메시지, 도구 호출(tool call), CLAUDE.md이며, 도구의 결과는 제외됩니다. 읽어 들인 파일이나 웹 페이지에 삽입된 악성 문구가 분류기를 직접 조작하는 것은 불가능하도록 설계되었습니다.

루프는 인간이 보고 있지 않은 곳에서 CI 로그나 Issue, 의존 라이브러리의 README를 대량으로 읽습니다. 그곳에 숨겨진 지시에 따라가 버릴 위험이 있습니다. 분류기는 읽어 들인 내용을 심사 지시로 받아들이지 않고, 사용자의 요청과 실행하려는 작업을 비교합니다.

4. auto 모드가 막는 개발 과정

차단 패턴의 분류

분류기의 기본 방침은 요청을 넘어 권한을 확장하는 작업, 미지의 인프라로 향하는 작업, 읽어 들인 콘텐츠에 의해 유도된 것처럼 보이는 작업을 막는 것입니다. 신뢰되는 것은 작업 디렉토리와 세션 시작 시 설정된 git remote뿐이며, 그 외는 명시적으로 신뢰를 선언하기 전까지 “외부”로 취급됩니다 (Permission modes).

공식 문서의 기본 차단 대상을 개발 과정별로 정리했습니다 (Configure auto mode).

“CI를 고치는 김에” 운영 환경이 바뀐다. 밤에 일어나면 아침까지 아무도 눈치채지 못한다 |
| ... |

로컬에서의 구현, 테스트, 그리고 동일 리포지토리로의 push는 루프에 적합합니다. 하지만 프로덕션(본방), 공유 인프라, 권한 관리, 외부 공개는 루프에 적합하지 않으며, 분류기(classifier)가 막는 것은 당연한 사양입니다.

루프가 멈추는 실패 패턴

공식 문서의 내용과 제가 운영하며 경험한 바를 바탕으로, auto mode에서 루프가 멈추기 쉬운 상황들을 정리했습니다.

연속 블록에 따른 수동 승인 전환

분류기가 3회 연속 또는 세션 누적 20회 동안 블록하면, auto mode는 일시 정지하고 프롬프트 방식으로 돌아갑니다. 이 임계값은 설정할 수 없습니다. 무인 루프에서는 여기서 사람의 승인을 기다리며 멈추게 됩니다.

비대화 실행에서 남는 미실행 작업

-p를 이용한 비대화 실행 시, 허가 프롬프트의 수신자가 없으면 임계값에 도달해도 액션이 실행되지 않고 Claude는 작업을 계속합니다. 루프 자체는 멈추지 않지만, '배포 외에는 전부 완료했습니다'라는 상태로 완료 보고가 나올 때가 있습니다. 멈추는 것보다 알아차리기 어려운 실패입니다.

블록 후 시도 반복

블록되면 Claude는 그 이유를 받아들여 다른 방법을 시도합니다. 정상적인 작업이 실수로 블록되었을 경우, 대안을 찾아 비슷한 시도를 반복하게 되고, 토큰과 시간만 줄어듭니다. 공식 문서에서도 블록이 반복되는 것은 대부분 '분류기가 사용자의 환경(어떤 리포지토리나 서버가 신뢰할 수 있는지)을 알지 못하기' 때문이라고 설명합니다.

대화 압축으로 사라지는 지시

사내 문서나 채팅을 읽을 수 있는 커넥터를 연결하는 경우, 그 내용이 공개 자료(공개 리포지토리, 블로그 게시물, 외부 서비스)로 흘러나가는 경로는 hook으로 결정적으로 검사합니다. 분류기 또한 외향적인 글에서 내부 정보가 섞이는 것을 막으려고 하지만, '무엇이 내부 정보인지'는 조직마다 다르므로 분류기는 알 수 없습니다. 조직 고유의 경계는 조직 스스로 규칙에 작성할 수밖에 없습니다.

비용 상한선

대량의 서브 에이전트 실행, 과금 API 호출, 클라우드 리소스 생성 등은 보안 문제가 아니라 돈 문제인 경우가 많아 분류기에서 제한되지 않는 경우가 많습니다. 루프는 한 번의 오판이 N번 쌓이기 때문에, 횟수나 규모의 상한을 hook이나 Wrapper Script로 정해둡니다.

방어 계층

각 방법으로 작업을 멈추게 하는 확실성을 비교하면 다음 순서가 됩니다.

아래로 갈수록 확실하고, 위로 갈수록 유연합니다. '절대로 일어나서는 안 될 일'은 아래 계층에 두고, '상황에 따라 달라지는 것'은 위에 두는 것이 좋습니다. 분류기에는 그 중간에서 규칙으로 다 쓰지 못하는 작업을 판단하게 하는 것이 좋다고 생각합니다.

공식 문서에도 같은 생각이 적혀 있습니다. permissions.ask

은 분류기보다 먼저 평가되며 auto mode에서도 반드시 프롬프트가 나옵니다. permissions.deny

는 분류기와 사용자 의도 모두로 무시할 수 없습니다. 대화에서의 선언은 대화 압축 과정에서 사라질 수 있습니다(Configure auto mode).

6. '게으름'과 '불필요한 작업'에 대한 대처

분류기가 심사하는 것은 안전성이지, 업무의 질은 보지 않습니다.

auto mode에서 루프가 멈추지 않게 되면, 이번에는 다른 문제가 눈에 띄기 시작합니다. 제가 운영하면서 다음 4가지를 반복해서 봤습니다(건수는 측정하지 않았습니다).

이러한 문제들은 CLAUDE.md에 '테스트를 실행한 후에 완료 보고할 것'이라고 적어도 확실히 막을 수는 없습니다. 프로젝트 루트의 CLAUDE.md는 대화 압축 후에도 다시 로드되기 때문에, 지시 자체가 사라지는 것은 아닙니다(4장에서, 대화로만 전달된 지시가 사라지는 이야기와는 다릅니다). 문제는 CLAUDE.md의 지시에 강제력이 없기 때문에, 긴 루프 속에서 우선순위가 낮아지면 그대로 지켜지지 않게 된다는 것입니다.

이러한 대처에는 hook이 효과적입니다. 특히 다음 2가지로 루프의 질이 크게 달라집니다.

• Stop hook: Claude가 턴을 마치려는 순간 개입하여 '정말로 끝내도 되는지'를 판단합니다. 아직 아니라면 exit code 2와 이유를 반환하며 작업을 계속하게 합니다. 연속해서 되돌릴 수 있는 횟수에는 내장 상한(8회, CLAUDE_CODE_STOP_HOOK_BLOCK_CAP)이 있습니다(Hooks). - PreToolUse hook: 툴을 실행하기 직전에 개입하여 허가/거부/확인을 반환합니다. 스코프 외 파일에 대한 쓰기나 비용이 많이 드는 작업의 횟수를 결정적으로 제한할 수 있습니다.

Stop hook에서는 테스트 로그나 종료 코드는 스크립트로 확인합니다. '요청된 범위를 충족했는지'와 같이 말로 판단하는 부분에는 LLM에게 평가를 시키는 프롬프트 타입의 hook을 사용합니다. 이 조합이 실용적입니다.

7. 실패 기록 및 hook 반영

저는 실패를 대장에 기록하는 것부터 hook 작성을 시작하고 있습니다.

• 분류기에 거부된 작업, Stop hook에 되돌려진 이유, 사람이 손으로 수정한 부분을 한 줄씩 기록합니다.
  PermissionDenied
  hook을 사용하면 auto mode에서 거부된 툴 입력을 받을 수 있으므로, 기록을 자동화할 수 있습니다(Hooks). - 주 1회 정도 집계하여 같은 종류의 실패가 반복되고 있지 않은지 확인합니다.
• 반복되는 실패를 다음 3가지로 분류합니다.
• 오블록 →
  autoMode.environment
  에 신뢰하는 인프라를 선언합니다(분류기에 문맥을 제공). - 본래 막아야 할 작업 →
  permissions.deny

또는 PreToolUse hook으로 격상(결정적으로 만듦)합니다. 질적인 문제(게으름・불필요한 작업) → Stop hook의 판별 조건에 추가합니다.

• 오분류 블록 →
• 분류된 실패를 hook의 판별 조건으로 삼습니다. 이후에는 같은 실패가 감지되거나 되돌려지는 대상이 됩니다. 다만 Stop hook에는 프롬프트 형태도 있어, 후술하는 예시처럼 2번째는 통과시키는 설계도 가능하므로, 어디까지 확실히 막힐지는 hook의 종류와 작성 방식에 따라 달라집니다.

공식 문서에서도 거부를 되돌아보고 설정에 반영하는 방법을 설명하고 있습니다. /permissions

최근의 거부 목록을 검토하여 반복적인 거부는 신뢰하는 환경 선언(autoMode.environment)으로, 정형화된 작업은 allow로, 일회성 작업은 다음 메시지에서 구체적으로 의도를 명시하는 방식으로 분류합니다(Configure auto mode).

루프는 같은 처리를 여러 번 반복하기 때문에, 그 자리에서 고치는 것만으로는 같은 실패가 N번 발생할 수 있습니다. 첫 번째 실패를 장부에 기록하고, hook에 반영하여 반복을 방지합니다.

8. 설정 예시

아래는 기사용으로 작성한 최소 구성입니다. 그대로 사용하지 말고, 자신의 환경에 맞게 조정해 주세요.

permissions: 확실히 막을 것과 반드시 물어볼 것

{
"permissions": {
"deny": [
...

주의할 점이 2가지 있습니다.

첫 번째는, ask나 deny의 규칙이 작성된 문자열의 전방 일치로만 일치한다는 것입니다. 같은 의미의 명령어라도 작성 방식이 다르면 무시됩니다(Configure auto mode).

이 예시의 ask는 기본 브랜치로의 push를 확인하는 의도로 작성했지만, 위와 같이 작성 방식에 따라 main으로의 push도 통과할 수 있습니다. PreToolUse hook에서 명령어 전체를 검사하면 포착 범위가 넓어지지만, hook 역시 문자열을 보기 때문에 전면적이지는 않습니다. main으로의 push를 확실히 막고 싶다면, 리포지토리 측의 브랜치 보호 기능을 사용해야 합니다.

두 번째는, auto mode에 진입하면 Bash(*)나 인터프리터의 와일드카드가 같은 임의 코드 실행을 허용하는 넓은 allow가 비활성화된다는 것입니다. 패키지 매니저의 run 명령어를 허용하는 allow도 제외 대상이므로, Bash(npm run lint)와 같은 규칙이 auto mode에서 남아있는지는 /permissions로 확인해 주세요. Bash(npm test)와 같은 좁은 규칙은 유지됩니다(Permission modes).

autoMode.environment: 오분류 블록을 줄이기

오분류 블록의 주원인은 '분류기가 당신의 인프라를 모르는 것'이므로, 신뢰하는 범위를 자연어로 선언합니다.

{
"autoMode": {
"environment": [
...

"$defaults"는 반드시 포함해야 합니다. 포함하지 않으면 environment의 내장 엔트리가 대체됩니다(블록 규칙은 유지됩니다). /auto-mode-setup이 출력하는 초안에는 "$defaults"가 들어가지 않으니, 추가해 주세요. - 이 설정은 사용자 설정(~/.claude/settings.json)에서

）、managed settings, --settings

플래그는 Agent SDK의 인라인 JSON에서 읽히며, 프로젝트의 .claude/settings.json에서는 읽히지 않습니다. 이는 리포지토리가 스스로 신뢰 범위를 넓힐 수 없도록 하기 위함입니다. -
/auto-mode-setup
으로 초안을 만들 수 있습니다. claude auto-mode critique이 확인하는 것은 allow / soft_deny / hard_deny 규칙의 모호성이며, environment의 내용은 claude auto-mode config로 확인할 수 있습니다.

PreToolUse hook: 조직 고유 경계를 결정적으로 막다

외부 전송 작업에 조직 고유의 '내보내서는 안 되는 문자열'이 포함되어 있는지 검사하는 최소 예시입니다.

#!/usr/bin/env bash
# PreToolUse (Bash): 외부 명령에 내부 식별자가 포함되어 있으면 중지
set -euo pipefail
...

금지 목록 자체의 유출을 막기 위해, 금지 패턴 파일은 리포지토리 외부에 배치합니다. 그 대신, 파일이 없거나 손상되었을 때 무시되지 않도록, 검사할 수 없는 경우에는 중단하는 쪽으로 설정했습니다.

Stop hook: 끝나기 전에 검증을 촉구하다

#!/usr/bin/env bash
# Stop: 테스트를 실행한 흔적이 없으면, 한 번만 되돌려준다 (재요청)
set -euo pipefail
...

이 hook은 검증을 촉구하는 메커니즘입니다. 두 번째 Stop은 무조건 통과하며, 작업 트리가 깨끗하면 검증 기록도 보지 않습니다. 품질의 보장은 CI와 브랜치 보호가 담당합니다.

작업 트리의 해시값은 추적되지 않은 신규 파일을 포함하여 계산합니다. git diff HEAD만으로는 새로운 파일만 추가된 변경 사항이 테스트 없이 통과할 수 있기 때문입니다 (실제로 검증 과정에서 걸렸습니다).

#!/usr/bin/env bash
# 추적 중인 차분(diff) + 추적되지 않은 파일의 내용으로부터 작업 트리의 해시를 만듭니다
set -euo pipefail
...

테스트는 이 해시값을 기록하는 래퍼를 통해 실행됩니다. .loop/는 .gitignore에 추가합니다 (추가하지 않으면 해시 자체가 추적되지 않은 파일로 섞입니다).

{
"scripts": {
"test": "node test.js && mkdir -p .loop && .claude/hooks/tree-hash.sh > .loop/tested-tree"
...
}

stop_hook_active를 확인하여, 되돌려주기가 무한히 계속되지 않도록 했습니다. hook 자체가 루프를 멈출 수 없게 하지 않도록, hook에도 종료 조건을 설정합니다.

hook 등록

{
"hooks": {
"PreToolUse": [
...
}

hook의 경로는 "$CLAUDE_PROJECT_DIR"을 기준으로 작성합니다. 상대 경로일 경우, Claude가 cd한 위치에서 스크립트를 찾지 못해 exit 127이 발생하고, exit 2를 제외한 다른 코드는 차단하지 않기 때문에 가드가 완전히 풀립니다 (Hooks).

실제로 작동시켜 확인한 것

위의 hook은 일회용 리포지토리에 놓고 claude -p로 실제로 작동시켰습니다 (Claude Code 2.1.283). hook 이벤트는 --output-format stream-json --verbose --include-hook-events를 붙이면 관찰할 수 있습니다.

• PreToolUse의 exit 2: 명령어는 실행되지 않았고, stderr의 문구가 그대로 도구 결과로 Claude에게 전달되었습니다. Claude는 재시도하지 않고, 인간의 판단이 필요하다고 보고했습니다.
• Stop의 exit 2: Claude는 종료하지 않고 작업을 계속했습니다. 첫 번째 Stop 입력 시 stop_hook_active는 false였고, 되돌려준 후 두 번째는 true였습니다. - 프롬프트형 Stop hook ("type": "prompt"): 설정으로 받아들여지고 실행되는 것을 확인했습니다.

Stop hook으로 재고하게 만드는 범위

Stop hook이 보장하는 것은 한 번의 재고를 통해 지시에 따르게 하는 것이 아닙니다. 프롬프트에서 '테스트는 실행하지 마세요'라고 명시했을 경우, Claude는 되돌려짐을 받았음에도 불구하고 사용자 지시를 우선하여 'hook과 지시가 모순됩니다'라고 보고하고 종료했습니다. stop_hook_active

로 두 번째 과정을 거치도록 설계했기 때문에, hook은 한 번만 되돌립니다.

도저히 통과시키고 싶지 않은 상태가 있다면, Stop hook이 아니라 PreToolUse(push나 PR 생성 직전)에서 막아야 합니다.

분류기에 전달할 의도

'작업 트리를 바로 이전 커밋과 동일하게 만들고, 있는 것은 전부 버려줘'라고 구체적으로 요청하자, auto mode는 미추적 파일 삭제(git clean에 해당)를 실행했습니다. 공식 문서에 나와 있듯이, 구체적인 의도 표명은 기본 블록을 덮어씁니다. 다만 덮어쓸 수 있는 것은 soft block에 한정되며, hard block은 의도를 밝혀도 통과할 수 없습니다. 반면 '리포지토리를 정리해줘'라고만 요청했을 때는, Claude는 삭제가 아닌 git stash -u를 선택했습니다.

첫 번째 검증에서는 로그 파일을 '전부 버려줘'라고 요청한 해당 디렉터리에 작성했기 때문에, 로그와 함께 사라졌습니다. 루프의 로그나 장부는 루프가 건드리는 작업 트리 외부에 두어야 합니다.

9. 전체 루프 설계

전체 루프에서는 다음과 같이 조합합니다.

설계 체크리스트입니다.

• 루프에 포함할 공정은 '로컬 구현・테스트・동일 리포지토리로 push'에 한정했는가
• 운영/공유 인프라/권한 부여/외부 공개는 루프 외부에서 사람이 수행하는 구성인가
• 루프가 작동하는 환경에, 운영 자격 정보를 두고 있지 않은가

절대 발생해서는 안 되는 작업은
deny