▲

.claude/ 폴더 구조 분석

 (blog.dailydoseofds.com)
10P by GN⁺ 5시간전 | ★ favorite | 댓글 1개
  • .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 명령을 생성하며, 스킬은 추가 기능(보조 파일, 자동 트리거 등)을 지원
▲
GN⁺ 5시간전  [-]
Hacker News 의견들

  • 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) 이 필요함
      예를 들어, 이 규칙처럼 사전 조건을 확인하도록 설정하면 안정적임
      보안팀도 이런 접근을 선호할 것 같음
      나도 규칙을 정의하면서 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의 대체 문서가 매우 유용함
    나는 .claude 폴더 정의를 싫어할 이유를 모르겠음
    메인 에이전트가 파일을 직접 작성하게 하고, 반복적으로 업데이트하며 자기 개선형 시스템을 만들 수 있음
    지금은 .claude가 스스로 복제하고 평가하며 업데이트함 — 나는 코드를 짜는 게 아니라 .claude를 코딩하는 셈임

    • 요약하자면, CLAUDE.md는 단순한 문서가 아니라 Claude의 운영체제임
      행동을 정의하고, 지식을 스킬로 위임하며, 시간이 지날수록 스스로 개선되는 시스템을 만드는 것임

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

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

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

답변달기