settings.json 문서

범위. 이 문서는 Claude Code 어댑터 의 훅 배선 파일(settings.json)을 설명합니다. 다른 하니스 는 각자의 네이티브 설정 표면을 사용합니다 — 각 어댑터의 등가 구성 진입점은 site/content/docs/harnesses/<harness>.mdx 를 참조하세요.

개요Copy Anchor Link

settings.json 은 Apothem 생태계를 위한 Claude Code 훅 실행을 구성합니다. 어떤 훅이 어떤 이벤트에서 발화하는지, 그 타임아웃, 그리고 최상위 권한 표면을 선언합니다. Claude Code 가 지원되는 모든 플랫폼에서 ~/.claude/settings.json 을 로드하기 때문에 Apothem 은 하나의 정규 템플릿만 배포합니다.

Python 전용 런타임Copy Anchor Link

구성된 모든 훅은 Claude Code의 exec 형식 명령 구조를 사용합니다. 배포되는 템플릿에는 ${PYTHON_BIN}과 ${HARNESS_ROOT} 토큰이 들어 있으며, apothem install은 ${PYTHON_BIN}을 해석된 절대 인터프리터 경로로 바꿉니다:

{
  "type": "command",
  "command": "${PYTHON_BIN}",
  "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "PreToolUse", "pretooluse-write"]
}

apothem install 은 이 토큰을 하니스 루트의 절대 경로 (슬래시 형식, Windows·macOS·Linux 에서 유효)로 렌더링하므로, 설치된 settings.json 은 ~/.claude/.apothem/support/hooks/dispatch.py 에 머티리얼라이즈된 디스패처를 직접 호출합니다. 디스패처와 컨포미티 게이트(~/.claude/.apothem/support/conformity/gate.py, 그 옆 ~/.claude/.apothem/support/schemas/ 에 schema 픽스처가 있음)는 모두 독립형 표준 라이브러리 스크립트입니다 — 호스트에 임포트 가능한 apothem 패키지가 필요하지 않으며, 하나의 템플릿이 모든 플랫폼을 처리합니다.

훅 구성 SchemaCopy Anchor Link

권한Copy Anchor Link

"permissions": {
  "allow": ["Read", "Glob", "Grep"]
}

allow 에 없는 도구는 호출별 명시적 승인 또는 워크스페이스 수준 권한이 필요합니다. 읽기 전용 도구는 사전 승인되어 있으며, 쓰기 작업(Write, Edit, NotebookEdit, Bash)은 PreToolUse 검증기를 거칩니다.

훅 이벤트Copy Anchor Link

타임아웃 값은 정규 훅 이벤트 예산을 반영합니다 — 아래 표는 독자 편의를 위해 이를 재현한 것이며, 정규 출처가 우선합니다.

이 템플릿은 네 개의 이벤트를 등록합니다. PreCompact나 PostCompact는 등록하지 않습니다. Codex와 Qwen Code 템플릿은 이를 등록하며, 훅 참조가 하니스별로 나열합니다.

dispatch.py 는 이벤트 화이트리스트에 UserPromptSubmit 과 Notification 도 추가로 받아들입니다. 둘 다 배포된 템플릿에서는 배선되어 있지 않으며, 동일한 로케이터 + 디스패치 패턴의 matcher 블록을 추가하면 활성화됩니다.

최상위 필드Copy Anchor Link

검증Copy Anchor Link

세 개의 검증기가 점점 더 엄격한 정도로 훅 표면을 다룹니다.

# 구조 + Python 위생(빠름, 오프라인)
python scripts/dev/validate_hooks.py

# 전체 생태계(구조 + frontmatter + 위임된 훅 검사)
python scripts/dev/validate_ecosystem.py

# 적대적 스윕(구성된 각 훅 명령을 저하된 입력으로 공격)
python scripts/dev/chaos_pass.py

훅 또는 설정 변경을 커밋하기 전에 세 가지 모두 0으로 종료해야 합니다.

단일 이벤트의 임시 스모크 테스트:

python src/apothem/hooks/dispatch.py --event-name SessionStart

예상 출력: hookSpecificOutput 을 포함하는 단일 행 JSON 엔벨로프.

흔한 문제Copy Anchor Link

SessionStart 가 타임아웃됨Copy Anchor Link

가장 흔하게는 find-python 로케이터가 Microsoft Store 심을 발견하고 실제 인터프리터 해석에 실패하는 경우입니다. 확인하세요.

python src/apothem/hooks/dispatch.py --event-name SessionStart

명령이 유효한 JSON 엔벨로프를 출력하는데 Claude Code 패널에 타임아웃이 표시되면, settings.json 에서 해당 이벤트의 timeout 을 높이세요. 명령이 셸 수준에서 실패하면, 실제 CPython 3.10+ 를 설치하고 그것이 PATH 에 있거나 로케이터로 발견 가능한지 확인하세요.

모든 Write/Edit 가 차단됨Copy Anchor Link

PreToolUse 가 하니스 설치 루트(Claude Code 어댑터의 경우 ~/.claude/) 외부에 작성되는 내용 속 플랜 내부 용어를 플래그하고 있습니다. 내용에 CM-7 위반이 없는지 검토하세요( src/apothem/rules/persistent-conventions-vigilance.md 참조). 코드베이스 산출물에는 도메인 언어만 사용합니다.

settings.json 이 로드되지 않음Copy Anchor Link

Claude Code 는 ~/.claude/settings.json 을 읽습니다. Apothem 이 기대되는 하니스 루트에 설치되었는지 확인하고 파일 변경 후 세션을 재시작하세요.

훅이 조용히 아무 동작도 하지 않음Copy Anchor Link

훅 계약은 "항상 0으로 종료하고, 항상 유효한 JSON 을 방출한다"입니다. 인터프리터를 찾을 수 없으면 로케이터가 빈 값을 반환하고 명령은 no-op 이 됩니다. chaos_pass.py 를 실행해 구성된 각 훅이 유효한 엔벨로프를 반환하는지 확인하세요 — 라이브 세션이 숨길 저하된 해석 경로를 잡아냅니다.

계층화된 우선순위Copy Anchor Link

Claude Code 는 우선순위가 증가하는 순서로 세 계층을 합성하여 유효 설정 객체를 해석합니다.

상위 계층 값은 리프 키 수준에서 하위 계층 값을 오버라이드합니다 — 프로젝트 계층과 사용자 로컬 계층 모두 permissions.allow 항목을 선언하면 합집합이 취해지고, 둘 다 theme 같은 스칼라를 선언하면 사용자 로컬 값이 이깁니다. 정확한 키별 병합 시맨틱은 Claude Code 하니스 가 소유합니다.

사용자 로컬 오버라이드 만들기Copy Anchor Link

1. examples/harnesses/claude-code/settings.local.example.json을 <harness-root>/settings.local.json으로 복사합니다. settings.local.json 파일 이름은 .gitignore 패턴과 일치하므로, 이 파일은 버전 관리에 올라가지 않습니다.
2. 로컬 사본을 편집합니다. 재정의할 키만 남기세요. 하니스가 계층을 합성하므로, 없는 키는 프로젝트 계층에서 상속됩니다.
3. 저장하기 전에 파일이 유효한 JSON으로 파싱되는지 확인하세요. 하니스는 세션 시작 시 잘못된 형식의 JSON을 거부합니다.