The Config Ecosystem — Three Layers Explained

Every time you open Claude Code in a project, it reads a set of files before you type a single message. These files are not a one-time setup chore — they are a living system that gets richer as you build. Understanding what each layer does is the difference between using Claude as a generic code assistant and using it as a developer who knows your standards, your project, and your patterns by heart.

The Three-Layer System

Here is the complete picture of what Claude reads at the start of every session:

Your Computer
│
├── C:\Users\[you]\.claude\               ← Your personal developer home
│   │
│   ├── CLAUDE.md                         ← LAYER 1: Your Developer Profile
│   │   Your universal rules, your         Applies to EVERY project you open
│   │   tech stack, your habits
│   │
│   └── skills\
│       ├── new-feature.md                ← LAYER 3: Expert Instruction Sets
│       ├── bug-fix.md                     Loaded when a task matches
│       ├── supabase-migration.md
│       └── pre-launch-audit.md
│
└── S:\My Projects\MyApp\                 ← Your project folder
    │
    └── CLAUDE.md                         ← LAYER 2: This Project's Rulebook
        Stack, tables, routes,             Applies only to this project
        conventions for this app           Overrides global where they conflict

What Claude loads and when:

When all three are in place, Claude starts every session already knowing: who you are and how you like to work, exactly what this project is (stack, database, routes), and the proven expert approach for whatever type of task you're about to do.

Layer 1: The Global CLAUDE.md — Your Developer Profile

File location: ~/.claude/CLAUDE.md On Windows: C:\Users\[your name]\.claude\CLAUDE.md

What it is: A permanent document describing you as a developer. It lives outside any specific project — in the .claude folder in your home directory. Every Claude Code session you ever open, on any project, on this machine, reads this file first.

The analogy: Your firm's standard operating procedure document. When a new team member joins your CA firm, you hand them the SOP: how the firm operates, what tools you use, what the quality standards are, what you never do. This is that SOP — but for Claude, and it covers how you build software.

What belongs in the global profile:

What does NOT go here:

• Anything specific to one project (that goes in the project CLAUDE.md)
• API keys, passwords, or secrets (those go in .env files, never in markdown files)
• Large code patterns (those go in skill files)

Layer 2: The Project CLAUDE.md — This Project's Rulebook

File location: At the root of your project folder (e.g., S:\My Projects\MyApp\CLAUDE.md)

What it is: A permanent document describing everything about this specific project. It is committed to git alongside your code, so anyone who opens the project (including Claude on a different machine) reads the same context.

What it is NOT: A README. A README explains what the project does to people who find it on GitHub. A project CLAUDE.md explains how to work on it to Claude.

The analogy: The engagement file for a specific audit client. Your global SOP (Layer 1) tells you how your firm operates. The engagement file tells you about THIS client — their chart of accounts, their specific requirements, what needs special attention, what you found last time. The project CLAUDE.md is that engagement file.

What belongs in the project CLAUDE.md:

A real example — the Aurora Public School project CLAUDE.md:

Aurora Public School is the live job placement platform used throughout this training. Its project CLAUDE.md is 511 lines. Here are the key sections and what they contain:

That 511-line investment saves hours every session. Claude already knows where everything is, who can access what, and what the architectural decisions were — without you explaining a single thing.

Layer 3: Skill Files — Expert Instruction Sets

File location: ~/.claude/skills/ (global — shared across all your projects) On Windows: C:\Users\[your name]\.claude\skills\

What they are: Markdown files that contain step-by-step expert instructions for a specific type of task. When you describe a task, Claude checks the skill routing table in your CLAUDE.md, loads the matching skill file, and follows its sequence for the entire task.

The analogy: The specialized procedure section of your firm's SOP. The main SOP (global CLAUDE.md) tells you how the firm operates. The "Income Tax Audit Procedure" or "GST Reconciliation Checklist" tells you the expert step-by-step sequence for that specific type of engagement. Skill files are those specialized procedures — except for software tasks.

Why skill files matter:

Without a skill file, Claude defaults to a generic approach for every task type. With a skill file:

• The investigation sequence is predefined and battle-tested
• The quality checklist runs automatically before Claude says "done"
• Anti-patterns are documented — Claude avoids known mistakes
• Every task of that type is handled consistently, regardless of session

The five production skill files from Aurora Public School:

These are production skill files from a live platform. Each one was developed through real-world use.

new-feature.md — Building Something New

Triggered by: "build," "add," "create," "implement," "new page," "new form"

What it makes Claude do:

1. Extract requirements as a numbered list and confirm before coding
2. Check existing database structure before proposing schema changes
3. Build the database migration first (if needed), then the data hook, then the UI
4. Create React Query hooks for all data fetching — never call Supabase directly in a component
5. Add Zod validation for all user inputs before building the form
6. Handle three states in every data-showing component: loading (skeleton), error (friendly message), empty (helpful prompt)
7. Run a quality checklist before saying done: types correct, RLS exists, all three states handled, responsive

Anti-patterns it prevents: Direct Supabase calls in components, any types, hard-deletes, service role key in frontend

bug-fix.md — Investigating and Fixing Problems

Triggered by: "fix," "bug," "broken," "error," "not working," "crash," "wrong"

What it makes Claude do:

1. Define expected vs actual behavior before touching any code
2. Follow a systematic investigation sequence: read the component → check the data hook → check the database/RLS → check recent git changes → check browser console errors
3. Identify root cause, not just symptom
4. Fix the root cause — not a workaround
5. Verify in the actual browser with real data
6. Check if the same bug could exist elsewhere

Anti-patterns it prevents: Adding as any to silence TypeScript errors, empty catch blocks, fixing the symptom while leaving the root cause

supabase-migration.md — Database Changes

Triggered by: "database," "table," "schema," "migration," "RLS," "column," "foreign key"

What it makes Claude do:

1. Answer the data design questions first (what is stored, who reads it, who writes it, how it connects)
2. Write the SQL migration file in supabase/migrations/ with a timestamp prefix
3. Include in every migration: CREATE TABLE, RLS enabled, policies for each user role, is_deleted soft-delete column
4. Apply the migration via CLI without asking you to run it manually
5. Regenerate TypeScript types after the migration
6. Update any hooks querying the affected tables

Anti-patterns it prevents: RLS disabled tables, hard-deletes, storing money as floats, storing passwords in your own tables

pre-launch-audit.md — Checking Before Going Live

Triggered by: "before release," "audit," "pre-launch," "check everything," "ready to go live"

What it makes Claude do:

1. Security check: grep for service role key in frontend, hardcoded API keys, .env missing from .gitignore, TypeScript any
2. Database check: verify RLS enabled on every user-data table, at least one policy per operation
3. Code quality check: console.log in production code, empty catch blocks, build passes cleanly
4. UI check: pages load without errors, login works, core flows work end-to-end, error messages are user-friendly, works on mobile
5. Classify every finding as Critical / Important / Nice to have
6. Report findings in a structured format before recommending launch

Anti-patterns it prevents: Shipping with security holes, disabled RLS, console.log spam, broken core flows

How the Three Layers Interact

Precedence (what wins when rules conflict):

Skill file
  ↑ Most specific — applies to this task type
Project CLAUDE.md
  ↑ Project-level — overrides global defaults
Global CLAUDE.md
  ↑ Universal — applies everywhere

Example: Your global CLAUDE.md says "max 400 lines per file." Your project CLAUDE.md says "max 500 lines for this project." For this project, Claude uses 500 — the project rule wins.

Example: Your global CLAUDE.md says "use React Query for all data fetching." The bug-fix skill says "when investigating data bugs, first check the React Query cache key and invalidation logic." Both apply — React Query (from global) + the investigation sequence (from skill).

The loading sequence in a typical session:

Quick Reference: What Goes Where