In Clawd We Trust

This guide is the result of a year of intensive Claude Code usage, approximately 100x normal usage per week. These insights have been hard-won through thousands of hours of iteration, mistakes and refinement. Whether you're just getting started or looking to level up, this document will help you get the most out of Claude Code.

Part 1: The Right Mental Model

Before touching any settings or writing any prompts, you need to understand what Claude Code actually is, and what it isn't.

Build. Don't code.

This is the single most important mindset shift. Claude Code is not a fancy autocomplete. It's not a search engine for Stack Overflow answers. It's a collaborator that can execute on your vision.

Your job is to build. To think about architecture, user experience, system design and business value. Claude's job is to help you realise that vision in code. The more you focus on the "what" and "why", the more Claude can handle the "how".

Claude Code amplifies. It doesn't replace.

Claude Code is a way to increase your output, not replace your ability to think. Treat it as such.

You still need to:

Understand your codebase deeply
Know the patterns, standards, conventions and naming in your system
Make architectural decisions
Review everything

If you abdicate your thinking to Claude, you'll end up with a codebase you don't understand, full of subtle issues you can't diagnose. Claude amplifies your expertise, it doesn't substitute for it.

It does exactly what you tell it to do.

This is both Claude's greatest strength and the source of most frustrations. Claude will do exactly what you tell it to do. The problem is that what you tell it to do may not be what you actually wanted.

This is why:

Precision in your prompts matters
Planning before execution matters
Review after execution matters

When something goes wrong, the first question to ask is: "Did I actually communicate what I wanted?"

Claude will take the path of least resistance.

Like humans, Claude will by default take the shortest route to achieve a goal, even if that route is detrimental to code quality and architecture.

This manifests as:

Quick fixes instead of proper solutions
Workarounds instead of addressing root causes
Minimal implementations that technically satisfy the request but miss the spirit
Incomplete implementations and TODOs

This is where specificity becomes critical. Be explicit about quality expectations. And importantly: telling Claude what NOT to do is very powerful. If you've seen it take shortcuts before, preemptively forbid those shortcuts.

Course correction is your friend here. When you see Claude heading toward a lazy solution, interrupt and redirect.

You must understand your codebase.

You need to know your codebase and repository deeply. You need to know:

The patterns in use
The standards and conventions
The naming conventions
How different parts of the system interconnect

This knowledge is what enables you to:

Catch issues early
Course-correct when Claude creates anti-patterns
Recognise when Claude doesn't have the full context
Make good architectural decisions

Without this understanding, you can't effectively review Claude's work or guide it toward good solutions.

Part 2: Setting up your environment for scale

Your environment determines your ceiling. A well-configured setup multiplies your effectiveness; a poor setup creates constant friction.

Architectural documentation over CLAUDE.md

CLAUDE.md files are useful for giving Claude immediate context, but what's far more valuable is actual architectural documentation in your repository.

This includes:

Standards and patterns: how things should be done in this codebase
Architectural decisions: why the system is structured the way it is
Conventions: naming, file organisation, code style
System overview: how different components interact

This documentation serves two purposes. Claude can reference it to understand how to work within your system. And it forces you to codify decisions that might otherwise be trivial knowledge.

Invest time in creating and maintaining this documentation. It pays dividends not just for Claude, but for your entire team.

Get your entire system running locally

This is critical. When Claude can access your entire system locally, it can:

Safely inspect every facet of the codebase
Make changes to database schemas
Modify infrastructure configurations
Test changes end-to-end
Understand how components interact in practice

If parts of your system only exist in remote environments, Claude is working with incomplete information and can't fully verify its changes.

Let Claude see the bigger picture

If you have multiple repositories that form a larger system, configure Claude to read adjacent repositories in the same directory. This allows Claude to understand how the entire system interconnects, not just the slice it's currently working on.

This context is invaluable for understanding API contracts between services, avoiding breaking changes and maintaining consistency across the system.

Create reusable assets

Power users don't start from scratch every time. Build up a library of reusable assets.

Prompt guides. Create guides for different types of work:

Research prompts: how to investigate a problem or technology
Architecture prompts: how to design a system
Implementation prompts: how to build the solution
Prompt creation prompts: how to generate prompts for each of the above

These guides ensure consistency and capture your accumulated knowledge about what works.

Saved prompts in your repository. Store general prompts that you'll want to execute repeatedly: audit prompts for code quality review, test-fixing loop prompts, documentation update prompts, refactoring prompts. Having these ready to go eliminates friction and ensures you're using proven approaches.

Custom CLI tools. Create CLI tools that Claude can use to execute multi-step tasks more easily. This saves context (Claude doesn't need to understand the underlying complexity), saves time (complex operations become single commands) and reduces errors (the tool encapsulates the correct sequence of steps).

Custom hooks and commands. Build your own hooks and commands that integrate with Claude's workflow. This lets you extend Claude's capabilities in ways specific to your needs.

External documentation and MCPs

For third-party integrations:

MCP servers: if a provider has an MCP integration, use it
llm.txt files: many providers offer their entire documentation in a single file designed for LLMs. Download or copy these locally for easy Claude access
Figma MCP: useful for frontend work, though don't over-optimise here

The key insight: sometimes a simple local text file is more effective than a complex integration.

Keep it simple

Don't try to overcomplicate things by setting up the most advanced workflows possible. This is a common trap.

Overly complex setups waste valuable context on workflow overhead, won't be specific to your actual needs, result in worse output not better and create maintenance burden.

Start simple. Add complexity only when you have a clear, demonstrated need for it. The goal is effective output, not impressive tooling.

Model selection

For primary work, use the most capable model available with extended thinking enabled. The additional reasoning capability is worth it for complex tasks.

For sub-agents handling discrete, well-defined tasks, you can use lighter models appropriate to their needs. The sub-agent doesn't need the full power of your primary model if it's just executing a narrow, well-scoped task.

Match the model to the cognitive demands of the work.

Part 3: The phased workflow

One of the most important realisations is that thinking and doing should be separated. Don't try to do everything in one conversation.

Research → Architect → Implement

For any significant piece of work, use separate conversations for each phase:

Research: investigate the problem space, understand constraints, explore options (plan agentic mode)
Architect: design the solution, make structural decisions, plan the approach (plan agentic mode + architecture.md / CLAUDE.md file)
Implement: execute on the plan (agentic mode with edit / write access)

Each phase gets its own conversation, with its own focused context. Use Claude to create the prompt for each phase, following your prompt guides.

This separation provides several benefits. Each conversation stays focused and doesn't degrade. You can iterate deeply on each phase without context pollution. The output of each phase becomes the input to the next. You can parallelise research while implementing something else.

Leverage markdown files extensively

Use markdown files as your continuity mechanism. They help you track progress through complex tasks, maintain continuity when you need to start new conversations due to context degradation, preserve decisions and rationale, and hand off context between conversation phases.

When a conversation is going well and producing valuable output, have Claude write key decisions and plans to markdown files. This way, if you need to start fresh, you haven't lost that work.

Critical for multi-day work: ensure Claude updates your local progress markdown files as it goes, not just its internal plan files. When you return the next day or after a break, these files are how you pick back up. They're your continuity across sessions, conversations and context resets.

Make your prompts idempotent

Idempotency is critical for reusable prompts. An idempotent prompt can be executed multiple times without modification and will produce consistent, correct results each time.

This matters because you may need to re-run a prompt if a conversation degrades, you might want to apply the same prompt across different contexts, and it enables automation and reduces manual intervention.

Design your saved prompts so they don't depend on specific conversation state or require manual tweaking before each use.

Don't rush to execute

Don't be afraid to spend significant time in back-and-forth conversation before executing anything. Ask questions. Explore edge cases. Challenge assumptions.

This is why separating architecture from implementation is so powerful. You can take your time getting the design right without feeling pressure to start coding.

When Claude asks you a question about approach, don't just pick an option to move forward. Talk through it. Understand the tradeoffs. Come up with the best solution together.

It's better to take your time and plan correctly than to execute blindly and have to undo or redo work.

Plan mode and interrupts

Use plan mode liberally. It lets Claude think through an approach without immediately executing.

And critically: don't be afraid to interrupt. Use ESC mid-execution to course-correct if you see Claude heading in the wrong direction. It's much cheaper to interrupt early than to let a flawed approach run to completion.

Don't be afraid to repeat yourself

Sometimes you need to send Claude the exact same message you sent before.

This happens when Claude summarises what it would do instead of actually doing it, when execution was interrupted and needs to resume, or when Claude misunderstood and you want it to try again with fresh attention.

Don't feel like you need to rephrase. If your original prompt was clear and correct, just send it again. Sometimes emphasis through repetition is exactly what's needed.

Review always

This is non-negotiable. Review everything Claude produces. Not just a quick glance. Actually understand what changed and why.

Your review is the quality gate. Claude is fast but not infallible. Your expertise is what catches the issues that slip through.

Feedback loops are everything

The most effective Claude Code workflows have tight feedback loops that allow rapid iteration toward the desired outcome.

Backend work benefits enormously from tests. Write tests first or alongside implementation, and let test results guide Claude's iteration. When tests fail, Claude has clear signal about what needs to change.

Frontend work is harder because feedback loops are less automated. You need to be more hands-on, checking visual output, testing interactions, verifying behaviour. Consider tools that can provide automated feedback (visual regression, accessibility checks) where possible. You can also use the Claude Code browser extension as a way to test out the final output and close the feedback loop between testing and final developed solution.

The tighter your feedback loop, the faster Claude can converge on the right solution.

When debugging, talk through the problem

When something isn't working, resist the urge to just let Claude brute-force it with repeated attempts.

Instead, talk through the problem. Understand it together. Claude doesn't replace your brain. It augments it. Often Claude can go in the wrong direction, and it's up to you to provide insights, advice or suggestions about what might have gone wrong.

Important nuance: don't be afraid to share your hypotheses, but frame them as possibilities rather than certainties. Say "I think it might be X, but I could be wrong" rather than "It's definitely X". This leaves room for Claude to explore other avenues while still taking your insights into consideration. If you state something as fact, Claude may take your word as gospel and stop exploring alternatives.

Managing conversation context

Claude conversations will deteriorate over time as context accumulates. You need to develop judgment about when to continue an existing conversation (when it already has all the context necessary for your current questions or execution needs) and when to start fresh (when the conversation has become muddled, when you're starting a new phase of work, or when accumulated context is causing confusion).

The VS Code chat UI is helpful here, it lets you restore previous conversations easily, so you can revisit earlier context when needed.

Part 4: Parallelisation and async leverage

This is where power users pull away from casual users. The ability to run multiple Claude instances effectively can multiply your output dramatically.

The multi-clone workflow

For work that could potentially conflict, use separate clones of your repository.

Setup. Create multiple clones of the same repository. Each clone handles work that might have a large blast radius or conflict with other changes. Each clone merges back to a base branch in that cloned repository. Maintain one "primary" repository that pulls all commits on the base branch.

The primary repository is for reviewing changes from all clones, auditing for issues, merging changes and picking up missed anti-patterns or code smells.

For non-overlapping work: keep it in the base repository. No need for clone overhead.

For large changes with big blast radiuses: use separate clones to avoid agents stepping on each other's toes.

This approach is more robust than workstreams because each clone has complete isolation.

Divide and conquer

When facing a large goal, ask: can this be divided and conquered in parallel?

If yes:

Break the work into independent pieces
Use Claude to create prompts for each piece (following your prompt guides)
Execute each piece in a separate Claude Code instance
Integrate the results

Critical warning: be careful with work that must be executed sequentially. Parallel execution of sequential dependencies will create merge conflicts and integration nightmares. Make sure pieces are truly independent before parallelising.

Sub-agents: power with caveats

Don't be afraid to use sub-agents, but be very aware of their limitations.

Sub-agents can much more easily veer off course, and you cannot directly course-correct them the way you can with your main conversation. By the time you see their output, they've already gone down whatever path they chose.

Best practices for sub-agents:

Use them for very discrete and explicit tasks
Limit them to pure execution, not decision-making
Ensure they return only summaries to the main worker
Keep the main conversation's context clean. Don't let sub-agent details pollute it

Sub-agents are powerful for parallelisation, but they require tight scoping to be effective.

Async thinking

Use Claude for background thinking while you work on other things.

Have a question about your codebase? An idea you want to explore? Kick off a Claude instance to research it while you continue your main work. When you're ready, come back to that conversation with all the research done and context loaded.

This turns idle curiosity into actionable insights without interrupting your flow.

Never sit idle

During long-running Claude executions, don't just watch the terminal.

Productive alternatives: research and architect your next steps, improve project hygiene (there's always something), review recent changes, update documentation, work through your TODO list.

There's always something that can be done. Waiting for Claude to finish is wasted time.

Part 5: Maintaining quality at speed

Speed without quality creates technical debt that eventually slows you down more than you gained. These practices keep quality high even at high velocity.

Commit religiously

Commit regularly. Commit often. Commit after every meaningful change.

This makes it trivially easy to revert when something goes wrong. Without frequent commits, a bad change can contaminate a large amount of work, making recovery painful.

Think of commits as save points. You can always go back.

Git is your best friend. Learn it deeply.

One of the biggest wins in using Claude Code effectively is deeply understanding Git and using it to your advantage. Git is a tool you cannot avoid, and failure to understand it will result in lost changes and huge headaches when merging.

Key practices:

Rebase early: rebase your branches to their source branch as soon as you possibly can. The longer you wait, the more painful merges become.
Leverage branching: whether you're collaborating with others or working solo with multiple Claude instances, branches keep work isolated and safe.
Understand Git operations: when Claude performs git operations (resets, checkouts, rebases) you need to understand what's happening. If multiple workers have edited the same file and Claude tries to reset it, you can lose all changes.

Watch out for multi-instance conflicts. When you have multiple Claude instances working in the same repository, be especially careful. Claude might try to reset a file that multiple workers have edited, and you'll lose both sets of changes. Commit frequently and keep work on separate branches to prevent this.

Beware scripts that modify files in bulk

Be extremely careful when Claude attempts to write and run scripts that edit files in bulk.

This often happens with large refactoring tasks: Claude decides it's too tedious to make changes systematically one by one, so it writes a script to do a mass find-and-replace or batch modification.

This can end in disaster.

Before Claude runs any script that modifies multiple files, you must commit all current changes. This ensures you can easily revert if the script does something unexpected. If you don't commit first and the script causes problems, you may have to rewind and lose legitimate changes you've made.

When in doubt, push back on the script approach and ask Claude to tackle changes one by one. It's slower, but it's safer and more reviewable.

Encapsulation is critical

Good encapsulation saves context (Claude doesn't need to understand everything to work on something), keeps code clean and maintainable, reduces blast radius of changes and makes parallel work safer.

Invest in good abstractions and clear boundaries. They pay dividends in Claude Code effectiveness.

Don't be afraid to refactor

Refactoring is not a luxury. It's essential maintenance.

When you see code that's becoming unwieldy, that has accumulated cruft, or that no longer fits the current architecture, refactor it. Claude makes refactoring cheaper than ever, so there's less excuse to let technical debt accumulate.

Just remember to update documentation after refactoring.

Prefer breaking changes over backwards compatibility

Claude will, by default, attempt to maintain backwards compatibility. This can be helpful, but be aware of when it's doing this, especially when you actually want breaking changes.

Generally, prefer breaking changes to ensure clean code and architecture, no pollution from legacy code and artefacts, clear migration paths rather than accumulated shims, and simpler mental models for the codebase.

Backwards compatibility has a cost: complexity that compounds over time. Unless you have a strong reason to maintain it (external APIs, gradual rollouts), opt for clean breaks.

Keep your source code lean

Always prioritise keeping your source code clean and not bloated.

More unnecessary bloat means more context lost when Claude is working. Every line of legacy code, every unused function, every backwards-compatibility shim is context that Claude has to process, potential confusion about what's current vs deprecated and maintenance burden.

Spend time regularly to clean up unused code, refactor verbose implementations, remove legacy compatibility layers and delete code that's no longer needed.

A lean codebase is a codebase Claude can work with effectively.

Hacks and workarounds are signals

If you see Claude creating hacks or workarounds, stop and pay attention.

This usually indicates a larger architectural issue. Claude is trying to solve a problem, but the system's structure is making a clean solution difficult or impossible.

When this happens, take a step back. See the forest, not just the trees. Often the right response is not to accept the hack, but to address the underlying architectural problem that's forcing it.

Regular audits

Run regular audits of your codebase as a background task. Here's an effective audit workflow:

Initial audit: ask Claude to audit changes or sections of the codebase, outputting findings to a dedicated markdown file
Deep dive: ask Claude to iterate over each identified issue, investigating whether it's a legitimate issue or a false positive
Final list: you now have a vetted list of real issues
Remediation: ask Claude to create remediation plans for each issue
Execution: generate prompts for each remediation following your prompt guides
Testing: make Claude Code write unit tests for every feature or bug fixed to ensure the code actually runs

This systematic approach catches issues early, before they compound.

Beware performative tests

When writing tests, watch out for tests that pass consistently but don't actually test your source code, mock so heavily that they're testing the mocks not the implementation, or check that code runs without verifying it produces correct results.

Tests should provide genuine confidence that code works correctly. Performative tests provide false confidence, which is worse than no tests.

Documentation hygiene

Maintain your documentation:

Purge ephemeral docs: remove temporary notes, outdated plans, completed TODOs
Update real documentation: keep architectural docs, standards and guides current, especially after refactoring
Keep things organised: a messy docs folder becomes a docs folder that nobody reads

TODO documents

Maintain TODO documents for capturing thoughts and ideas. These are simple markdown files where you note things you want to investigate, capture ideas for improvements and track non-urgent issues.

When you have time, pick items from your TODO list and run them through the Research → Architect → Implement workflow.

Part 6: Understanding the power (and danger)

Claude Code can do anything the CLI can do. This is incredibly powerful, and also dangerous.

Respect the capabilities

Claude can modify any file in your system, execute arbitrary commands, change database schemas, alter infrastructure and delete things.

This power is what makes Claude Code so effective. It's also what makes review and understanding essential.

Your expertise is the guardrail

Claude doesn't have your judgment about what changes are safe vs risky, what the business impact of a change might be, what conventions matter in your specific context, or what "done" looks like for your specific needs.

Your expertise is what keeps Claude's power channeled productively. Without it, that power can create messes as easily as it creates value.

When Claude asks questions

When Claude asks for your input on an approach, that's not a moment to just pick something and move on.

It's an opportunity to understand the tradeoffs Claude has identified, think through implications, bring your domain knowledge to bear and arrive at a better solution together.

Don't short-circuit this collaboration. It's where some of the best outcomes come from.

Part 7: Principles for long-term success

Focus on architecture and code quality

Everything else follows from this. If your architecture is sound and your code is clean, Claude can work more effectively, changes are less likely to cause problems, the system remains maintainable and velocity stays high over time.

If you sacrifice architecture for speed, you'll eventually lose the speed too.

Follow modern standards and best practices

Always follow industry standards, best practices and established patterns. This gives Claude proven patterns to follow, makes code more maintainable, reduces the chance of novel bugs and makes onboarding easier.

Resist the temptation to do things in non-standard ways unless you have a very good reason.

Know when to step back

Sometimes you're too deep in the details to see the real problem.

If you find yourself fighting the same issue repeatedly, accepting hacks just to move forward, or confused about why things aren't working: stop. Step back. Look at the bigger picture. Often the problem isn't where you're looking, it's in a decision made earlier or an assumption that's no longer valid.

This is a skill

Using Claude Code effectively is a skill that develops over time. You'll make mistakes. You'll learn what works for your specific context. You'll develop intuitions that are hard to articulate.

Give yourself permission to experiment, fail and iterate. The insights that will matter most to you are the ones you discover through your own experience.

A note on these guidelines

These are guidelines, not rules to die by.

Claude will evolve over time, its capabilities, its behaviours, its quirks. These guidelines will need to evolve too. What works today may be unnecessary or counterproductive tomorrow.

More importantly, your context is unique. Your codebase, your team, your domain, your working style, they're all different from anyone else's. Some of these practices will resonate immediately. Others might not fit your situation at all.

Do what feels best for you. Use this guide as a starting point, not a prescription. The goal is to help you develop your own effective relationship with Claude Code, not to follow someone else's playbook rigidly.

Quick reference: key practices

Practice	Why it matters
Separate Research → Architect → Implement	Keeps conversations focused, enables iteration
Use multiple repo clones for parallel work	Prevents conflicts, enables safe parallel execution
Commit religiously	Easy rollback, clear history
Master Git (branching, rebasing)	Prevents lost changes, enables collaboration
Review everything	Quality gate, catches issues
Plan mode + ESC interrupts	Control execution, course-correct early
Tight feedback loops (tests)	Fast convergence to correct solutions
Talk through problems, don't brute force	Better debugging, collaborative problem-solving
Regular audits	Catch issues early
Maintain documentation	Enables Claude, captures knowledge
Build reusable prompts and tools	Consistency, efficiency
Don't sit idle during execution	Maximise productive time
Understand your codebase deeply	Enables effective guidance and review
Watch for hacks as signals	Catch architectural issues
Focus on architecture and quality	Everything else follows
Prefer breaking changes over backwards compatibility	Keeps codebase clean and lean
Keep source code lean	More bloat = more lost context
Use sub-agents for discrete tasks only	They veer off course easily
Leverage markdown for continuity	Survive conversation degradation and multi-day work
Make prompts idempotent	Enables reuse without modification
Tell Claude what NOT to do	Prevents lazy shortcuts
Keep it simple	Complex workflows waste context
Commit before bulk-modify scripts	Prevents catastrophic loss of changes
Share hypotheses as possibilities	Leaves room for Claude to explore

Final thought

Claude Code is a tool of remarkable capability. In the hands of someone who understands their craft, it's a force multiplier unlike anything we've had before. Not 10x or 20x, but 100x.

But it's still a tool. The thinking, the judgment, the architecture, the quality standards: those come from you.

Build. Don't just code.

In Clawd we trust.