Claude Code - 문서가 알려주지 않는 설정 가능한 모든 것

Claude Code의 문서화되지 않은 Hook 기능과 상세 설정을 활용한 맞춤형 개발 환경 구축 방법을 소개한다.

@anthropic-ai/[email protected] 버전을 기준으로, 공식 문서에 명시되지 않은 Hook, Skills, Agents의 상세 설정 및 제어 방법을 다룬다.

Hook을 통한 실시간 동작 제어 Hook은 단순히 실행 여부를 결정하는 것을 넘어, stdout의 이벤트별 JSON 필드를 통해 Claude Code의 동작을 실시간으로 수정할 수 있다.

PreToolUse: updatedInput으로 도구 실행 전 명령어를 수정하거나(예: git push를 --dry-run으로 변경), permissionDecision으로 권한을 강제할 수 있다.
SessionStart: watchPaths로 특정 파일을 감시하거나, additionalContext를 통해 세션 전체에 유지될 컨텍스트를 주입할 수 있다.
PostToolUse: updatedMCPToolOutput을 사용하여 Claude가 받는 MCP 도구의 응답을 수정할 수 있다.

설정 및 구성 체계

설정 파일: 개인 설정은 ~/.claude/settings.json, 프로젝트 설정은 .claude/settings.json에 위치하며, 프로젝트 설정은 Git을 통해 팀과 공유 가능하다.
Skills & Agents: 숨겨진 frontmatter를 통해 모델 종류, 작업 범위(scope), 지속 메모리, MCP 의존성 등을 세밀하게 제어할 수 있다.

이러한 기능을 활용하면 Claude Code를 단순한 도우미를 넘어 프로젝트 특성에 최적화된 학습형 개발 환경으로 구성할 수 있다.