Inside the .claude Folder

Every project I work on has a .claude/ folder at the root. Its source lives in git, like the rest of the code.

That folder turns Claude Code from a generic assistant into a project-aware teammate. Everyone who clones the repo inherits the same setup.

Agentic coding is only as good as the context you give the agent. The .claude/ folder is where that context lives.

The .claude folder, at a glance #

your-project/
├── .mcp.json               # shared MCP servers (root only)
└── .claude/
    ├── CLAUDE.md           # project onboarding
    ├── settings.json       # permissions, hooks, env
    ├── settings.local.json # personal overrides, gitignored
    ├── skills/             # procedures, loaded on demand
    ├── rules/              # conventions, optionally scoped
    ├── hooks/              # scripts for hooks
    └── agents/             # specialized roles

Six layers, one folder. Context, safety, procedures, guardrails, automation, specialists.

The foundation #

CLAUDE.md: where everything starts #

Claude Code reads CLAUDE.md on every boot. The onboarding doc.

In Phel, mine covers the compiler pipeline (Lexer → Parser → Analyzer → Emitter), module structure, conventions, and key commands.

A global ~/.claude/CLAUDE.md applies to all your projects. The project file says how this codebase works. The global file says how I work.

Every byte ships in every prompt. Keep it short. Past one screen, move detail into rules/ or skills/.

A good CLAUDE.md is a good onboarding doc. The better it is, the less you repeat yourself.

settings.json: safety before leverage #

Before giving the agent more power, lock down what it must never do.

.claude/settings.json holds three things: permissions (allow/deny), hooks (event commands), and env (variables). A gitignored settings.local.json keeps personal overrides separate.

{
  "permissions": {
    "allow": [
      "Bash(composer:*)",
      "Bash(./bin/phel:*)",
      "Bash(git:*)",
      "Bash(gh:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}

Allow unlocks flow. Deny stops the obvious mistakes, but it matches the command text, not what the command does. find . -delete walks past a rm deny rule. For a hard block, use a hook.

Deny rules catch the obvious. Hooks enforce the rest.

Procedures and guardrails #

Skills: procedures you can run #

Next pain after onboarding: repetition. Skills solve that.

A skill is a folder in .claude/skills/ with a SKILL.md inside: a short description plus the steps. Only the description sits in context. Claude loads the full skill when you call it with a slash, or on its own when the task matches the description.

A few from Phel:

• /gh-issue <number>: issue to branch, TDD plan, PR.
• /commit: fix, analysis, tests, conventional commit.
• /refactor-check: SOLID, naming, architecture smells.
• /release [version]: changelog, PHAR, tag, release.

Skills capture what to do. Rules capture what not to do.

Rules: the guardrails #

CLAUDE.md loads every session. Rules load only when they match. Files in .claude/rules/ target code areas with glob patterns, so the context stays lean.

Rules are not suggestions. A convention change and its rule ship in the same commit. No drift, no outdated wiki.

Automation and delegation #

Hooks: automation at the edges #

Rules tell the agent what to do. Hooks make sure it happens even if the agent forgets.

Hooks are shell commands triggered by Claude Code events (PreToolUse, PostToolUse, Stop), wired through settings.json. In Phel, PreToolUse blocks edits to critical files (build/release.sh, .github/*, composer.lock). PostToolUse auto-formats PHP via php-cs-fixer.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": ".claude/hooks/protect-files.sh" }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": ".claude/hooks/format-php.sh" }]
    }]
  }
}

Rules are what the agent should know. Hooks are what the system enforces anyway.

Agents: specialized roles #

Everything so far shapes one agent. Agents add specialists the main agent can delegate to, each with its own tools, permissions, and model. The most advanced piece, so add it last.

A few from Phel:

• Explorer (Sonnet, read-only): files, structure mapping.
• Clean Code Reviewer: SOLID and naming on diffs.
• TDD Coach: red-green-refactor enforcement.
• Domain Architect: module boundaries, compiler pipeline.
• Debugger: compiler errors across all phases.

Each agent runs in its own context window, so the main session stays clean while the specialist digs deep. The win is focus, not only cost. An agent with only read and grep cannot rewrite your codebase by mistake.

Right model for the right job. Fast and cheap for exploration. Deep and careful for architecture.

Start small, grow with friction #

Do not build all of this on day one.

The order, driven by real friction:

1. Start with CLAUDE.md.
2. Lock down settings.json permissions.
3. First time you repeat yourself, write a skill.
4. First time the agent breaks a convention, add a rule.
5. First time something bad almost gets committed, add a hook.
6. First time a generalist is wrong for the job, define a specialist.

Each step fixes a problem you actually had. Not one you imagined.

Empty folder? Let the agent start it. /init drafts a CLAUDE.md from your repo. Then ask: “Which conventions do I repeat in this codebase? Propose rules and skills for them.”

Already have one? Ask the agent to audit it: “Check .claude/ against the current Claude Code docs. What is stale, unused, or wrong?” Tools change fast, and your setup ages with them. That’s how this post got its last update.

Commit the folder. Share it. When someone joins, their session inherits everything.

One spec for teams with more than one AI tool #

If your team uses only Claude Code, you can stop here.

.claude/ has one limit: only Claude Code reads it. Codex reads AGENTS.md, Cursor reads .cursor/rules/. On a mixed team, the same rules get copied into each format, and the copies drift.

That’s why I built agnostic-ai. Write your rules, skills, agents, and hooks once. agnostic-ai sync turns them into the files each tool reads. You commit the spec, and the generated folders stay out of git. This site and Phel both run on it.

.claude/ teaches one tool your project. One spec teaches all of them.

Treat your agent setup like infrastructure. Version it. Review it. Evolve it with the codebase.