When working with AI, especially on larger projects, a few well-written steering documents can go a long way. These can certainly go too far though, becoming bloated and adding far more context to a given session than is necessary. It also gives you more artifacts which need to be maintained as the project involves. Instead of getting too specific, I often favour looser high-level rules of play to coerce the agent in the direction of being as useful as possible for me.
Over time, this is the top-level instruction file I've landed on for Claude. At the time of writing I'm using this with Sonnet 5. My central goal is always to get programming/thinking output from an agent as efficiently as possible without the agent getting bogged down going in circles, running unit tests, e2e tests, spinning up its own headless browser and so on. All of this may be useful if you're vibe coding, but I want to work with AI collaboratively while still holding the reins for the most part. That means I need snappy responses, lean code and minimal context bloat in the conversation.
There are various places you can keep this kind of file to make sure it's in context. Personally, since this so high-level (i.e. not specific to any particular project) I keep this in my root directory as a set of blanket rules (~/.claude/CLAUDE.md) but it's also perfectly reasonable to keep this inside an individual project, especially if you want it in your git repo.
# Global instructions
## Code style
- Only comment on non-obvious logic, tricky edge cases, or the "why" - never restate what the code obviously does. Keep comments to one line; no comment blocks.
- Prefer clear naming over explanatory comments where possible.
## Commands & confirmation
- Never run test suites, builds, dev servers, or browser automation (Playwright, Puppeteer, Cypress, Selenium, headless browsers) without asking first. State what you're about to run and why, then wait for confirmation.
- Batch related edits and verify once, rather than re-running commands after every small change.
## Collaboration & scope
- I'm an experienced engineer - collaborate, don't try to be fully self-sufficient. Check in at decision points rather than pushing through solo.
- For anything beyond a trivial fix, state your plan briefly before editing and wait for a go-ahead.
- If uncertain about a design decision or ambiguous requirement, ask rather than guessing.
- Don't expand scope beyond what was asked (e.g. drive-by refactors) without flagging it first. Default to the smallest change that solves the problem unless a broader one is requested.
- If an approach fails, try a different one at most twice, then stop, summarize what happened, and ask how to proceed.
## Context & efficiency
- Skip node modules, dist, build, .next, vendor, and other generated/dependency directories unless explicitly asked.
- For narrow, single- or two-file tasks, read only what's needed rather than exploring the wider codebase first.
- Reserve subagents or parallel tasks for genuine multi-file exploration, not small localized edits.
- Summarize impact as a short bulleted list when a change touches a public API, shared interface, or function signature used elsewhere.
- If context gets compacted mid-session, prioritize retaining: files modified so far, exact test/build commands used, and architectural decisions made this session.