The decision framework for where every piece of configuration belongs, a starter project structure, and the path from first skill to full team adoption.
Numerical scenarios are illustrative unless a source is linked. Validate operational, legal, financial, and regulatory decisions against current primary guidance and your own baseline.
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
Where are you now?
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.
# My ProjectA 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.
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-prdescription: Reviews current branch changes against coding standardsuser-invocable: trueallowed-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 compliance2. Missing error handling3. Missing or inadequate tests4. 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: explorerdescription: Explores and summarises unfamiliar areas of the codebasetools: Read Grep Globpermission-mode: dontAsk---# Codebase ExplorerMap the requested area of the codebase. Return:1. Key files and their roles2. Data flow from input to output3. Patterns and conventions used4. 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.
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.
Where are you now?
A teammate says 'Claude keeps using our old API pattern instead of the new one.' What is the right response?
4 questions
Module 8 — Final Assessment
01Your 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?
02You 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?
03A 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?
04You want Claude to NEVER commit code that fails linting. Which approach provides the strongest guarantee?
