설정 파일들이 무작위 폴더에 흩어지는 것을 방지하기 위한 Claude Code 프로젝트 구조 분석입니다.

Claude Code 프로젝트를 제대로 설정하고 있다면, 모든 요소는 다음 위치에 존재합니다.

1). claude.md - 모든 세션을 로드합니다
↳ 프로젝트 개요, 기술 스택 (tech stack), 코딩 컨벤션 (coding conventions), 아키텍처 노트 (architecture notes)가 모두 하나의 파일에 담깁니다.

2). .mcp.json - MCP 서버 통합 관리
↳ GitHub, Jira, Slack, 데이터베이스 등이 포함되며, 프로젝트 루트 (project root)에 위치하고 Git을 통해 팀 전체와 공유됩니다.

3). settings.json - 컨트롤 센터
↳ 권한 (permissions), 도구 액세스 (tool access), 환경 변수 (env variables), 훅 (hooks) 설정이 모두 한 곳에 고정됩니다.

4). rules/*.md - 커스텀 규칙
↳ 각 .md 파일은 자체적인 모듈로서 claude.md에 들어갈 수 없는 내용들을 명시합니다.

5). commands/*.md - 커스텀 명령
↳ /project:command-name 형식으로 호출하며, 모든 .md 파일은 하나의 명령어가 됩니다. 사용자 입력을 위한 $arguments를 지원하여 PR 리뷰, 배포 (deploys), 스캐폴딩 (scaffolding)에 완벽합니다.

6). skills/<name>/skill.md - 자동 트리거 기술 (skills)
↳ 작업 컨텍스트 (task context)를 기반으로 실행되거나 /skill-name으로 직접 호출할 수 있습니다. 필요할 때만 로드되어 컨텍스트 (context)를 가볍게 유지합니다.

7). agents/*.md - 특화된 서브 에이전트 (sub-agents)
↳ 격리된 컨텍스트 (isolated context)에서 실행되며, 고유의 시스템 프롬프트 (system prompt), 도구 (tools), 권한 (permissions)을 가집니다. @agent-name으로 호출합니다.

8). hooks/*.sh - 이벤트 기반 스크립트
↳ LLM의 추측이 아닌 셸 명령 (shell commands)을 통해 Claude가 결정론적 (deterministic)인 동작을 수행하도록 만듭니다.