Give AI Docs, Not Scripts
Stop over-scripting Claude. Let your documentation do the work instead.
When I first started using Claude, my instinct was to control it tightly — write detailed prompts, define step-by-step instructions, build skills for every scenario.
It felt productive. It felt precise. It was the wrong instinct.
Step-by-step instructions go stale the moment your project changes. They also create a false sense of reliability — Claude follows your script, but the script itself might be wrong, incomplete, or irrelevant.
The better approach: write good documentation and trust the model to read it.
Instead of telling Claude "when adding a new page, do X then Y", I maintain docs that explain what the system is — the architecture, the design system, the schema. Claude reads the relevant doc and figures out the right steps itself. If the project changes, I update the doc once.
CLAUDE.md as a map, not a script
Claude Code reads a CLAUDE.md at the root of your project automatically. Here's mine:
No workflow scripts, no "when you do X, do Y first". Just what the project is and where the truth lives.
The critical rules section is the exception — constraints that aren't obvious from reading the code. Short, declarative, non-negotiable.
I also keep each concern in its own file: design system in one doc, schema in another, architecture in another. Claude loads what's relevant, not everything. Better signal-to-noise than one giant instruction file.
My job isn't to script Claude's behavior — it's to keep the documentation honest. Claude's job is to reason from it.
A few things I keep in mind:
Docs over instructions. Describe the system, not the workflow.
CLAUDE.md as orientation, not a script. Point to authoritative sources and let the model read them.
Skills for genuinely complex workflows only. Multi-step deploys, yes. "How to add a component", no.
Stale instructions are worse than no instructions. An outdated step-by-step actively misleads.
The underlying principle is the same one that makes good software: separation of concerns. Documentation describes reality. Behavior follows from it.