Most people treat CLAUDE.md like a prompt file.

That’s the mistake.

If you want Claude Code to feel like a senior engineer living inside your repo — not a chatbot that happens to have file access — your project needs structure. Claude needs four things at all times: the why (what the system does), the map (where things live), the rules (what’s allowed), and the workflows (how work gets done).

Here are the five layers that make it work.

1. CLAUDE.md — Repo Memory (Keep It Short)

This is the north star file. It’s the first thing Claude reads when it enters your project, and it sets the tone for everything that follows.

But here’s where most teams go wrong: they turn CLAUDE.md into a knowledge dump. Architecture docs, coding standards, API references, deployment procedures — all crammed into one file.

The result? The model starts missing important context because there’s too much noise.

Keep CLAUDE.md focused on three things:

  • Purpose — Why does this system exist?
  • Repo map — What lives where?
  • Rules and commands — What’s allowed, what’s not, and how does work get done?

That’s it. Everything else belongs in one of the layers below.

2. Skills — Reusable Expert Modes

Stop rewriting instructions every session.

Claude Code skills (.claude/skills/ or ~/.agents/skills/) let you package common workflows into reusable modules that Claude loads on demand. Think of them as expert modes:

  • Code review checklist
  • Refactor playbook
  • Release procedure
  • Debugging flow

The result is consistency across sessions and teammates. When your skills are well-structured, Claude doesn’t just generate code — it follows your team’s actual processes.

If you’re using OpenClaw or similar agent frameworks, skills become even more powerful. They can bundle scripts, reference docs, and assets into portable packages that any agent can pick up.

For more on how skill creation tools are evolving, see our recent post on Anthropic’s skill creator and Google’s Workspace CLI.

3. Hooks — Guardrails That Don’t Forget

Models forget. Hooks don’t.

Claude Code hooks are deterministic actions that fire automatically — before or after Claude performs certain operations. Use them for the things that must happen every time:

  • Run the formatter after file edits
  • Run tests when core modules change
  • Block unsafe directories (auth, billing, migrations)

The distinction matters: prompts are suggestions. Hooks are guarantees. When you tell Claude “always run tests after editing src/auth/” in a prompt, it might forget by the third edit. When you wire it as a hook, it’s automatic.

4. Docs — Progressive Context

Don’t bloat your prompts with everything Claude might need. Instead, give Claude a map to where truth lives:

  • Architecture overview — System design, data flow, infrastructure
  • ADRs (Architecture Decision Records) — Why you made the choices you did
  • Operational runbooks — How to deploy, debug, and recover

Claude is good at reading files on demand. It doesn’t need every detail upfront — it needs to know where to look. A well-organized docs/ directory means Claude can pull context exactly when it’s relevant.

5. Local CLAUDE.md for Risky Modules

This is the layer most teams miss entirely.

Put small, focused CLAUDE.md files near the sharp edges of your codebase:

src/auth/CLAUDE.md
src/persistence/CLAUDE.md
infra/CLAUDE.md

These files contain module-specific gotchas, constraints, and warnings. When Claude works in src/auth/, it automatically sees the authentication-specific guidance — the token rotation quirks, the session handling edge cases, the “never modify this function without updating the migration” warnings.

This is how you get surgical precision without bloating the root CLAUDE.md.

Structure Over Prompting

Prompting is temporary. Structure is permanent.

When your repo is organized this way, Claude stops behaving like a chatbot and starts acting like a project-native engineer. It knows the context, follows the processes, respects the guardrails, and finds the right documentation — because the project itself teaches it how to work.

The AI coding CLI landscape is moving fast. Claude Code, Codex CLI, Gemini CLI — they’re all shipping agent capabilities. But the teams that get real value aren’t the ones with the best prompts. They’re the ones with the best-structured repos.

Kevin Kaminski is a Microsoft MVP and Principal at Big Hat Group, where he helps enterprise teams deploy AI agents, Windows 365, and modern management solutions. For help structuring your AI coding workflows, get in touch.