AI-translated from English; not yet reviewed by a fluent editor.

# Claude Code 세션 시작 시 범위가 제한된 프로젝트 컨텍스트 hook 추가하기

> 현재 Git 브랜치를 Claude Code 컨텍스트에 추가하는 작은 프로젝트 SessionStart hook을 설치합니다. 직접 출력, 시작과 재개, 실패 동작을 확인합니다.

By BIG CHANGE Editorial

Published: 2026-10-20T00:22:54.831Z
Updated: 2026-10-20T00:22:54.831Z
Canonical: https://bigchange.ai/blog/claude-code-session-start-branch-context-hook-guide

![Conceptual charcoal illustration of an unbranded desktop monitor with one short orange stroke above two soft charcoal strokes; a keyboard rests in front.](https://bigchange.ai/api/media/file/claude-code-session-start-context-hero-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no actual Claude Code interface, hook execution or model result is depicted.

Claude Code hook은 앱이 세션의 특정 시점에 실행하는 명령입니다. 이 안내서는 프로젝트 범위의 `SessionStart` hook 하나를 추가합니다. 현재 Git 브랜치를 읽어 대화를 시작하거나 재개할 때 짧은 컨텍스트 한 줄을 전달합니다. 근거는 [Anthropic의 최신 hook 참조 문서](https://code.claude.com/docs/en/hooks)이며 2026년 10월 19일 확인했습니다. BIG CHANGE는 Node로 스크립트를 직접 확인하고 설정 JSON을 검사했습니다. Claude Code hook 실행이나 모델 응답 테스트는 하지 않았습니다.

## 핵심 변화

- **달라진 점:** 이 프로젝트의 `SessionStart` hook은 Claude Code가 대화를 시작하거나 재개할 때 짧은 Git 브랜치 한 줄을 전달합니다.
- **중요한 이유:** 매번 수동으로 붙여 넣지 않아도 시작 또는 재개 시 현재 브랜치가 세션 컨텍스트에 들어갑니다.
- **확인할 점:** 컨텍스트는 규칙을 강제하거나 모델 답변을 보장하지 않습니다. 신뢰하는 자신의 프로젝트에서 시작 및 재개 시 실제 전달 여부를 확인하세요.

## 설치 전 준비

변경 권한이 있는 Git 프로젝트를 사용하세요. 같은 터미널에서 Claude Code, Node.js, Git을 사용할 수 있어야 하며 프로젝트의 `.claude/settings.json` 파일을 수정할 권한이 필요합니다. 확인할 명령은 `node --version`, `git --version` , `claude --version`입니다. 준비 환경에는 Claude Code 2.1.301과 Node 24.19.0이 있었습니다. 관찰한 버전이며 최소 요구사항이 아닙니다.

**모델에 보내기 전에 브랜치 이름을 검토하세요.** 브랜치에는 고객명, 티켓명, 사고명이 포함될 수 있습니다. 문자 필터링과 문자열 단축은 그 의미를 지우지 않습니다. 브랜치 이름을 모델 컨텍스트에 넣도록 승인받은 경우에만 이 예제를 설치하세요. 그렇지 않으면 민감하지 않은 승인된 상태를 출력하도록 스크립트를 변경하고 설치 전에 변경 내용을 검토하세요. [Anthropic 데이터 사용 문서](https://code.claude.com/docs/en/data-usage) 는 서비스의 데이터 처리 방식을 설명합니다. 프로젝트의 권한도 함께 적용하세요.

Hook 명령은 자신의 사용자 권한으로 실행됩니다. 활성화 전에 기존 프로젝트 및 사용자 hook, 조직 정책, 전체 스크립트를 검토하세요. 프로젝트 설정은 저장소에 커밋될 수 있지만 `.claude/settings.local.json` 파일은 로컬에 남습니다. 이 예제는 해당 프로젝트에만 적용되도록 프로젝트 설정 파일을 사용합니다.

## 두 파일 설치하기

1. 프로젝트 안에 `.claude/hooks/` 를 만드세요. 아래 블록 전체를 `.claude/hooks/session-context.cjs` 파일로 저장하세요.

```javascript
'use strict';

const { execFileSync } = require('node:child_process');

const project = process.env.CLAUDE_PROJECT_DIR;
if (!project) {
  process.stderr.write('CLAUDE_PROJECT_DIR is unavailable\n');
  process.exit(1);
}

try {
  const raw = execFileSync('git', ['-C', project, 'branch', '--show-current'], {
    encoding: 'utf8',
    timeout: 1500,
    maxBuffer: 4096,
    stdio: ['ignore', 'pipe', 'pipe'],
  }).trim();
  const branch = raw ? raw.replace(/[^A-Za-z0-9._/-]/g, '_').slice(0, 80) : 'detached HEAD';
  process.stdout.write(`Current project branch: ${branch}\n`);
} catch {
  process.stderr.write('Could not read the project branch; check Git and project path\n');
  process.exit(1);
}
```

Git 하위 프로세스는 제한 시간 1.5초, 출력 버퍼 4,096바이트를 사용합니다. detached HEAD처럼 브랜치 결과가 비어 있으면 `detached HEAD`가 됩니다. 프로젝트 경로가 없거나 Git이 실패하면 짧은 stderr 진단과 종료 코드 1을 반환합니다.

2. 기존 `.claude/settings.json` 파일을 여세요. 아래 `hooks.SessionStart` 항목을 다른 설정과 hook 그룹에 병합하고 기존 항목은 보존하세요. 블록은 검토된 패킷의 전체 `settings.example.json` 를 보여 줍니다. 파일에 이미 `SessionStart` 항목이 있으면 배열을 교체하지 말고 해당 배열에 이 그룹을 추가하세요.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.cjs"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}
```

Matcher는 새 세션과 재개된 세션을 포함합니다. Anthropic은 `clear`, `compact` , `fork` 도 `SessionStart` 소스로 문서화하지만 이 예제에서는 의도적으로 제외합니다. `args` 필드는 exec 형식을 선택합니다. Claude Code는 `node` 를 호출하면서 해석된 프로젝트 스크립트 경로를 하나의 인수로 넘깁니다. 셸 따옴표 처리나 파싱을 거치지 않습니다. Windows에서 `node.exe` 는 실행 파일로 확인되어야 합니다. `.cmd` shim은 exec 형식에 적합하지 않습니다. 명령의 hook 제한 시간 5초는 스크립트의 Git 제한 시간 1.5초와 별개입니다.

## 스크립트 확인 후 Claude Code 확인하기

3. Claude Code를 열기 전에 프로젝트 터미널에서 스크립트를 실행하고 출력을 Git과 비교하세요. PowerShell에서는:

```powershell
$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current
```

Bash에서는:

```bash
CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/session-context.cjs
git branch --show-current
```

스크립트 stdout에는 정확히 한 줄인 `Current project branch: BRANCH`가 나와야 합니다. 여기서 `BRANCH` 는 스크립트의 문자 필터와 80자 제한을 적용한 Git 결과입니다. Detached HEAD는 `Current project branch: detached HEAD`를 출력합니다. 직접 확인은 이 터미널에서 로컬 스크립트가 작동한다는 것만 입증합니다. 준비 확인에서 일반 브랜치 결과는 Git과 일치했습니다. 누락되거나 잘못된 프로젝트 경로는 빈 stdout, stderr 진단, 종료 1을 냈습니다. 긴 이름 제한과 detached HEAD 대체값은 소스에서 검토했으나 해당 경우를 실행하지는 않았습니다.

4. 신뢰하는 프로젝트에서 새로운 **대화형** Claude Code 프로세스를 `claude --debug-file STARTUP_PRIVATE_LOG`와 함께 시작하고 직접 관리하는 비공개 경로를 사용하세요. 작업 공간 신뢰를 승인하기 전에 프로젝트 및 사용자 hook을 검토하세요. 디버그 로그에서 `SessionStart` 이벤트와 소스 `startup`, 선택된 스크립트 경로, 종료 상태, 출력 처리를 확인하세요. 도구 사용이나 독립적인 Git 읽기를 허용하지 말고 Claude에게 받은 브랜치 컨텍스트를 물어보세요. 답변과 디버그 기록을 직접 실행 결과와 비교하세요. Hook stdout은 Claude 컨텍스트에 들어가며 화면 UI에 메시지로 표시된다는 보장은 없습니다.
5. 해당 세션을 종료하세요. 별도 프로세스에서 `claude --debug-file RESUME_PRIVATE_LOG --resume`로 재개한 뒤 `SessionStart` `resume` 이벤트를 확인하고 도구나 Git 재조회 없이 질문 확인을 반복하세요. 두 디버그 로그에는 프로젝트 세부사항이 노출될 수 있으므로 비공개로 보관하세요. 비대화형 `-p` 또는 SDK 실행에는 같은 작업 공간 신뢰 요청이 없으며 저장소 hook이 자동 실행될 수 있으므로 이 확인에는 대화형 흐름을 사용하세요. Anthropic에 따르면 설정 파일 감시기가 보통 hook 설정 변경을 반영하지만 새 프로세스를 사용하면 시작과 재개를 더 명확히 테스트할 수 있습니다.

이후 정상적인 프로젝트 작업으로 브랜치가 바뀌면 직접 확인과 새 세션을 반복하여 한 줄이 바뀌는지 확인하세요. 이 안내서를 테스트했다고 주장하려고 일부러 브랜치를 바꾸지 마세요.

## 실행되지 않을 때

직접 스크립트 결과부터 확인한 다음 JSON 병합, `SessionStart` 철자, `startup|resume` matcher, 프로젝트 루트 경로, `node` 및 `git` 사용 가능 여부, 작업 공간 신뢰, 디버그 오류를 확인하세요. `CLAUDE_PROJECT_DIR` 가 없으면 `CLAUDE_PROJECT_DIR is unavailable` 를 stderr에 출력합니다. 프로젝트 경로 오류 또는 Git 실패 시 `Could not read the project branch; check Git and project path`를 출력합니다. 두 경우 모두 종료 1이며 컨텍스트 줄은 출력하지 않습니다. `SessionStart` 실패는 진단용이며 차단하지 않습니다. 동작 실행을 막는 관문으로 사용할 수 없습니다. Anthropic은 도구 동작 제어용으로 `PreToolUse` 를 문서화합니다. 이는 다른 이벤트이며 별도로 검토한 설계가 필요합니다.

스크립트는 로컬 Git만 실행하며 네트워크 요청이나 모델 호출은 하지 않습니다. Claude Code 시작, 재개, 질문 확인은 계정·제공업체·모델 사용 한도를 소비할 수 있습니다. [Anthropic 비용 안내](https://code.claude.com/docs/en/costs) 에서 최신 조건을 확인하세요. 이 안내서는 고정 가격을 제시하거나 유료 세션 테스트를 보고하지 않습니다.

대화가 진행 중인 상황에서 하는 별도 작업은 [Claude Code 세션 컨텍스트 검사 및 계속하기 안내](https://bigchange.ai/blog/claude-code-session-context-continue-guide) 에서 설명합니다. 그 안내는 이 시작 hook을 설정하지 않습니다.

## 출처 및 추가 자료

- [Anthropic, Claude Code hook 참조](https://code.claude.com/docs/en/hooks) — 2026년 10월 19일 확인한 최신 1차 명세입니다. `SessionStart` 소스와 matcher, exec 형식 `args`, 경로 자리표시자, stdout 컨텍스트, 설정 재로딩, 신뢰, 디버그 로그, 비차단 실패 동작을 설명합니다. 문서 근거이며 BIG CHANGE의 hook 실행이 아닙니다.
- [Anthropic, hook으로 동작 자동화하기](https://code.claude.com/docs/en/hooks-guide) — hook 설정과 테스트에 관한 공식 안내입니다. 위의 정확한 스크립트와 설정은 이 안내서를 위해 검토한 범위가 제한된 BIG CHANGE 예제이며 공급업체 테스트 결과를 복사한 것이 아닙니다.
- [Anthropic, Claude Code 설정](https://code.claude.com/docs/en/setup) — 설치 및 환경 요구사항입니다. 예제를 사용하기 전에 최신 플랫폼 지침을 확인하세요.
- [Anthropic, Claude Code 데이터 사용](https://code.claude.com/docs/en/data-usage) — 브랜치 정보를 모델 컨텍스트에 보내기 전에 검토할 제공업체의 최신 데이터 처리 조건입니다. 프로젝트 권한 승인은 별도 결정입니다.
- [Anthropic, 효과적인 비용 관리](https://code.claude.com/docs/en/costs) — 대화형 확인을 위한 최신 계정 및 사용 안내입니다. 로컬 Git 스크립트 자체는 모델이나 네트워크에 요청하지 않습니다.

## Sources

- [Claude Code hook 참조](https://code.claude.com/docs/en/hooks) — 2026년 10월 19일 승인된 스냅샷과 대조하고 집필 중 다시 확인한 최신 Anthropic 1차 매뉴얼입니다. SessionStart startup/resume 소스와 matcher 의미, exec 형식 command 및 args, 프로젝트 루트 자리표시자, 일반 stdout 컨텍스트, 설정 감시기, 작업 공간 신뢰, debug-file 검사, Windows 실제 실행 파일 규칙, 비차단 SessionStart 오류를 규정합니다. 제품 동작을 설명하며 BIG CHANGE는 Claude가 호출한 hook을 실행하지 않았습니다. 고정된 문서 개정일은 제시되지 않았습니다.
- [hook으로 동작 자동화하기](https://code.claude.com/docs/en/hooks-guide) — Anthropic의 공식 설정 및 테스트 안내입니다. 독자의 hook 구성과 진단 절차를 뒷받침하며 BIG CHANGE가 Claude Code 안에서 예제를 실행했다는 주장은 아닙니다. 기사에 나온 정확한 제한형 Node 스크립트와 설정은 별도로 검토한 로컬 구현 패킷에서 왔습니다.
- [Claude Code 고급 설정](https://code.claude.com/docs/en/setup) — 로컬 Claude Code 설정을 확인하기 위한 공식 설치·환경 참조입니다. 준비 과정에서 관찰한 버전은 2.1.301뿐이며 이 출처가 그 버전을 최소 요구사항으로 만드는 것은 아닙니다.
- [Claude Code 데이터 사용](https://code.claude.com/docs/en/data-usage) — 계정에 따라 달라지는 공식 데이터 처리 조건입니다. 이 기사는 Git 브랜치 정보를 모델 컨텍스트에 넣기 전에 이를 검토하도록 안내합니다. 필터링과 잘라내기는 브랜치 이름이 고객이나 사고의 기밀 세부사항을 드러내는 것을 막지 못합니다. 포괄적인 개인정보 보호 보장은 추론하지 않습니다.
- [효과적인 비용 관리](https://code.claude.com/docs/en/costs) — 대화형 시작·재개 질문 확인에 필요한 공식 계정·모델 사용 안내입니다. 로컬 스크립트 자체는 모델이나 네트워크에 요청하지 않지만 실제 Claude 세션은 요금제·제공업체·API 한도를 소비할 수 있습니다. 고정 가격이나 유료 테스트를 주장하지 않습니다.
- [Claude Code 세션의 컨텍스트를 검사하고 계속하는 방법](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — 이전 BIG CHANGE 기사 414는 맥락을 제공하는 내부 링크와 관계 분류에만 사용됩니다. 기존 대화를 검사하고 작업을 계속하는 방법을 다루며 이 hook 구현의 근거나 동일 사건의 직접적인 후속 관계는 아닙니다.