.claudeフォルダの完全解剖ガイド

Anatomy of the .claude/ folder A complete guide to CLAUDE.md, custom commands, skills, agents, and permissions, and how to set them up properly. Most Claude Code users treat the .claude folder like a black box. Two .claude Directories The system includes two distinct locations: 1. Project-level (.claude/ in your project root) - Team configuration committed to git 2. Global (~/.claude/ in home directory) - Personal preferences and session history CLAUDE.md: The Core File The most critical file in the system, CLAUDE.md loads directly into Claude's system prompt at session start. It should contain: - Build, test, and lint commands - Key architectural decisions - Non-obvious gotchas - Import conventions and naming patterns - File and folder structure Should NOT contain: - Full documentation links - Long theoretical explanations Recommendation: Keep CLAUDE.md under 200 lines to maintain instruction adherence. CLAUDE.local.md Create CLAUDE.local.md in your project root. Claude reads it alongside the main CLAUDE.md, and it's automatically gitignored so your personal tweaks never land in the repo. Rules Folder Organization The .claude/rules/ folder breaks instructions into focused, modular files: - code-style.md - testing.md - api-conventions.md - security.md Path-scoped rules use YAML frontmatter to activate only for matching files: --- paths: - "src/api/**/*.ts" --- Custom Commands Every markdown file in .claude/commands/ becomes a slash command. A file named review.md creates /project:review. Key feature: The ! backtick syntax executes shell commands and embeds output into prompts, making commands genuinely functional rather than template-based. Skills vs. Commands Critical distinction: - Commands wait for explicit user invocation - Skills watch conversations and trigger automatically when task descriptions match Skills are packaged in subdirectories with supporting files, while commands are single files. Agents for Specialized Work Define subagent personas in .claude/agents/ for complex, recurring workflows. Each agent has: - Isolated context window - Restricted tool access - Optional model preference (Haiku for read-only tasks, Sonnet for complex work) Settings.json Permissions The settings.json file inside .claude/ controls what Claude is and isn't allowed to do. Structure includes: - $schema reference for VS Code validation - allow list (runs without confirmation) - deny list (blocked entirely) - Unspecified commands prompt for confirmation Recommended allow list: - Bash(npm run *) for script execution - Bash(git *) for version control - Read, Write, Edit, Glob, Grep for file operations Recommended deny list: - Destructive commands like rm -rf - Network commands like curl - Sensitive files like .env Global ~/.claude/ Directory Contains: - Personal CLAUDE.md (loads in all projects) - Session transcripts and auto-memory in projects/ - Personal commands, skills, and agents Implementation Progression 1. Run /init and refine generated CLAUDE.md 2. Create .claude/settings.json with appropriate permissions 3. Build 1-2 custom commands for frequent workflows 4. Split CLAUDE.md into modular rules as it grows 5. Add ~/.claude/CLAUDE.md for personal preferences CLAUDE.md is your highest-leverage file. Get that right first. Everything else is optimization.