.claude/ Folder: Claude Code's Secret Control Panel 🚀🔥

claude-folderlink-note

Yo, my guy, let's crack open this .claude/ black box. Most peeps ignore it, but that's like driving blindfolded. Time to level up.

1️⃣ WHY Does This Even Exist? (The Pain It Kills 💀)

Before .claude/? Claude Code was generic AF. It guessed your project's rules, commands, and style—leading to endless "/no, do it THIS way" corrections. Teams fought over prefs, sessions forgot context, and risky commands ran wild.

The "Ohhh" Unlock: .claude/ is your project brain. Injects custom instructions, commands, skills, and safety rails automatically. Claude behaves like a team member from session 1. No more babysitting. Productivity 10x.

PROBLEM (BLACK BOX) ❌          SOLUTION (.CLAUDE/) ✅
════════════════════════        ════════════════════
Generic Claude everywhere       Custom per project/team
Forgets rules each session      Persistent memory + rules
Risky ops (rm -rf? 😱)          Permissions lock it down
Team chaos on styles            Shared config in git

2️⃣ BIG PICTURE: Two Folders, Not One 🤯

  • Project-level ./.claude/: Team-shared, git-committed. Lives in your repo root.
  • Global ~/.claude/: Your personal vibes, session history, cross-project stuff.

Claude loads both, project first (overrides global). Subdirs too for scoped rules.

YOUR PROJECT ROOT
│
├── CLAUDE.md (team bible 📖)
└── .claude/          ← CONTROL CENTER
    ├── rules/        • Modular rules
    ├── commands/     • /slash magic
    ├── skills/       • Auto-triggers
    ├── agents/       • Sub-experts
    └── settings.json • Permissions
│
└── ~/.claude/        ← YOUR GLOBAL VAULT
    ├── CLAUDE.md
    ├── commands/
    └── projects/     • Session memory

LOCK IT IN: Project = team rules. Global = you rules. Stack 'em.

3️⃣ MECHANICS: File-by-File Breakdown ⚙️

Loaded on session start, injected into Claude's prompt. Keep files lean (<200 lines) or context chokes.

CLAUDE.md: The System Prompt Boss 👑

Why? No manual reminders. Claude reads it first, follows forever.

How?

  1. Write essentials: commands, arch, conventions, gotchas.
  2. Lives in project root (or subdirs/global).
  3. Loaded + combined automatically.

Don't Bloat: No linter config or long theory—link that shit.

EXAMPLE CLAUDE.md (20 lines gold 🔥)
# Commands
npm run dev # etc.

# Arch
- Express + Prisma

# Conventions
- Zod validation always

Personal Twist: CLAUDE.local.md (gitignored) for your quirks.

TL;DR: CLAUDE.md = "Claude, act like this." Edit once, win daily.

rules/: Split the Monolith 📂

Why? Giant CLAUDE.md → ignored mess. Modular = team owns pieces.

How?

  • MD files in .claude/rules/ auto-load.
  • YAML frontmatter for path-scoping (e.g., only API files).
.claude/rules/
├── code-style.md      (always loads)
└── api-conventions.md
  ---
  paths: ["src/api/**"]
  ---
  - Zod reqs

TL;DR: Rules scale teams. Scope = smart.

commands/: Custom /slashes 🛠️

Why? Built-ins suck for your workflows. Inject git diffs, args, shell output.

How?

  1. MD in .claude/commands/ → /project:filename.
  2. Use !git diff`` for real output.
  3. $ARGUMENTS for user input.
EX: commands/review.md → /project:review
!`git diff main...HEAD`
Review for bugs/tests...

Global: ~/.claude/commands/ → /user:cmd.

TL;DR: Commands = saved prompts on steroids.

skills/: Auto-Pilot Workflows 🤖

Why? Commands wait—you type. Skills watch convo, trigger solo.

How?

  • Subdir w/ SKILL.md (YAML: desc, tools).
  • Bundles files (@DETAILED_GUIDE.md).
  • Matches desc? Boom, invokes.
.claude/skills/security-review/
└── SKILL.md
---
description: Use on security mentions
---
1. Scan SQLi/XSS...

Call explicit: /security-review.

TL;DR: Skills = proactive Claude.

agents/: Spawn Experts 🧑‍💻

Why? Main Claude multitasks poorly on deep dives. Agents = isolated pros.

How?

  • MD in .claude/agents/ w/ YAML (name, model=sonnet, tools=Read).
  • Claude spawns, compresses results back.
agents/code-reviewer.md
---
name: code-reviewer
model: sonnet
tools: Read,Grep
---
Flag bugs + fixes.

TL;DR: Agents = delegate hard tasks.

settings.json: Permission Jail ⛓️

Why? Blind trust = disasters (curl secrets? No.)

How?

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Read", "Write"],
    "deny": ["Bash(rm *)", "Read(.env)"]
  }
}
  • Allow: No-ask zone.
  • Deny: Blocked.
  • Else: Asks.

settings.local.json for personal.

TL;DR: Permissions = safety net.

4️⃣ GET STARTING: 5-Step Ramp-Up 🚀

  1. /init → Auto CLAUDE.md.
  2. settings.json w/ basics.
  3. 1-2 commands (review/fix).
  4. Split to rules/.
  5. Global CLAUDE.md prefs.

BURN THIS IN: CLAUDE.md first. Rest optimizes. Treat like infra—small setup, big ROI.

You tracking, fam? This flips Claude from helper to teammate. Hit me for examples. 😎

← All notes