Your Configuration Blueprint

The decision framework

You now understand all six layers. The remaining question is: for any given piece of configuration, which layer does it belong in? Here is the decision flow you should follow every time.

Step 1: Is this knowledge Claude needs in every session?

Yes → Put it in CLAUDE.md. Build commands, project architecture, universal coding standards. Keep it under 200 lines. If it is growing beyond that, split into @imports or .claude/rules/.

Step 2: Is this knowledge that applies to a specific area of the codebase?

Yes → Put it in .claude/rules/ with a paths field. React component conventions for src/components/**, API patterns for src/api/**, database rules for migrations/**. These load only when Claude touches matching files.

Step 3: Is this a workflow or task-specific procedure?

Yes → Make it a skill in .claude/skills/. PR review checklist, deployment procedure, changelog generation, code migration steps. Skills load on-demand and can be invoked manually with /skill-name.

Step 4: Does this task require isolated execution?

Yes → Make it an agent in .claude/agents/. Heavy exploration, restricted-access review, parallel work, test generation. Agents run in their own context and optionally in their own worktree.

Step 5: Does the agent need domain knowledge before starting?

Yes → Wire skills into the agent using the skills field. Review standards, testing conventions, architecture maps. The agent starts with full knowledge instead of inferring from code.

Step 6: Does this rule need deterministic enforcement?

Yes → Add a hook in .claude/settings.json. Auto-linting, blocking dangerous commands, protected files, audit logging. Hooks fire automatically and can block actions — they do not depend on Claude's choice.

The one-line rules:

Always-on knowledge → CLAUDE.md
Scoped knowledge → Rules with paths
Task recipes → Skills
Isolated workers → Agents
Informed workers → Agents with skills
Guaranteed behaviour → Hooks

Your team's API error handling conventions are 25 lines long and only relevant when working in src/api/. Where should they live?

A configuration blueprint you can copy

Here is the complete file structure for a well-configured Claude Code project. Adapt it to your needs, but this structure covers the common patterns.

your-project/
├── CLAUDE.md                              # Lean foundation (under 100 lines)
├── .claude/
│   ├── settings.json                      # Hooks and permissions
│   ├── .mcp.json                          # MCP server configs (if needed)
│   ├── rules/
│   │   ├── react-components.md            # paths: src/components/**
│   │   ├── api-design.md                  # paths: src/api/**
│   │   ├── database.md                    # paths: src/db/**
│   │   └── testing.md                     # paths: **/*.test.*
│   ├── skills/
│   │   ├── review-pr/SKILL.md             # /review-pr command
│   │   ├── changelog/SKILL.md             # /changelog command
│   │   ├── security-check/SKILL.md        # /security-check command
│   │   ├── code-review-standards/SKILL.md # Preloaded into reviewer agent
│   │   ├── testing-conventions/SKILL.md   # Preloaded into test-writer agent
│   │   └── project-architecture/SKILL.md  # Preloaded into navigator agent
│   └── agents/
│       ├── reviewer/AGENT.md              # Read-only code reviewer
│       ├── navigator/AGENT.md             # Codebase exploration
│       ├── test-writer/AGENT.md           # Isolated test generation
│       └── debugger/AGENT.md              # Bug investigation
└── src/
    ├── components/                        # React component rules auto-load here
    ├── api/                               # API design rules auto-load here
    └── db/                                # Database rules auto-load here

The CLAUDE.md — lean and focused:

# My Project

A Next.js application with a Convex backend.

## Build Commands
- pnpm install — install dependencies
- pnpm dev — start dev server at localhost:3000
- pnpm build — production build
- pnpm test — run test suite
- pnpm lint — run linter

## Architecture
- Next.js 16 with App Router
- Convex for backend (schema, mutations, queries in convex/)
- TypeScript throughout
- Tailwind CSS for styling

## Universal Standards
- 2-space indentation
- Named exports (no default exports)
- camelCase for functions and variables
- PascalCase for components and types
- Explicit TypeScript types on all exports

Under 30 lines. Everything Claude needs to be oriented in every session. Everything else lives in the right layer.

The settings.json — hooks for enforcement:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$FILE\" 2>/dev/null || true"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit",
        "if": "Edit(.env*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Cannot edit .env files via Claude Code' >&2; exit 2"
          }
        ]
      }
    ]
  }
}

Two hooks: auto-format after every edit, and block edits to .env files. Deterministic, no exceptions.

Your first skill, agent, and hook

You do not need to build the entire blueprint at once. Start with three files and expand from there.

File 1: Your first skill — a PR review checklist.

Create .claude/skills/review-pr/SKILL.md:

---
name: review-pr
description: Reviews current branch changes against coding standards
user-invocable: true
allowed-tools: Read Grep Glob Bash
---

# PR Review

## Changed files
!`git diff --name-only main...HEAD`

## Diff
!`git diff main...HEAD`

Review these changes for:
1. Naming convention compliance
2. Missing error handling
3. Missing or inadequate tests
4. Security issues (hardcoded secrets, injection vectors)
5. Performance concerns (N+1 queries, unnecessary re-renders)

Format findings as Critical / Warning / Suggestion with file:line references.

Try it: make some changes on a branch and type /review-pr.

File 2: Your first agent — a codebase explorer.

Create .claude/agents/explorer/AGENT.md:

---
name: explorer
description: Explores and summarises unfamiliar areas of the codebase
tools: Read Grep Glob
permission-mode: dontAsk
---

# Codebase Explorer

Map the requested area of the codebase. Return:
1. Key files and their roles
2. Data flow from input to output
3. Patterns and conventions used
4. Dependencies (internal and external)
5. Anything surprising or non-obvious

Try it: ask Claude to "explore the authentication system" or any area you are unfamiliar with. Watch it delegate to the explorer agent and return a clean summary.

File 3: Your first hook — auto-format after edits.

Add to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$FILE\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

From now on, every file Claude edits is automatically formatted. You never need to ask Claude to format, and Claude never needs to remember.

That is it. Three files. One recipe, one chef, one guardrail. Use them for a week. When you feel comfortable, add more skills, build more agents, wire skills into agents, and add more hooks. The system grows incrementally.

Scaling to a team

Everything in .claude/ is version-controlled. When you push your configuration to the repository, every developer on your team gets the same skills, agents, hooks, and rules. This is the mechanism for consistent Claude Code behaviour across a team.

Phase 1: Foundation (week 1)

Clean up CLAUDE.md to under 100 lines
Add 2-3 path-specific rules for your most common code areas
Create one skill (PR review) and one agent (explorer)
Add auto-format hook

Phase 2: Coverage (weeks 2-3)

Add skills for common workflows (deploy, changelog, security check)
Build a reviewer agent preloaded with code review standards
Add hooks for protected files and dangerous command blocking
Create a testing-conventions skill

Phase 3: Composition (weeks 3-4)

Wire skills into agents (reviewer + review standards, test writer + testing conventions)
Build a navigator agent preloaded with architecture skill
Set up the test writer agent with worktree isolation
Document the configuration in a team README

Phase 4: Optimisation (ongoing)

Review agent output for consistency — tune skills when output drifts
Add hooks for new enforcement needs as they arise
Remove skills and rules that are not being used
Update architecture and convention skills as the project evolves

The feedback loop: When a team member notices Claude not following a convention, the fix is not "tell Claude in the next session." The fix is to update the right configuration file — a rule, a skill, an agent prompt, or a hook. That fix persists across every developer's session, forever.

A teammate says 'Claude keeps using our old API pattern instead of the new one.' What is the right response?

✎

Module 8 — Final Assessment

Your CLAUDE.md is 350 lines containing build commands, architecture overview, React conventions, API patterns, testing standards, and a deployment procedure. How should you restructure it?

You have a skill called coding-standards and three agents (reviewer, test-writer, api-builder) that all need to follow those standards. What is the correct configuration?

A developer on your team says: 'I added a PostToolUse hook to run tests after every file edit, but it is slowing down my workflow because tests run even for small edits to documentation files.' What should they do?

You want Claude to NEVER commit code that fails linting. Which approach provides the strongest guarantee?