Claude Code를 실제 프로젝트에 적용할 때 참고하기 좋은 설정 예시입니다. `CLAUDE.md`를 중심으로 스킬, 서브에이전트, 훅, 커맨드 구성을 어떻게 묶어 운영하는지 볼 수 있어, Claude Code 설정을 처음 정리하는 분들에게 특히 유용합니다.

왜 널리 쓰이는지

이 자료는 `shanraisshan/claude-code-best-practice` 저장소의 `CLAUDE.md` 파일로, Claude Code 설정을 위한 best practices 예시로 소개되는 자료입니다. 단순한 설명 문서라기보다 실제 설정 구조를 보여주는 reference implementation 성격에 가깝습니다.

특히 Claude Code에서 자주 언급되는 구성 요소인 `skills`, `subagents`, `hooks`, `commands` 패턴을 한곳에서 확인할 수 있다는 점이 장점입니다. 개별 기능을 따로 보는 것보다, 여러 설정 요소가 어떤 역할 분담으로 연결되는지 파악하기 좋습니다.

무엇이 들어있는지

핵심은 Claude Code를 운영하기 위한 규칙과 설정 예시입니다. `CLAUDE.md` 안에서 프로젝트 작업 방식, 커맨드 구성, 에이전트와 스킬의 역할 분리 같은 패턴을 확인할 수 있습니다.

검색 요약 기준으로는 `Command → Agent → Skill` 아키텍처를 통해 `weather-orchestrator` 예시를 보여주는 것으로 알려져 있습니다. 즉, 사용자가 커맨드를 실행하고, 해당 커맨드가 적절한 에이전트 흐름으로 이어지며, 필요한 스킬을 활용하는 식의 구조를 참고할 수 있습니다.

또한 브라우저 자동화 MCP 사용, 커밋 단위 규칙 등 실제 개발 작업에서 지켜야 할 운영 규칙도 포함되어 있습니다. Claude Code를 단순 질의응답 도구가 아니라, 프로젝트 안에서 일정한 규칙을 따르는 작업 파트너로 설정하려는 경우 참고할 만합니다.

쓰는 법 요약

자료는 GitHub에서 바로 확인할 수 있습니다.

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

먼저 위 링크의 `CLAUDE.md`를 읽고, 현재 프로젝트에 필요한 항목만 골라 적용하는 방식이 좋습니다. 예를 들어 커밋 규칙, MCP 사용 방식, 커맨드와 에이전트 구조처럼 바로 필요한 부분부터 가져오고, 이후 `skills`, `subagents`, `hooks`, `commands` 구성을 프로젝트 상황에 맞게 나누어 정리하면 됩니다.

그대로 복사해 쓰기보다는 “어떤 규칙을 `CLAUDE.md`에 넣고, 어떤 작업을 커맨드·에이전트·스킬로 분리할지”를 참고하는 용도로 보는 편이 안전합니다. 실제 적용 전에는 팀의 개발 방식, 저장소 구조, 사용 중인 Claude Code 환경과 맞는지 확인하는 것을 권장합니다.