도입

Claude Code를 팀이나 프로젝트에서 꾸준히 쓰다 보면 “어떤 규칙을 CLAUDE.md에 적어야 하는지”, “명령·에이전트·스킬·훅을 어떻게 나눠야 하는지”가 금방 막힙니다.

`claude-code-best-practice`는 이런 설정 구조를 한 저장소에서 참고할 수 있게 모아둔 실전형 예시입니다. 단순한 설명 문서라기보다, Claude Code 프로젝트 설정을 어떻게 구성할지 볼 수 있는 레퍼런스에 가깝습니다.

왜 좋은가 / 왜 유명한가

- Claude Code의 핵심 구성요소를 한 번에 비교해 볼 수 있습니다.

원문 README에는 Subagents, Commands, Skills, Workflows, Hooks, MCP Servers, Settings, Status Line, Memory, Checkpointing, CLI Startup Flags 등이 표로 정리되어 있습니다.

- 실제 파일 위치 기준으로 설명되어 있습니다.

예를 들어 Subagents는 `.claude/agents/.md`, Commands는 `.claude/commands/.md`, Skills는 `.claude/skills//SKILL.md`, Memory는 `CLAUDE.md`와 `.claude/rules/` 같은 식으로 위치가 함께 제시됩니다.

- Claude Code 공식 문서와 함께 읽기 좋습니다.

README의 각 항목은 Claude Code 공식 문서 링크와 저장소 내부의 best-practice, implementation 문서로 연결되는 구조입니다.

- “vibe coding”에서 “agentic engineering”으로 넘어가는 실전 패턴을 보여주는 자료로 소개되어 있습니다.

저장소 설명 자체가 “from vibe coding to agentic engineering - practice makes claude perfect”로 되어 있어, 단순 프롬프트 모음보다 구조화된 Claude Code 운영 방식을 참고하는 데 초점이 있습니다.

무엇을 할 수 있나 / 무엇이 들어있나

원문 README에서 확인되는 주요 구성은 다음과 같습니다.

- Subagents

Claude Code의 하위 에이전트 구성을 참고할 수 있습니다. 위치는 다음과 같이 안내되어 있습니다.

.claude/agents/.md

- Commands

Slash commands 패턴을 확인할 수 있습니다. 원문 기준 위치는 다음과 같습니다.

.claude/commands/.md

- Skills

Claude Code Skills 구성을 참고할 수 있습니다. 원문 README에는 공식 Skills 저장소와 모노레포용 Skills 관련 문서도 함께 연결되어 있습니다.

.claude/skills//SKILL.md

- Workflows

워크플로 예시로 `weather-orchestrator.md`가 언급되어 있습니다.

.claude/commands/weather-orchestrator.md

- Hooks

Claude Code Hooks 구성 위치가 안내되어 있습니다.

.claude/hooks/

- MCP Servers

MCP 서버 설정은 다음 파일들과 연결되어 있습니다.

.claude/settings.json
.mcp.json

- Settings

Claude Code 설정은 `.claude/settings.json`에 위치합니다. README에서는 Permissions, Model Config, Output Styles, Sandboxing, Keybindings, Auto Mode Config 등 공식 문서 항목과 함께 연결되어 있습니다.

.claude/settings.json

- Status Line

상태 표시줄 설정 역시 `.claude/settings.json`과 연결되어 있습니다.

.claude/settings.json

- Memory

Claude Code 메모리와 규칙 구성 위치가 구체적으로 제시되어 있습니다.

CLAUDE.md
.claude/rules/
~/.claude/rules/
~/.claude/projects//memory/

- Checkpointing

원문 README에는 Checkpointing이 “automatic (file-edit tracking)”으로 표시되어 있습니다. 별도 파일 위치가 아니라 파일 편집 추적 기반 자동 기능으로 정리되어 있습니다.

- CLI Startup Flags

Claude CLI 시작 플래그는 다음 형식으로 안내되어 있습니다.

claude [flags]

설치와 사용법

원문 README 발췌 범위에는 이 저장소를 설치하는 명령이나, 특정 패키지를 내려받는 명령이 포함되어 있지 않습니다. 따라서 임의의 `git clone`, `npm install`, `claude` 실행 명령은 이 글에서 새로 만들지 않습니다.

대신 이 자료는 “내 프로젝트의 Claude Code 설정을 어떻게 구성할지 참고하는 예시 저장소”로 쓰면 됩니다. 먼저 아래 원문 링크에서 `CLAUDE.md`와 `.claude` 관련 파일 구조를 확인합니다.

https://github.com/shanraisshan/claude-code-best-practice/blob/main/CLAUDE.md

Claude Code 설정을 프로젝트에 반영할 때는 README에 나온 위치 기준을 그대로 참고합니다.

CLAUDE.md
.claude/agents/.md
.claude/commands/.md
.claude/skills//SKILL.md
.claude/hooks/
.claude/settings.json
.mcp.json
.claude/rules/

예를 들어 프로젝트 공통 규칙을 정리하려면 `CLAUDE.md`를 먼저 확인하는 방식이 적합합니다. 이 파일은 Claude Code가 프로젝트 문맥과 작업 규칙을 이해하는 데 쓰이는 핵심 메모리 파일로 안내되어 있습니다.

CLAUDE.md

명령어 기반 작업 흐름을 만들고 싶다면 Commands 항목을 봅니다. README 기준으로 명령 파일은 `.claude/commands/.md` 위치에 둡니다.

.claude/commands/.md

특정 역할을 맡는 하위 에이전트 패턴을 참고하려면 Subagents 항목을 확인합니다.

.claude/agents/.md

반복 가능한 기능 단위를 Skills로 나누고 싶다면 Skills 위치를 기준으로 구조를 살펴보면 됩니다.

.claude/skills//SKILL.md

MCP 서버나 Claude Code 세부 설정까지 같이 다루는 경우에는 다음 파일을 확인합니다.

.claude/settings.json
.mcp.json

실제 적용 순서는 다음처럼 잡으면 초보자도 무리 없이 시작할 수 있습니다.

1. 원문 링크에서 `CLAUDE.md`를 먼저 읽습니다.

2. 내 프로젝트에 필요한 규칙이 “메모리”, “명령”, “에이전트”, “스킬”, “훅”, “MCP 설정” 중 어디에 가까운지 나눕니다.

3. README 표의 Location 항목을 기준으로 대응되는 파일 위치를 확인합니다.

4. 저장소의 예시 구조를 참고해 내 프로젝트 설정 파일을 작성합니다.

5. Claude Code 공식 문서 링크를 함께 확인해 현재 사용하는 Claude Code 버전에서 지원되는지 검토합니다.

주의할 점

- 원문 README 발췌에는 설치 명령이 없습니다.

자료를 적용할 때는 저장소 내용을 참고하되, 실행 명령이나 설치 절차는 Claude Code 공식 문서와 해당 저장소의 최신 README를 확인해야 합니다.

- 설정 파일에는 권한과 보안 이슈가 생길 수 있습니다.

특히 Hooks, MCP Servers, Permissions, Sandboxing 관련 설정은 외부 도구 실행이나 파일 접근과 연결될 수 있으므로 그대로 복사하기보다 프로젝트 환경에 맞게 검토해야 합니다.

- 예시 구조와 내 프로젝트 구조가 다를 수 있습니다.

이 저장소는 “참고용 베스트 프랙티스” 성격이 강합니다. 모든 항목을 한 번에 도입하기보다 `CLAUDE.md`, Commands, Subagents처럼 효과가 큰 부분부터 단계적으로 적용하는 편이 안전합니다.

출처와 다운로드

원문 자료는 아래 GitHub 링크에서 확인할 수 있습니다.

https://github.com/shanraisshan/claude-code-best-practice/blob/main/CLAUDE.md

게시글 하단 첨부파일에서도 자료를 받을 수 있습니다. 최신 내용과 연결 문서는 GitHub 원문을 함께 확인하는 것을 권장합니다.