> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# 자동화와 후크

> Claude Code 후크, 슬래시 커맨드, 멀티 에이전트로 반복 작업을 자동화

## 후크 (Hooks) — 결정론적 자동화

후크는 **특정 이벤트가 발생할 때 자동으로 실행되는 셸 명령**입니다. Claude의 판단에 의존하지 않고 결정론적으로 동작하므로, "매번 X를 해야 한다" 같은 규칙을 강제하기에 적합합니다.

### 지원되는 이벤트

| 이벤트                | 발생 시점               |
| ------------------ | ------------------- |
| `SessionStart`     | `claude` 시작 시       |
| `UserPromptSubmit` | 사용자가 프롬프트를 제출할 때    |
| `PreToolUse`       | Claude가 도구를 호출하기 직전 |
| `PostToolUse`      | 도구 호출이 끝난 직후        |
| `Stop`             | Claude가 응답을 마칠 때    |
| `Notification`     | 사용자 알림이 발생할 때       |

### 설정 위치

`.claude/settings.json` 또는 `.claude/settings.local.json`:

```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --silent || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Claude] 작업 완료' | terminal-notifier"
          }
        ]
      }
    ]
  }
}
```

### 실용적 후크 예제

**1. 파일 수정 후 자동 lint**

```json theme={null}
{
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{
      "type": "command",
      "command": "ruff check $CLAUDE_FILE_PATH 2>&1 | head -20"
    }]
  }]
}
```

**2. 위험한 명령 차단**

```json theme={null}
{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -E 'rm -rf|DROP TABLE|DELETE FROM' > /dev/null; then echo '위험한 명령 차단됨'; exit 2; fi"
    }]
  }]
}
```

`exit 2`로 종료하면 Claude가 해당 도구 호출을 진행하지 못합니다.

**3. 작업 완료 시 슬랙 알림**

```json theme={null}
{
  "Stop": [{
    "hooks": [{
      "type": "command",
      "command": "curl -X POST $SLACK_WEBHOOK_URL -d '{\"text\":\"Claude 작업 완료\"}'"
    }]
  }]
}
```

**4. 시크릿 누출 방지**

```json theme={null}
{
  "PreToolUse": [{
    "matcher": "Write",
    "hooks": [{
      "type": "command",
      "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -E '(api[_-]?key|password|token)\\s*[:=]\\s*[\"\\x27][^\"\\x27]{20,}' > /dev/null; then echo '잠재적 시크릿 감지'; exit 2; fi"
    }]
  }]
}
```

## 슬래시 커맨드 작성하기

자주 쓰는 프롬프트는 **사용자 정의 슬래시 커맨드**로 등록하면 한 단어로 호출할 수 있습니다.

### 위치

* 프로젝트 단위: `<project>/.claude/commands/<name>.md`
* 사용자 단위: `~/.claude/commands/<name>.md`

### 예제 — `/check-app` 커맨드

`~/.claude/commands/check-app.md`:

```markdown theme={null}
---
description: 배포된 Databricks App의 상태와 로그를 확인
argument-hint: <app-name>
---

다음을 순서대로 실행해줘:

1. `databricks apps get $1`로 앱 상태 확인
2. 상태가 RUNNING이 아니면 즉시 알리고 중단
3. RUNNING이면 `databricks apps logs $1 | tail -100`으로 로그 확인
4. 로그에 ERROR/Traceback/500이 있는지 grep
5. 발견되면 에러 라인을 정리해서 보고, 없으면 "정상" 출력
```

사용:

```
> /check-app my-rag-app
```

### 더 발전된 예 — `/cost-check`

```markdown theme={null}
---
description: 지난 N일간 워크스페이스 사용량과 비용을 요약
argument-hint: [days]
---

기본값 7일. 인자로 일수 지정 가능.

실행할 일:
1. `system.billing.usage` 테이블에서 지난 ${1:-7}일 데이터 조회
2. SKU별로 비용 집계
3. 가장 비싼 항목 5개를 마크다운 표로 출력
4. 전 주 대비 증감률 계산
5. 임계 초과 항목이 있으면 ⚠️ 표시

execute_sql MCP 도구 사용. 결과는 USD 기준으로 표시.
```

## 서브 에이전트 (Sub-Agents) — 병렬 실행

큰 작업을 작게 쪼개 **여러 Claude 인스턴스를 병렬로 실행**할 수 있습니다.

### 어떨 때 쓰나

* **독립적 탐색이 여러 개**: "frontend, backend, infra 폴더에서 각각 X 패턴 찾기"
* **컨텍스트를 메인에 가져오기 싫은 대용량 검색**
* **완전히 다른 영역에서 동시 진행**

### 사용 예

```
> 다음 세 가지를 병렬 에이전트로 진행해줘:
  1. Explore 에이전트로 src/ 전체에서 deprecated된 함수 호출 찾기
  2. general-purpose 에이전트로 docs/ 전체에서 깨진 링크 찾기  
  3. databricks-docs 스킬로 ai_parse_document 최신 사양 정리
  
  세 결과를 받아서 종합해줘.
```

각 서브 에이전트는 독립된 컨텍스트에서 실행되고, 메인 Claude는 최종 결과만 받습니다. **컨텍스트 절약**이 핵심 가치입니다.

### 커스텀 에이전트 정의

`.claude/agents/<name>.md`로 도메인 특화 에이전트를 정의할 수 있습니다. 예: 데이터 분석 전용 에이전트가 SQL 실행 도구만 사용하도록 제한.

## 스케줄링 — 정기 실행

`/loop`나 외부 스케줄러로 Claude Code 작업을 정기적으로 실행할 수 있습니다.

### `/loop` — 인터랙티브 반복

```
> /loop 5m /check-deployment
```

5분마다 `/check-deployment` 커맨드를 실행. 사용자가 `Esc`로 중단할 때까지 계속.

### crontab으로 헤드리스 실행

```bash theme={null}
# 매일 오전 9시에 일일 체크 실행
0 9 * * * cd ~/projects/myapp && claude -p "/daily-health-check" --output-format json >> ~/logs/claude.log
```

`-p` 플래그는 비대화형(headless) 모드. CI/CD에서도 사용 가능합니다.

## 환경 변수 — 후크와 커맨드에서 사용

후크와 커맨드는 다음 환경 변수에 접근할 수 있습니다:

| 변수                    | 의미                                  |
| --------------------- | ----------------------------------- |
| `$CLAUDE_FILE_PATH`   | 방금 편집/읽은 파일 경로 (Edit/Write/Read 후크) |
| `$CLAUDE_TOOL_INPUT`  | 도구에 전달된 입력 JSON                     |
| `$CLAUDE_TOOL_OUTPUT` | 도구 출력 (PostToolUse)                 |
| `$CLAUDE_PROJECT_DIR` | 현재 프로젝트 루트                          |
| `$CLAUDE_SESSION_ID`  | 현재 세션 ID                            |

## 안전한 자동화 원칙

자동화 강도가 높아질수록 위험도 커집니다. 다음 원칙을 지키세요:

1. **PreToolUse 후크로 위험 명령 차단**: 한 줄로 큰 사고를 막을 수 있음
2. **모든 자동 실행은 Git 커밋된 상태에서**: 자동화가 잘못 동작해도 롤백 가능
3. **시크릿은 환경 변수로**: 후크 명령에 평문으로 두지 말 것
4. **테스트 환경에서 먼저 검증**: 후크 동작은 운영 워크스페이스에 적용 전 dev에서 충분히 테스트
5. **`--dangerously-skip-permissions`는 컨테이너에서만**: 호스트에서는 절대 사용하지 말 것

## 다음 단계

마지막으로 모범 사례와 함정을 다룹니다.