Skip to main content

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.

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

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

​
지원되는 이벤트

이벤트발생 시점
SessionStartclaude 시작 시
UserPromptSubmit사용자가 프롬프트를 제출할 때
PreToolUseClaude가 도구를 호출하기 직전
PostToolUse도구 호출이 끝난 직후
StopClaude가 응답을 마칠 때
Notification사용자 알림이 발생할 때

​
설정 위치

.claude/settings.json 또는 .claude/settings.local.json: 
{
  "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 
{
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{
      "type": "command",
      "command": "ruff check $CLAUDE_FILE_PATH 2>&1 | head -20"
    }]
  }]
}
2. 위험한 명령 차단 
{
  "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. 작업 완료 시 슬랙 알림 
{
  "Stop": [{
    "hooks": [{
      "type": "command",
      "command": "curl -X POST $SLACK_WEBHOOK_URL -d '{\"text\":\"Claude 작업 완료\"}'"
    }]
  }]
}
4. 시크릿 누출 방지 
{
  "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: 
---
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

---
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으로 헤드리스 실행

# 매일 오전 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는 컨테이너에서만: 호스트에서는 절대 사용하지 말 것

​
다음 단계

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