# .claude/ 폴더 구조 분석

> Clean Markdown view of GeekNews topic #27941. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=27941](https://news.hada.io/topic?id=27941)
- GeekNews Markdown: [https://news.hada.io/topic/27941.md](https://news.hada.io/topic/27941.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-03-28T09:53:17+09:00
- Updated: 2026-03-28T09:53:17+09:00
- Original source: [blog.dailydoseofds.com](https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder)
- Points: 65
- Comments: 1

## Summary

`.claude/` 폴더의 `CLAUDE.md`, `commands/`, `skills/`, `agents/`, `settings.json` 등 **전체 구조를 체계적으로 정리한 레퍼런스 글**입니다. 이번 주 gstack이나 Harness 같은 프로젝트를 보면서 "이 스킬/에이전트 파일이 어디에 어떻게 놓이는 거지?" 싶었던 분이라면 이 글이 그 지도 역할을 합니다. 다만 HN 댓글에서 반복적으로 나오는 조언이 있는데  **CLAUDE.md는 짧게 유지하고, 남이 만든 스킬을 무작정 설치하지 말라**는 것입니다. 설정을 과하게 쌓으면 오히려 모델 성능이 떨어지고, Anthropic 팀도 30일마다 초기화한다는 이야기가 있을 정도입니다.

## Topic Body

- `.claude/` 폴더는 **Claude Code의 핵심 제어 디렉터리**로, 프로젝트별 규칙·명령·권한·메모리 상태를 관리함  
- `CLAUDE.md`는 Claude의 **행동 원칙과 프로젝트 규칙을 정의하는 중심 파일**로, 여러 계층의 설정을 병합해 적용함  
- `commands/`, `skills/`, `agents/` 폴더는 각각 **사용자 정의 명령, 자동 워크플로, 전문 서브에이전트**를 구성해 협업 효율을 높임  
- `settings.json`은 **명령 실행 권한과 파일 접근 범위**를 제어하며, `settings.local.json`으로 개인별 오버라이드가 가능함  
- 전체 구조는 Claude에게 **프로젝트의 정체성과 규칙을 전달하는 프로토콜**로 작동해, 명확한 설정이 생산성과 협업 효율을 극대화함  
  
---  
  
### .claude/ 폴더 구조와 구성 요소  
- `.claude/` 폴더는 **Claude Code의 동작을 제어하는 핵심 디렉터리**로, 프로젝트별 규칙·명령·권한·메모리 상태를 관리  
- 프로젝트 루트의 폴더는 **팀 단위 설정**을 포함하며 Git에 커밋됨  
- 홈 디렉터리(`~/.claude/`)의 폴더는 **개인 설정과 세션 기록**을 저장하며, 자동 메모리 및 개인 명령을 포함  
- ## CLAUDE.md — Claude의 지침서  
  - Claude Code 세션 시작 시 가장 먼저 읽는 파일로, **Claude의 행동 원칙과 프로젝트 규칙을 정의**  
  - 프로젝트 루트의 `CLAUDE.md`는 팀 공통 규칙, `~/.claude/CLAUDE.md`는 **전역 개인 규칙**, 하위 폴더의 `CLAUDE.md`는 **폴더별 규칙** 담당  
  - Claude는 여러 `CLAUDE.md` 파일을 **병합하여 적용**  
  - 권장 내용은 빌드·테스트 명령, 주요 아키텍처 결정, 비직관적 제약사항, 네이밍·에러 처리 규칙 등  
  - **200줄 이하 유지**가 권장되며, 과도한 길이는 Claude의 지침 준수율을 저하시킴  
- ## CLAUDE.local.md — 개인별 오버라이드  
  - 팀 공통 규칙과 별도로 **개인 선호를 반영**할 수 있는 파일  
  - 프로젝트 루트에 `CLAUDE.local.md`를 생성하면 Claude가 이를 함께 읽음  
  - `.gitignore`에 자동 포함되어 **저장소에 커밋되지 않음**  
- ## rules/ 폴더 — 모듈형 규칙 관리  
  - `CLAUDE.md`가 커질 경우 `.claude/rules/` 폴더로 분리해 관리  
  - 각 규칙 파일은 **주제별로 분리**되어 유지보수가 용이  
    - 예: `code-style.md`, `testing.md`, `api-conventions.md`, `security.md`  
  - YAML 프런트매터의 `paths` 필드를 사용하면 **특정 경로에만 적용되는 규칙** 지정 가능  
    - 예: `src/api/**/*.ts` 경로에만 API 규칙 적용  
  - 경로 지정이 없는 규칙은 모든 세션에 항상 로드됨  
- ## commands/ 폴더 — 사용자 정의 슬래시 명령  
  - `.claude/commands/` 폴더의 각 Markdown 파일은 **슬래시 명령(/)** 으로 등록됨  
    - 예: `review.md` → `/project:review`, `fix-issue.md` → `/project:fix-issue`  
  - `!` 백틱 구문으로 **셸 명령 실행 결과를 Claude 프롬프트에 삽입** 가능  
    - 예: `!git diff main...HEAD`  
  - `$ARGUMENTS` 변수를 사용해 명령 실행 시 **인자 전달** 가능  
    - 예: `/project:fix-issue 234` → GitHub 이슈 234 내용 자동 로드  
  - 프로젝트 명령은 팀과 공유되며, 개인 명령은 `~/.claude/commands/`에 저장되어 **모든 프로젝트에서 사용 가능**  
- ## skills/ 폴더 — 자동 실행 워크플로  
  - **명령과 유사하지만 자동으로 트리거되는 워크플로**로 작동  
  - Claude가 대화 내용을 분석해 **적절한 상황에서 자동 실행**  
  - 각 스킬은 하위 폴더의 `SKILL.md` 파일로 정의되며, YAML 프런트매터로 **트리거 조건과 허용 도구** 지정  
    - 예: `security-review` 스킬은 보안 관련 대화 시 자동 실행  
  - 스킬 폴더에는 `DETAILED_GUIDE.md` 등 **보조 문서나 템플릿 파일** 포함 가능  
  - 개인 스킬은 `~/.claude/skills/`에 저장되어 전역적으로 사용 가능  
- ## agents/ 폴더 — 전문 서브에이전트  
  - `.claude/agents/` 폴더에는 **특정 역할을 수행하는 서브에이전트(persona)** 정의  
  - 각 에이전트는 독립된 시스템 프롬프트, 모델, 도구 접근 권한을 가짐  
    - 예: `code-reviewer.md`, `security-auditor.md`  
  - `tools` 필드로 접근 가능한 도구를 제한해 **보안 및 역할 분리** 실현  
  - `model` 필드로 작업에 맞는 Claude 모델(예: Haiku, Sonnet, Opus) 선택 가능  
  - Claude는 필요 시 해당 에이전트를 **별도 컨텍스트에서 실행**해 결과만 요약 보고  
- ## settings.json — 권한 및 프로젝트 설정  
  - `.claude/settings.json`은 Claude의 **명령 실행 권한과 파일 접근 범위**를 정의  
  - `$schema` 필드는 VS Code 등에서 **자동 완성과 유효성 검사** 지원  
  - `allow` 목록은 **자동 승인 명령**, `deny` 목록은 **완전 차단 명령** 지정  
    - 예: 허용 — `Bash(npm run *)`, `Read`, `Write`, `Edit`  
    - 차단 — `Bash(rm -rf *)`, `Bash(curl *)`, `.env` 파일 읽기  
  - 목록에 없는 명령은 실행 전 **사용자 확인 요청**  
  - 개인별 권한 변경은 `.claude/settings.local.json`에 저장되며 Git에 포함되지 않음  
- ## ~/.claude/ 폴더 — 전역 설정 및 메모리  
  - `~/.claude/CLAUDE.md`는 **모든 프로젝트에 공통 적용되는 개인 지침**  
  - `~/.claude/projects/`는 **프로젝트별 세션 기록과 자동 메모리** 저장  
    - Claude가 학습한 명령, 패턴, 구조적 통찰을 유지  
    - `/memory` 명령으로 조회 및 수정 가능  
  - `~/.claude/commands/`, `~/.claude/skills/`, `~/.claude/agents/`는 **전역 개인 명령·스킬·에이전트** 저장소  
- ## 전체 구조 예시  
  ```  
  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  ```  
- ## 초기 설정 단계  
  - **1단계:** `/init` 명령으로 기본 `CLAUDE.md` 생성 후 핵심 내용만 남김  
  - **2단계:** `.claude/settings.json` 작성, 실행 허용·차단 규칙 정의  
  - ### 3단계:**자주 사용하는 워크플로(예: 코드 리뷰, 이슈 수정)에 맞는**명령 추가  
    - **4단계:** `CLAUDE.md`가 커지면 `.claude/rules/`로 분리  
    - **5단계:** `~/.claude/CLAUDE.md`에 개인 선호 규칙 추가  
  
### 핵심 인사이트  
- `.claude/` 폴더는 **Claude에게 프로젝트의 정체성과 규칙을 전달하는 프로토콜**  
- `CLAUDE.md`가 가장 중요한 파일이며, 이를 명확히 정의할수록 **Claude의 생산성이 극대화**  
- 나머지 구성요소는 이를 보완하는 최적화 계층으로, 점진적으로 확장 가능  
- 명확한 설정은 **Claude의 수정 요청 감소와 효율적 협업**으로 이어짐  
  
### 추가 논의  
- `settings.json`의 **deny 리스트는 인간 사용 시 안전하지만**, 에이전트 모드에서는 Bash 접근으로 인해 추가 보호 필요  
- OneCLI는 네트워크 수준에서 **자격 증명 토큰을 대체하는 프록시 계층**을 제공해 비밀정보 노출을 방지  
- 향후 **에이전트 모드 전용 .claude 설정**(규칙·권한·스킬 분리)의 필요성 제기  
- 최신 문서에 따르면 **명령(commands)** 과 **스킬(skills)** 이 통합되어, `.claude/commands/deploy.md`와 `.claude/skills/deploy/SKILL.md`가 동일하게 `/deploy` 명령을 생성하며, 스킬은 추가 기능(보조 파일, 자동 트리거 등)을 지원

## Comments



### Comment 54024

- Author: neo
- Created: 2026-03-28T09:53:17+09:00
- Points: 2

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=47543139) 
- AI 에이전트 **툴킷 구축**이 마치 완벽한 생산성 세팅을 찾는 것처럼 느껴짐  
  블로그 글과 유튜브를 보며 루틴을 만들지만, 결국 단순한 **할 일 목록**으로 꾸준히 일하는 사람이 더 앞서감  
  내 경험상 **Plain Claude**에게 계획을 세우고 검토한 뒤 실행시키는 단순한 방식이 여전히 가장 잘 작동함
  - 대규모 코드베이스나 분산 시스템에서는 이야기가 다름  
    에이전트가 데이터를 파이핑하고, 요청을 만들고, 시스템을 추적하며 코드를 업데이트하는 **기술적 스킬**이 개발 효율을 비약적으로 높임  
    1천만 라인 규모의 코드에서 생산성이 크게 향상되었고, 그중 실제 코드 생성이 차지하는 비중은 5%도 안 됨  
    대부분은 테스트와 검증용 **툴체인**을 빠르게 만드는 능력 덕분임
  - 많은 사람들이 이 함정에 빠져 돈을 쓰고 있음  
    사실 자신이 **무엇을 원하는지 명확히 알고 잘 전달**할 수 있다면 AI로도 충분히 많은 일을 할 수 있음  
    대부분은 그걸 모름. 그래서 계획을 세우게 하는 과정이 이해를 얻는 **지름길**이 됨
  - 나는 PM으로서 에이전트가 시간을 절약하고 **출력의 복리 효과(compounding)** 를 주길 바람  
    하지만 세션마다 컨텍스트를 반복하고 .md 파일을 복사하는 비효율이 있음  
    지금의 목표는 이 **반복 제거**임.  
    컨텍스트를 축적하는 ‘context bank’를 어떻게 관리하는지 궁금함 — 예를 들어 “내 역할, 담당 제품, 최신 문서” 같은 기본 정보들  
    문서가 중복되고 오래된 게 많아 단순히 Drive 전체를 연결할 수도 없음  
    반복되는 컨텍스트가 두 번 이상 나오면 Skill 파일을 만들게 해야 할지, 아니면 문서를 모아 한 폴더로 관리해야 할지 고민 중임
  - 나도 비슷한 경험을 함. 작업 중 생긴 산출물은 대부분 버려짐  
    **오버 설정(over-configuration)** 은 품질 저하와 루프 문제를 일으킴  
    모델이 점점 좋아지기 때문에 예전엔 필요했던 지시문이 오히려 **성능을 방해**하기도 함  
    Anthropic 팀이 30일마다 claude.md를 초기화한다는 얘기도 들었음
  - 반대로, 나는 현지 회계 API를 통합해야 하는 프로젝트를 진행 중인데, 이건 완전히 커스텀 API라 LLM이 모름  
    그래서 Claude에게 **MCP 서버**를 만들게 했고, 이제 회계 작업을 자동으로 처리함  
    월말 마감 후 Claude에게 주요 작업을 추출해 Skill로 만들게 했더니, 마치 **주니어 회계사**가 생긴 것처럼 일함  
    커스텀 MCP와 Skill은 정말 유용하다고 느낌

- 많은 사람들이 에이전틱 코딩을 시작하기 전에 거대한 설정 벽을 만든다고 느껴짐  
  하지만 처음엔 **빈 .claude와 AGENTS.md** 로 시작해 직접 조작법을 배우는 게 맞음
  - 나는 아예 **직접 만든 스킬만 사용**해야 한다고 생각함  
    남이 만든 스킬을 마구 설치하면 **비결정성(nondeterminism)** 이 커지고 컨텍스트 윈도우도 낭비됨  
    예외적으로 playwright-cli 정도만 외부 설치를 추천함
  - 대규모 팀에서는 일정한 **가드레일(rule)** 이 필요함  
    예를 들어, [이 규칙](https://github.com/carlosonunez/bash-dotfiles/blob/main/ai/c...)처럼 사전 조건을 확인하도록 설정하면 안정적임  
    보안팀도 이런 접근을 선호할 것 같음  
    나도 규칙을 정의하면서 Claude가 GPG 서명 없이 커밋하지 않게 만들었음  
    다만 이런 규칙은 고정된 게 아니라 계속 진화해야 함
  - 이 글은 거대한 설정을 강요하는 게 아님  
    오히려 **작게 시작하고 짧게 유지**하라고 반복해서 강조함  
    초보자라도 AGENTS.md에 몇 줄만 추가하면 AI가 사용자의 의도를 더 잘 이해함  
    단순한 설정이 **AI 오작동**을 크게 줄여줌
  - 혼자서 코드를 다루는 것과 팀 단위로 **공유 프로젝트**를 다루는 건 완전히 다름  
    각 개발자가 에이전틱 도구를 쓰면 협업 방식 자체가 달라짐
  - 우선 **plan 모드**만 써도 90%는 해결됨  
    이런 복잡한 설정 논의는 모델이 발전하면서 1년 내에 대부분 사라질 것 같음

- `~/.claude/projects` 폴더가 진짜 재미있는 부분임  

- 나는 불필요한 설정이 적을수록 결과가 좋았음  
  사람들은 문서를 과하게 규정하지만, AI는 **유능하지만 긴장한 어른** 같음  
  너무 많은 지시를 주면 오히려 멍청해짐

- 이 글은 실제 경험보다는 생성된 느낌이 있음  
  **Claude.md는 짧게**, 링크 몇 개만 넣는 게 좋음  
  컨텍스트가 쌓이면 성능이 나빠지므로 **계획과 구현을 분리**하고 매번 초기화해야 함
  - 서두가 Claude의 문체와 너무 비슷해서 나도 그냥 Claude에게 직접 물어보면 될 것 같았음
  - 스킬과 커맨드의 차이가 헷갈림  
    스킬은 항상 컨텍스트에 있고, 커맨드는 수동 호출만 되는 건지 명확하지 않음

- 모든 모델 제공자가 표준 파일 세트를 공유했으면 좋겠음  
  그러면 Claude, Codex, Cursor, Opencode 간 전환이 쉬워질 텐데
  - 하지만 모델과 **하네스(harness)** 의 조합이 결과에 큰 영향을 줌  
    같은 프롬프트라도 모델마다 반응이 달라서, **프롬프트 튜닝**은 모델별로 달라야 함
  - 하나의 agents.md를 만들어 Claude.md가 참조하게 하고, 폴더 간 **심링크(sync)** 로 연결하면 됨  
    완벽하진 않지만 꽤 잘 작동함
  - 지금은 **초기 브라우저 시대**와 같음. 표준화되지 않은 덕분에 AJAX 같은 혁신이 나왔음  
    그래서 지금의 다양성은 오히려 긍정적임
  - 나는 임시로 **dotagents by Sentry** 를 써서 이 문제를 해결하고 있음
  - 모델 제공자들이 굳이 전환을 쉽게 만들 이유가 없다고 생각함

- **Claude Fast**의 [대체 문서](https://claudefa.st/blog/guide/mechanics/claude-md-mastery)가 매우 유용함  
  나는 .claude 폴더 정의를 싫어할 이유를 모르겠음  
  메인 에이전트가 파일을 직접 작성하게 하고, 반복적으로 업데이트하며 **자기 개선형 시스템**을 만들 수 있음  
  지금은 .claude가 스스로 복제하고 평가하며 업데이트함 — 나는 코드를 짜는 게 아니라 **.claude를 코딩**하는 셈임  
  - 요약하자면, CLAUDE.md는 단순한 문서가 아니라 **Claude의 운영체제**임  
    행동을 정의하고, 지식을 스킬로 위임하며, 시간이 지날수록 스스로 개선되는 시스템을 만드는 것임

- 사람들이 잘 모르는 벽은, Claude에게 파일을 수정하게 해도 **다시 읽도록 명시하지 않으면** 반영되지 않는다는 점임  
  예를 들어 CLAUDE.md를 새로 썼다면 Claude가 그걸 새 지시로 인식하게 **재로드**해야 함

- `~/.claude/plans` 폴더에는 **plan 모드 실행 시 생성된 계획 파일**이 저장됨  
  나는 이 디렉터리를 열어 백업하거나 참고용으로 자주 씀

- 나는 전역 MCP 서버와 **복합 에이전트(composite agent)** 를 중심으로 구성함  
  각 MCP 서버가 도구 세트를 정의하고, 에이전트는 그 안에서 **자율적으로 작업**함  
  .agent.md는 단순히 사용 가능한 도구를 설명하는 문서일 뿐, 복잡한 설정은 불필요함  
  스킬이나 재사용 프롬프트는 가치가 낮다고 느낌  
  모델은 이미 충분히 똑똑하므로, 필요한 건 **방향 제시(orientation)** 임