[Claude Code 자동화] Hooks, SDK, CI/CD 연동까지 — 반복 작업 자동화 완벽 가이드

 

안녕하세요!

재아군의 관찰인생입니다.

 

Claude Code를 매일 쓰다 보면, 매번 반복하는 패턴이 보이기 시작합니다.

"PR 올리기 전에 항상 린트 돌리고, 타입 체크하고, 커밋 메시지 작성하고..."

"이슈가 올라오면 분석하고, 브랜치 만들고, 구현하고, 테스트 돌리고..."

 

이런 반복 작업을 Claude Code의 자동화 기능으로 완전히 없앨 수 있습니다.

오늘은 Hooks 시스템부터 헤드리스 모드, CI/CD 연동까지 Claude Code 자동화의 모든 것을 정리합니다.

 

 

---

 

1. Claude Code 자동화란?

 

Claude Code 자동화는 인간의 개입 없이 Claude Code가 정해진 워크플로우를 자율적으로 실행하는 것을 말합니다.

크게 3가지 레벨로 나눌 수 있습니다.

 

레벨	방식	예시	난이도
1. Hooks	이벤트 트리거로 쉘 명령 자동 실행	파일 저장 시 자동 린트, 세션 시작 시 git pull	초급
2. 헤드리스 모드	CLI에서 프롬프트를 직접 전달하여 비대화형 실행	cron으로 매일 코드 리뷰, 스크립트에서 Claude 호출	중급
3. SDK/API	코드로 Claude를 에이전트로 프로그래밍	GitHub Actions에서 PR 자동 리뷰, 배포 파이프라인	고급

 

 

---

 

2. Hooks 시스템 — 이벤트 기반 자동화

 

Hooks는 Claude Code의 특정 이벤트가 발생할 때 쉘 명령이나 스크립트를 자동으로 실행하는 시스템입니다.

.claude/settings.json에 정의합니다.

 

사용 가능한 이벤트

 

이벤트	발생 시점	활용 예시
PreToolUse	도구 실행 직전	위험한 명령어 차단, 로깅
PostToolUse	도구 실행 직후	파일 변경 후 자동 린트/포맷팅
Notification	Claude가 알림을 보낼 때	Slack/Discord 알림 전송
Stop	응답 생성 완료 시	작업 완료 알림, 로그 기록
SessionStart	세션 시작 시	git pull, 환경 초기화, 컨텍스트 주입

 

실전 Hooks 설정 예시

 

// .claude/settings.json
{
  "hooks": {
    // 파일 수정 후 자동 ESLint 실행
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path') 2>/dev/null || true"
      }
    ],
    // 세션 시작 시 최신 코드 동기화
    "SessionStart": [
      {
        "command": "git pull --rebase origin main 2>/dev/null; echo 'OK'"
      }
    ],
    // rm -rf나 DROP TABLE 같은 위험한 명령어 차단
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo $CLAUDE_TOOL_INPUT | grep -qE 'rm -rf|DROP TABLE|truncate'; then echo 'BLOCK: 위험한 명령어 감지'; exit 1; fi"
      }
    ]
  }
}

 

Hooks의 핵심은 Claude Code의 동작을 감시하고 제어하는 가드레일 역할을 한다는 것입니다. 자동 린트로 코드 품질을 유지하면서, 위험한 작업은 사전에 차단할 수 있습니다.

 

 

---

 

3. 헤드리스 모드 — 스크립트에서 Claude 호출

 

헤드리스 모드는 Claude Code를 대화형 터미널 없이 프로그래밍 방식으로 실행하는 기능입니다.

쉘 스크립트, cron, CI/CD 파이프라인에서 Claude를 호출할 때 사용합니다.

 

기본 사용법

 

# -p 플래그: 프롬프트를 직접 전달
claude -p "src/api/users.ts를 분석해서 개선점을 알려줘"

# --output-format json: 결과를 JSON으로 반환
claude -p "이 함수의 타입 에러를 수정해줘" --output-format json

# 파이프 입력: stdin으로 컨텍스트 전달
git diff HEAD~1 | claude -p "이 변경사항을 리뷰해줘"

# --allowedTools: 사용 가능한 도구 제한
claude -p "코드를 분석해줘" --allowedTools Read,Glob,Grep

# --max-turns: 최대 턴 수 제한 (무한 루프 방지)
claude -p "버그를 찾아서 수정해줘" --max-turns 10

 

실전 자동화 스크립트

 

예시 1: 매일 아침 코드 상태 리포트

 

#!/bin/bash
# daily-report.sh — cron으로 매일 09:00에 실행

cd /path/to/project

REPORT=$(claude -p "다음을 분석해서 일일 리포트를 작성해줘:
1. 어제 머지된 PR 목록과 요약
2. 현재 열린 이슈 중 긴급한 것
3. 테스트 커버리지 현황
4. 기술 부채 중 이번 주에 처리해야 할 것

마크다운 형식으로 정리해줘." --allowedTools Read,Glob,Grep,Bash --max-turns 15)

# Slack으로 전송
curl -X POST "$SLACK_WEBHOOK" \
  -H "Content-type: application/json" \
  -d "{\"text\": \"$REPORT\"}"

 

예시 2: PR 자동 리뷰 봇

 

#!/bin/bash
# pr-review.sh — GitHub Actions에서 PR 생성 시 실행

PR_DIFF=$(gh pr diff $PR_NUMBER)

REVIEW=$(echo "$PR_DIFF" | claude -p "이 PR의 변경사항을 리뷰해줘.
다음 항목을 체크:
- 로직 오류
- 보안 취약점 (SQL 인젝션, XSS 등)
- 성능 이슈
- 테스트 누락

심각도별로 분류해서 GitHub 코멘트 형식으로 작성해줘." \
  --allowedTools Read,Glob,Grep \
  --max-turns 10 \
  --output-format text)

# PR에 리뷰 코멘트 남기기
gh pr comment $PR_NUMBER --body "$REVIEW"

 

예시 3: 의존성 취약점 자동 패치

 

#!/bin/bash
# security-patch.sh — 주 1회 실행

cd /path/to/project

# npm audit 결과를 Claude에게 전달
AUDIT=$(npm audit --json 2>/dev/null)

claude -p "npm audit 결과를 분석해서:
1. 심각도 high 이상의 취약점만 필터링
2. 안전하게 업데이트 가능한 패키지 식별
3. package.json에서 해당 패키지 버전을 업데이트
4. npm install 실행
5. npm test로 기존 테스트가 통과하는지 확인
6. 통과하면 커밋, 실패하면 롤백

npm audit 결과: $AUDIT" \
  --allowedTools Read,Edit,Bash,Glob \
  --max-turns 20

 

---

 

4. CI/CD 파이프라인 통합

 

Claude Code를 CI/CD에 통합하면 코드 리뷰, 문서 생성, 테스트 작성을 완전 자동화할 수 있습니다.

 

GitHub Actions 연동

 

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          echo "$DIFF" | claude -p "이 PR을 리뷰해줘.
          Critical/Warning/Info로 분류해서 GitHub 마크다운 형식으로 출력." \
            --allowedTools Read,Glob,Grep \
            --max-turns 10 \
            --output-format text > review.md

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: review
            });

 

자동화 가능한 CI/CD 작업

 

작업	트리거	Claude 역할
PR 코드 리뷰	PR 생성/업데이트	변경사항 분석, 보안/성능 이슈 탐지
릴리스 노트 생성	태그 생성	커밋 히스토리 분석, 사용자 친화적 노트 작성
API 문서 업데이트	src/api/ 변경 시	엔드포인트 분석, OpenAPI 스펙 자동 생성
테스트 보강	커버리지 80% 미만 시	누락된 테스트 케이스 자동 생성
마이그레이션 검증	DB 스키마 변경 시	마이그레이션 안전성 분석, 롤백 계획 생성

 

 

---

 

5. 실전 자동화 사례: 블로그 자동 발행

 

제가 실제로 운영하고 있는 블로그 자동화 파이프라인을 소개합니다.

이 블로그의 글들이 바로 이 파이프라인을 통해 생성되고 발행됩니다.

 

# 블로그 자동화 파이프라인 흐름
npm start -- auto "주제 키워드"

# 내부 동작:
# 1단계: 키워드 최적화 (SEO 친화적 제목 생성)
# 2단계: Claude CLI로 본문 콘텐츠 생성 (8 섹션, 테이블, 코드 블록)
# 3단계: HTML/CSS 이미지 5장 + 썸네일 자동 생성
# 4단계: SEO 검수 (키워드 배치, 구조, 콘텐츠 품질)
# 5단계: Playwright로 Tistory 자동 업로드 (로그인 → 글 입력 → 임시저장)

 

이 파이프라인에서 사용된 자동화 기법들:

 

• 헤드리스 Claude 호출: CLI에서 claude -p로 콘텐츠 생성
• node-html-to-image: HTML/CSS 템플릿을 PNG로 렌더링하여 이미지 자동 생성
• Playwright 자동화: 브라우저 자동화로 카카오 로그인 → TinyMCE 에디터 입력 → 임시저장까지 무인 실행
• SEO 자동 검수: 키워드 배치, 섹션 수, 이미지 수, 콘텐츠 길이를 점수화하여 품질 확보

 

하나의 명령어로 주제 선정부터 발행까지 전 과정이 자동화됩니다.

 

---

 

6. 안전한 자동화를 위한 가드레일

 

자동화의 편리함 뒤에는 위험성도 있습니다. 안전하게 운영하기 위한 필수 가드레일을 정리합니다.

 

가드레일	구현 방법	이유
도구 제한	--allowedTools Read,Grep	읽기 전용 작업에서 파일 수정을 방지
턴 수 제한	--max-turns 10	무한 루프 방지, API 비용 제어
위험 명령 차단	PreToolUse Hook으로 rm -rf, DROP 등 차단	돌이킬 수 없는 작업 사전 방지
드라이런 우선	프롬프트에 "실행하지 말고 보여줘만" 패턴 사용	새 자동화 구축 시 결과를 먼저 검증
환경 분리	프로덕션 DB 접근 불가한 환경에서 실행	실수로 프로덕션 데이터 변경 방지
로그 기록	PostToolUse Hook으로 모든 도구 호출 로깅	문제 발생 시 추적과 디버깅

 

---

 

7. 향후 전망

 

• 이벤트 드리븐 AI 에이전트: 현재는 cron이나 CI 트리거에 의존하지만, 향후에는 Slack 메시지, Jira 이슈 생성, 프로덕션 에러 등 다양한 이벤트에 Claude가 실시간으로 반응하는 시스템이 보편화될 것입니다.
• 자가 치유(Self-Healing) 시스템: 프로덕션에서 에러가 발생하면 Claude가 자동으로 원인을 분석하고, 핫픽스 PR을 생성하고, 테스트를 통과하면 자동 배포하는 완전 자동화 파이프라인이 실험 단계에 있습니다.
• 멀티 레포 자동화: 하나의 자동화 설정이 여러 프로젝트에 걸쳐 동작하는 기능. 모노레포 환경에서 특히 유용하며, 의존성 변경이 다른 패키지에 미치는 영향을 자동으로 분석하고 대응합니다.
• Claude Code SDK의 성숙: Agent SDK가 발전하면서 커스텀 자동화 도구를 더 쉽게 구축할 수 있게 됩니다. 현재의 쉘 스크립트 기반 자동화가 TypeScript/Python 기반의 정교한 자동화로 진화할 것입니다.

 

 

---

 

마무리

 

지금까지 Claude Code 자동화의 3가지 레벨을 살펴보았습니다.

 

• Hooks로 이벤트 기반 자동 린트, 보안 가드레일을 구축할 수 있습니다.
• 헤드리스 모드로 스크립트에서 Claude를 호출하여 정기적인 리뷰, 리포트를 자동화할 수 있습니다.
• CI/CD 통합으로 PR 리뷰, 문서 생성, 테스트 보강을 완전 자동화할 수 있습니다.
• 가드레일(도구 제한, 턴 수 제한, 위험 명령 차단)은 반드시 함께 구축하세요.

 

자동화는 "매일 반복하는 작업 1개"부터 시작하세요. 작은 성공을 경험한 후 점진적으로 확장하는 것이 가장 효과적입니다.

 

궁금한 점이나 자동화 사례가 있다면 댓글로 공유해 주세요!

감사합니다!