오늘만 무료

Claude Code 자율 운영 완전 정복 총정리

20개 체크·10개 hook 30분 셋업으로 점수 0점에서 100점까지

by AI개발자

4시간전 brunch_membership's

지금까지 잘 따라왔다.

7장, 20개 체크, 10개의 Hook스크립트, 5개 템플릿으로 완성단계까지 왔다.

마지막으로 그 모든 것들을 하나의 운영체계로서 연결하는 마지막 단계이다.

물론 처음부터 이번 장부터 읽고 설정해도 된다. 각 항목별 원리가 궁금하면 해당 장으로 가면 된다.

전체 체크 항목 리스트

퀵스타트 절차 (30분)

처음 설정하는 경우 이 순서대로 진행하면 30분 안에 전체 환경을 구축할 수 있다.

1단계: hook 스크립트 설치 (10분)

# claude-code-hooks 레포지토리를 클론

git clone https://github.com/gaebalai/claude-code-hooks.git ~/products/claude-code-hooks

# ~/.claude/hooks 디렉터리를 만들고 심볼릭 링크로 연결

mkdir -p ~/.claude/hooks

cd ~/.claude/hooks

ln -s ~/products/claude-code-hooks/hooks/*.sh .

# watchdog 스크립트를 PATH에 추가

mkdir -p ~/bin

ln -s ~/products/claude-code-hooks/scripts/cc-solo-watchdog ~/bin/

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc # 또는 ~/.bashrc

source ~/.zshrc

2단계: settings.json에 전체 hook 등록 (5분)

~/.claude/settings.json을 열고 아래 내용으로 교체(또는 병합)한다.

{

"hooks": {

"PreToolUse": [

{

"matcher": "Bash",

"hooks": [

{"type": "command", "command": "bash ~/.claude/hooks/branch-guard.sh"},

{"type": "command", "command": "bash ~/.claude/hooks/error-gate.sh"},

{"type": "command", "command": "bash ~/.claude/hooks/no-ask-human.sh"}

]

}

"PostToolUse": [

{

"matcher": "Edit|Write",

"hooks": [

{"type": "command", "command": "bash ~/.claude/hooks/syntax-check.sh"},

{"type": "command", "command": "bash ~/.claude/hooks/activity-logger.sh"}

]

{

"matcher": "Bash",

"hooks": [

{"type": "command", "command": "bash ~/.claude/hooks/activity-logger.sh"},

{"type": "command", "command": "bash ~/.claude/hooks/context-monitor.sh"},

{"type": "command", "command": "bash ~/.claude/hooks/decision-warn.sh"}

]

}

"Stop": [

{

"hooks": [

{"type": "command", "command": "bash ~/.claude/hooks/proof-log-session.sh"}

]

}

"PreCompact": [

{

"hooks": [

{"type": "command", "command": "bash ~/.claude/hooks/proof-log-session.sh"}

]

}

]

}

설정 후 Claude Code를 재시작해야 hook이 적용된다.

� 기존 settings.json이 있는 경우: 이미 다른 설정이 있다면 hooks 블록만 교체하거나 각 이벤트 배열에 항목을 추가한다. JSON 문법 오류가 없는지 python3 -m json.tool ~/.claude/settings.json으로 검증할 수 있다.

3단계: 템플릿 파일 배치 (10분)

# ops 디렉터리 생성

mkdir -p ~/ops

# 각 템플릿을 복사

cp ~/products/claude-code-hooks/templates/CLAUDE-autonomous.md ~/.claude/

cp ~/products/claude-code-hooks/templates/dod-checklists.md ~/.claude/

cp ~/products/claude-code-hooks/templates/task-queue.yaml ~/ops/

cp ~/products/claude-code-hooks/templates/mission.md ~/ops/

# lessons.md는 빈 파일로 시작

touch ~/ops/lessons.md

touch ~/ops/pending_for_human.md

# 배치 결과 확인

echo "=== ~/.claude/ ===" && ls ~/.claude/

echo "=== ~/ops/ ===" && ls ~/ops/

4단계: CLAUDE.md에 기본 규칙 추가 (5분)

CLAUDE-autonomous.md의 내용을 자신의 CLAUDE.md에 추가한다. 최소한 아래 4개 섹션이 포함되어야 한다.

# CLAUDE.md 최소 필수 구성

## 세션 시작 시 필수 절차

1. ~/ops/mission.md 를 읽어 현재 맥락 파악

2. ~/ops/task-queue.yaml 을 읽어 작업 목록 확인

3. ~/ops/lessons.md 를 읽어 과거 실수 숙지

4. status: in_progress 태스크 재개 또는 pending 태스크 시작

## 자율 판단 규칙 (묻지 않고 결정)

- 기술 선택, 구현 세부사항, 네이밍: 기존 코드베이스 규칙을 따른다

- 에러 수정: 스스로 조사·수정 (3회 실패 시 손절)

- 불명확한 사양: 업계 관례를 따르고 결정 이유를 주석으로 남긴다

## 반드시 사람에게 확인 (예외)

- 과금이 발생하는 조작

- 불가역적 데이터 삭제

- 외부 공개 (git push, 발행, 배포)

- 보안 관련 변경

## 루프 감지 규칙

같은 방법으로 3회 실패 시:

1. 즉시 멈춘다

2. ~/ops/pending_for_human.md 에 막힌 이유를 기록한다

3. 다른 태스크로 전환한다

## Git 운영 규칙

- 모든 작업은 새 브랜치에서 시작: git checkout -b feature/작업명

- main/master 직접 push 금지

- 파괴적 변경 전 안전 브랜치 생성 필수

5단계: watchdog 기동

# 현재 터미널에서 백그라운드로 실행

cc-solo-watchdog --log ~/.claude/watchdog.log &

# 또는 nohup으로 터미널 종료 후에도 유지

nohup cc-solo-watchdog --log ~/.claude/watchdog.log > /dev/null 2>&1 &

# 기동 확인

ps aux | grep cc-solo-watchdog

장시간 자율 운영 시에는 OS 자동 시작도 함께 설정한다 (macOS: launchd, Linux: systemd - 각 방법은 5장 참조).

6단계: 셋업 검증

전체 설정이 올바르게 되어 있는지 진단한다.

npx claudecode-scan

기대 결과:

Score: 95-100/100 — Production Ready ✅

▸ Safety Guards 100% [PASS] [PASS] [PASS] [PASS]

▸ Code Quality 100% [PASS] [PASS] [PASS] [PASS]

▸ Monitoring 100% [PASS] [PASS] [PASS]

▸ Recovery 100% [PASS] [PASS] [PASS]

▸ Autonomy 100% [PASS] [PASS] [PASS]

▸ Coordination 100% [PASS] [PASS] [PASS]

점수가 어떻게 변하는가

이 가이드의 전체 절차를 모두 적용했을 때의 점수 변화:

Before (기본 설정, 아무것도 하지 않은 상태):

Safety Guards: 0%

Code Quality: 0%

Monitoring: 0%

Recovery: 0%

Autonomy: 0%

Coordination: 0%

Total: 0/100

After (이 가이드의 전체 절차 적용 후):

Safety Guards: 100% (+21점)

Code Quality: 100% (+21점)

Monitoring: 100% (+16점)

Recovery: 100% (+16점)

Autonomy: 100% (+16점)

Coordination: 100% (+11점)

Total: 100/100

각 영역의 배점 차이는 현실의 위험도를 반영한다. Safety Guards와 Code Quality가 높은 것은, 이 두 영역의 공백이 즉각적이고 되돌리기 어려운 피해로 이어지기 때문이다.

100시간 가동해서 배운 것

최종적으로 가장 중요했던 것은 딱 하나였다.

"AI를 신뢰하는 것"이 아니라, "신뢰할 수 있는 구조를 만드는 것".

CLAUDE.md에 아무리 좋은 규칙을 써도, Claude Code가 항상 그 규칙을 따른다는 보장은 없다. 하지만 hook으로 물리적으로 차단하면, 규칙은 지켜진다. 감시 도구가 있으면 문제를 인지할 수 있다. 로그가 있으면 원인을 추적할 수 있다. 교훈이 쌓이면 같은 실패를 반복하지 않는다.

이것이 "AI 자율 운영"과 "AI가 멋대로 하게 내버려두는 것"의 차이다.

또한 국내 환경에서 자주 필요한 추가 설정도 공유한다.

비용 관리

# AWS 월별 지출 알림 설정 (AWS CLI 필요)

aws budgets create-budget \

--account-id $(aws sts get-caller-identity --query Account --output text) \

--budget '{

"BudgetName": "claude-agent-monthly",

"BudgetLimit": {"Amount": "50000", "Unit": "KRW"},

"TimeUnit": "MONTHLY",

"BudgetType": "COST"

}' \

--notifications-with-subscribers '[{

"Notification": {"NotificationType":"ACTUAL","ComparisonOperator":"GREATER_THAN","Threshold":80},

"Subscribers": [{"SubscriptionType":"EMAIL","Address":"your@email.com"}]

}]'

타임존 설정

# 로그에 KST(한국 표준시)가 기록되도록 환경변수 설정

echo 'export TZ=Asia/Seoul' >> ~/.zshrc

source ~/.zshrc

# 확인

date # 한국 시간이 출력되어야 함

GitHub 브랜치 보호 규칙 (무료 개인 레포지토리)

# GitHub CLI로 브랜치 보호 규칙 설정

gh api repos/{owner}/{repo}/branches/main/protection \

--method PUT \

--field required_pull_request_reviews='{"required_approving_review_count":1}' \

--field enforce_admins=true

파일 구조 최종 확인

셋업 완료 후의 파일 구조:

당장 시작하려면,

진단 부터,

npx claudecode-scan

hook 스크립트: https://github.com/gaebalai/claude-code-hooks/

GitHub - gaebalai/claude-code-hooks: 10 hooks + 5 templates for autonomous Claude Code operation. Production infrastructure from

10 hooks + 5 templates for autonomous Claude Code operation. Production infrastructure from 140+ hours of real-world use. - gaebalai/claude-code-hooks

https://github.com/gaebalai/claude-code-hooks

이 가이드는 Claude Code를 100시간 자율 운영하면서 실제로 발생한 사고들, 그리고 그것을 해결하기 위해 하나씩 추가한 설정들의 기록이다.