Setup decisions and habits that have made a real difference in how much I get out of Claude Code. Some are obvious in retrospect. Most I learned by wasting time doing it the other way first.
For any non-trivial feature (3+ steps, or anything involving architectural decisions), enter plan mode before writing code (start the session with --permission-mode plan, or switch modes in the UI). Add "do deep research on best practices and known issues, using web search" to your prompt. Claude will come back with a structured plan.
Read the plan. Adjust it. Then let it execute.
This matters more than it sounds like it should. Plans survive context compaction much better than vibe-prompted features do. When you're 40 messages into a session and the context window starts compressing earlier messages, a plan at the top of the conversation keeps the LLM anchored. Without one, bigger features tend to drift or lose coherence as the session goes on.
If something goes sideways mid-build, stop and re-plan. Don't let the LLM keep pushing through a broken approach. It will dig itself deeper.
Install the context-mode plugin:
/plugin marketplace add mksglu/context-mode
This uses an MCP server to load files into context via reference instead of parking the full file contents in the conversation. The practical effect is a significantly larger effective context window. For any project with more than a handful of files, it's worth the 30 seconds to install.
Create a /documents/ directory with these files. None of them should be loaded by default -- they're on-demand references that the LLM reads when a task requires them (see the architecture guide's documentation stack for the token budget reasoning).
platform-docs.md -- Describes every feature of your product in detail. Not marketing copy. Actual descriptions of what each screen does, what each component shows, how the business logic works. You can generate an initial version by having Claude Code go through each file and screen and summarize functionality. Then edit it into something accurate.
ICPs.md -- Ideal Customer Profiles. A dossier for each type of user: who they are, what they need, what they can and can't do, what frustrates them. Think private detective report, not marketing persona. This keeps Claude from making UX decisions in a vacuum.
styleguide.md -- The visual language of your application. Colors, typography, component hierarchy, spacing, responsive breakpoints. You can generate an initial version from an existing codebase using the --chrome flag to let Claude see the running app. Then refine it.
roadmap.md or vision.md -- Where the product is going. This gives exploratory runs some guardrails. Without it, Claude will build speculative features that don't fit your direction. With it, suggestions tend to align with what you actually want.
data-reference.md -- The connections between your domain data that aren't obvious from the models and their relationships. Implicit business rules, edge cases, the stuff a new developer would get wrong on their first PR. If an LLM has to guess at domain logic, it will guess wrong.
Your CLAUDE.md is the entry point for every session. It should index your /documents/*.md files with conditional triggers -- telling the LLM when to load each one, not dumping them all up front. This follows the Search over Scan principle: the LLM loads what's relevant to the current task, not everything that exists.
## Product documentation
All product documentation lives in `/documents/`.
| Document | When to read |
|----------|-------------|
| platform-docs.md | Before adding or modifying any feature. |
| ICPs.md | When making UX decisions or designing user-facing flows. |
| styleguide.md | When creating or modifying UI components. |
| roadmap.md | Before building speculative features or suggesting new scope. |
| data-reference.md | Before any data model, API, or schema changes. |
### Compliance rules
- Use colors, fonts, and patterns from styleguide.md. No new colors without updating the guide.
- New features must be documented in platform-docs.md after implementation.
- Schema or API changes must be reflected in data-reference.md.The compliance rules belong in CLAUDE.md because they're short and always relevant. The docs themselves stay on disk until needed. This way your CLAUDE.md costs ~200 tokens for the index instead of 10K+ tokens loading everything every session.
These go in your CLAUDE.md and tell the LLM how to work, not just what to work on. They've cut the amount of back-and-forth correction in my sessions significantly.
Tell Claude to offload research, exploration, and parallel analysis to subagents. One task per subagent keeps execution focused and keeps the main context window clean. For complex problems, more compute via subagents beats trying to do everything in a single thread.
## Subagent strategy
- Use subagents liberally to keep main context window clean
- Offload research, exploration, and parallel analysis to subagents
- One task per subagent for focused executionAfter any correction, have Claude update a tasks/lessons.md file with the pattern. The rules should be specific enough to prevent the same mistake next time. Over a few sessions, this file becomes a project-specific style guide for the LLM.
## Self-improvement loop
- After ANY correction from the user: update tasks/lessons.md with the pattern
- Write rules for yourself that prevent the same mistake
- Review lessons at session startNever let the LLM mark a task complete without proving it works. Run the tests. Check the actual output. Diff against main if relevant. "Would a staff engineer approve this?" is a useful gut check to put in the CLAUDE.md.
## Verification
- Never mark a task complete without proving it works
- Run tests, check logs, demonstrate correctness
- Diff behavior between main and your changes when relevantWhen you hand Claude a bug report, it should just fix it. No asking you to look up error messages or check logs. It has the tools. Point at the problem and let it resolve everything -- including failing CI -- without requiring you to context-switch.
## Bug fixing
- When given a bug report: just fix it. Don't ask for hand-holding.
- Point at logs, errors, failing tests, then resolve them
- Zero context switching required from the userFor anything that takes more than a few steps, have Claude write a plan to tasks/todo.md with checkable items. Mark items complete as they're done. Add a review section when finished. This gives you a paper trail and gives the LLM something concrete to reference when the context window gets long.
## Task management
1. Write plan to tasks/todo.md with checkable items
2. Check in before starting implementation
3. Mark items complete as you go
4. Document results and add a review section
5. Capture lessons after correctionsThese three go at the top. They're short and they prevent the most common failure modes.
Simplicity first. Make every change as simple as possible. Touch minimal code. The LLM's instinct is to over-engineer. Push back on that.
Find root causes. No temporary fixes, no bandaids, no "this should work for now." Senior developer standards. If something is broken, find out why and fix the actual problem.
Minimal impact. Changes should only touch what's necessary. If the task is to fix a button color, don't also refactor the component's state management.
Review habits only work when someone remembers to run them. But do NOT reach for headless Claude in CI to fix that: as of June 15, 2026, headless Claude Code (including anthropics/claude-code-action) bills to API credits, not your subscription. If your team works on subscription billing, the interactive session is the only surface where Claude runs at no marginal cost — so enforcement belongs in the session, and CI should stay LLM-free.
The stack, in order of value:
1. The push gate (ships with the qa-check plugin). Installing the qa-check plugin installs a PreToolUse hook that intercepts git push from any Claude Code session. In repos that opt in, the push is blocked until /qa-check has run against the current HEAD (or within the last 30 minutes — covering the normal check → fix → commit → push flow). The gate is a deterministic shell script: zero model calls, zero API cost.
- Opt a repo in:
touch .qa-check-requiredat the repo root (commit it). /qa-checkwrites the freshness marker (.git/qa-check-ok) automatically when it completes.- Deliberate override, one push:
QA_CHECK_SKIP=1 git push.
Because the whole team writes code through Claude Code, gating the session's git push IS gating the PR — at the moment the work happens, on subscription, instead of after the fact on API credits.
2. A free CI check that the QA report made it to the PR. No LLM — just verify the PR description contains the report the author's session already produced. .github/workflows/qa-report-check.yml:
name: qa-report-present
on:
pull_request:
types: [opened, edited, synchronize]
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Require QA Check Report in PR body
env:
BODY: ${{ github.event.pull_request.body }}
run: |
if ! grep -q "## QA Check Report" <<< "$BODY"; then
echo "::error::PR description is missing the QA Check Report. Run /qa-check and paste the report."
exit 1
fi3. Deterministic gates in CI. Linters, type checks, tests, coverage diffs — these were always LLM-free and they stay in CI. qa-check complements them; it never replaces them.
If your organization bills through the API anyway (no subscription seats), running /qa-check headless on PRs via claude-code-action@v1 works — but price it first; per-PR LLM review across an active org adds up quickly. For subscription teams the push gate above gives the same enforcement for free.
The context window resets every session. If the knowledge is in your head but not in the files, the LLM is working with incomplete information and you'll spend your time correcting it instead of building.
Put the knowledge in files. Index those files from CLAUDE.md with conditional triggers so the LLM loads what it needs, when it needs it.