Skip to content

Blog

A good CLAUDE.md describes how to think, not the project

The default CLAUDE.md lists the stack and the commands, and it shapes nothing. The useful ones set philosophy, rules, protocols and principles for how the agent works.

Written by

Context engineering

Published: 3 February 2026 Updated: 1 min read

Everyone has a CLAUDE.md now. Almost nobody has a good one.

The default template from /init gives you project description, tech stack, basic commands. Generic, bland, useless.

Your CLAUDE.md is your agent’s operating system. Generic templates give you generic results.

What the default gives you

  • “This is a TypeScript project”
  • “Run npm install to get started”
  • “Use npm test to run tests”
  • “Follow best practices”

This is context engineering theater. It does not shape how Claude thinks. It just takes up tokens.

What should actually be in there

  • Philosophy. How should Claude approach problems? “Take a deep breath. We’re not here to write code. We’re here to make a dent in the universe.” Set the mindset, not just the commands.
  • Truthfulness rules. “No fallbacks. No mocks. No theater. If you can’t do it, say so.” This kills hallucinations at the source.
  • Execution protocols. “Follow strict TDD. Red-Green-Refactor. Write the failing test first. Always.” Not suggestions. Rules.
  • Anti-hallucination. “Say ‘I don’t know’ if you don’t know. Answer only if confident. Think before responding.”
  • Code principles. “Simple over clever. Readability first. Small functions. Single responsibility.”
  • Context priming. “Prepare to discuss”, not “Prepare to work on X.” Make Claude spend tokens understanding before acting.

A constitution, not documentation

The best CLAUDE.md files I have seen do not describe the project. They describe how to think about the project. They read as a constitution, in this order: philosophy, then rules, then protocols, then principles.

When you frame coding as craftsmanship, you get craftsmanship back. When you frame it as “follow best practices”, you get autocomplete.

Is your CLAUDE.md a description, or a constitution?

Further reading

  1. Research, plan, implement keeps coding agents out of the dumb zone A coding agent gets worse the longer a session runs. Research, plan and implement in separate, compacted steps, use sub-agents to control context, and put human effort where mistakes cost the most. 2 min readShort post
  2. Most agent failures are context problems, not prompt problems Prompt engineering is how you ask. Context engineering is what the model sees. Eight practices, the symptoms of a badly built context and a four-question audit for the window. 2 min readShort post
  3. Agents fail from amnesia: context as a living playbook Agent failures are context failures. The ACE framework treats context as a playbook that grows through small updates instead of rewrites, and small open models gain the most from it. 2 min readShort post

All 16 posts on Context engineering

ClientsCase study: A large DIY retailer in Germany

Scaling needs named owners

Coding agents scale across teams when named people own the platform, the team practice, the guardrails, and the measurement. Rollout & scale is where that ownership is built and handed to internal owners, in your stack.

Training on this topic: Agentic Engineering for Developers and QA
See Rollout & scale

Want to check one team first? The self-check: twelve yes or no questions, three minutes, instant result, no account. Take the self-check