Claude Code 설정 구성 요소 설명

이것은 제가 EltexSoft에서 매일 사용하는 실제 Claude Code 구성입니다: 스택에 구애받지 않는 엔지니어링 '척추(spine)', 경로 글로브를 통해 파일별로 로드되는 플랫폼별 규칙 팩, 네 가지 스택에 걸친 42개의 서브 에이전트 목록, 커밋 가드를 포함한 후크와 자동 포맷터, 그리고 레포지토리 스캐폴더입니다. 이는 제가 42: The AI Builder's Stack에서 설명하는 것과 동일한 설정입니다. 유용한 부분만 가져가세요.

대부분의 사람들은 단일 CLAUDE.md를 게시하고 그것을 전체 설정이라고 부릅니다. 실제로 Claude Code를 신뢰할 수 있게 만드는 것은 구조입니다: 절대로 변하지 않는 전역 파일, 경로 글로브와 일치하는 파일을 Claude가 읽을 때만 로드되는 규칙들, 각 작업에 한정된 에이전트들, 그리고 문제가 되는 커밋을 사전에 막는 후크들이 그것입니다. 이것이 바로 여기 내용입니다.

hooks/guard-commit.sh | Claude Code Bash hook (PreToolUse)로, 에이전트가 force-push를 하거나 --no-verify를 사용하는 git hooks를 건너뛰는 것을 차단하고, 비(非)인간으로 커밋하거나, 커밋 메시지에 AI 출처 표기(attribution)를 작성하는 행위, 또는 명백한 비밀 정보(secrets)를 스테이징하는 것을 막습니다. 체인된 명령어의 모든 세그먼트는 개별적으로 검사됩니다. 따옴표로 묶인 텍스트, heredoc 본문, 치환(substitutions), 산술 연산은 먼저 데이터로 처리되어, 단순히 차단 플래그를 언급하는 커밋 메시지나 파일 본문으로는 절대 작동하지 않습니다. 즉, 체크가 분류할 수 없는 형태(어떤 형태의 쉘 래퍼, ${...} 내부의 치환, 커밋이나 푸시에서 따옴표 없이 사용된 패턴, 환경을 통해 전달되는 git config)는 추측하는 대신 거부됩니다. 이는 Claude가 사용하는 git 명령어에 대한 보호막이며, 사람이 자신의 터미널에서 git을 직접 입력하는 행위는 아닙니다. |
hooks/format.sh | 모든 스택에서 확장자별로 편집된 파일을 자동 포맷합니다. 포매터가 누락된 경우 오류를 발생시키지 않고 조용히 무시(no-op)됩니다. |
hooks/bootstrap-claude-md.sh | Claude Code SessionStart hook으로, 루트 CLAUDE.md 파일이 없는 git 저장소를 열 때, 표준 템플릿으로부터 이를 생성하도록 Claude에게 제안합니다 (사용자가 '예'라고 응답했을 때만 생성됨; §19는 감지 가능한 내용으로 채우고 나머지는 시간이 지남에 따라 완성됩니다). 전역 설정 디렉터리나 비(非)git 디렉터리, 그리고 파일이 이미 존재하는 경우에는 작동하지 않습니다. 오직 검사하고 제안하는 역할만 하며, 스스로 파일을 작성하지는 않습니다. |
tests/hooks/ | 세 가지 모든 hook에 대한 행위 테스트입니다: stdin의 JSON 페이로드, stdout의 종료 코드 등 규칙별, 과거 회귀(regression) 케이스별로 하나씩 존재합니다. 기본 bash 3.2와 jq를 사용하며, CI(.github/workflows/gate.yml)에서는 모든 PR과 함께 나머지 품질 게이트와 함께 이를 실행합니다. |
skills/new-repo/ | 스캐폴더 스킬입니다: 적절한 CLAUDE.md, .gitignore, 품질 게이트, 그리고 릴리스 워크플로우를 갖춘 새 저장소를 생성합니다. 웹(web)과 Android는 스캐폴딩하며; iOS와 컴퓨팅은 규칙(rule) + 에이전트 패키지 형태로 배포됩니다 (아직 스캐폴더가 없음).

docs/ | 온디맨드 참조를 위한 스파인 포인트 (전체 명단 테이블, Phase-3 검토 체크리스트, 오류 복구 테이블, PR 템플릿, 확장 노트). ~/.claude/docs/에 설치되며, 스텁이 이를 참조할 때만 로드됩니다.
templates/ | 빈 프로젝트 CLAUDE.md 템플릿 (일반 + 컴퓨팅)으로, 새 레포지토리에 복사하여 채우는 용도입니다.
examples/CLAUDE.example-web.md | 직접 작성하기 전에 '완료된' 상태가 어떤 모습인지 볼 수 있도록 미리 채워진 예시 파일입니다.
STRUCTURE.md | 전체 레이아웃, 설치 단계, 그리고 두 개의 설정 파일 스왑 방식에 대해 설명합니다. 이것을 먼저 읽으세요.

두 가지 계층이 있습니다. 글로벌(global) 계층(~/.claude/CLAUDE.md + rules/ + agents/ + hooks/)은 무엇을 구축하든 상관없이 항상 참인 모든 것입니다. 프로젝트(project) 계층은 레포지토리 루트에 있는 짧은 CLAUDE.md 파일로, 해당 프로젝트에만 특정한 내용(§19: 스택, 품질 게이트, 릴리스 포인터, 규정 준수 범위)을 담고 있습니다. 스파인은 프롬프트 캐싱되며 절대 변경되지 않습니다. 프로젝트 파일만이 레포지토리마다 수정하는 유일한 것입니다. 규칙은 경로 트리거에 의해 특화됩니다 (Claude가 파일을 읽을 때 그 파일의 paths: glob이 일치하면 패키지가 로드됨). 에이전트는 이름 오버라이드를 통해 특화됩니다 (레포지토리의 .claude/agents/<name>.md가 같은 이름의 글로벌 에이전트를 덮어씁니다). 둘 다 레포지토리를 미리 스캔하지 않습니다. 한 번 구성하면 대부분 그대로 둡니다.

Mac/Linux 환경에서 Claude Code가 이미 설치된 상태입니다. 전체 단계와 레포지토리별 설치 방법은 STRUCTURE.md에 있습니다. 먼저 후크 전제 조건인 jq(guard-commit.sh는 이것 없이는 폐쇄 실패)를 설치합니다: brew install jq (macOS) / sudo apt-get install jq (Debian/Ubuntu); 가드에는 또한 git 2.28 이상이 필요합니다. 그런 다음:

git clone https://github.com/roadhero/claude-code-setup.git && cd claude-code-setup
mkdir -p ~/.claude/rules ~/.claude/agents ~/.claude/hooks ~/.claude/skills
cp CLAUDE.md ~/.claude/CLAUDE.md
...

그런 다음 레포지토리별로 템플릿을 복사하여 프로젝트 CLAUDE.md로 사용하고 §19를 채웁니다. 작동하는 예시는 examples/에서 확인하세요.

이 설정은 저희 팀의 작업 방식에 맞춰져 있어 주관적입니다. git 규칙은 보호된 브랜치(protected branches)를 사용하는 PR 기반 흐름을 가정합니다. hooks는 포맷터가 설치되어 있다고 가정하며 (설치되지 않아도 깨끗하게 작동합니다). 컴퓨팅 스택은 C++/CUDA/Python 시스템에 적합하며, 웹 앱만 배포한다면 과도한 구성입니다. 필요 없는 것은 제거하세요. 핵심은 저의 정확한 설정을 채택하는 것이 아니라, 실제 작동하는 예시를 보고 자신만의 것을 구축하는 것입니다.

• Claude Code에 대한 장에서는 이 모든 것의 '이유'를 깊이 있게 다룹니다 – 전체 버전은 Sub-Etha Press에서 확인하실 수 있습니다.
• 도서:
  42: The AI Builder's Stack이 2026년 8월 15일 Amazon에서 출시됩니다. 다른 샘플 장은 eltexsoft.com에서 확인 가능합니다.

MIT 라이선스입니다. 사용하고, 포크(fork)하고, 변경하세요. 출처 표기는 필요 없습니다.