Best Practices for Claude Code Users
A consolidated reference for getting consistent, high-quality results from Claude Code in VS Code — individually and as a team. This module covers daily workflow patterns, production readiness, error handling, cost management, security, and scaling strategies.
Always Give Context
Claude only knows what you show it. Before asking anything non-trivial, attach the relevant files with @. A question with context gets a specific, usable answer. Without context, Claude guesses — and confident guesses are the most dangerous kind.
Be Specific About Output
Define exactly what you want: format, length, tone, what to avoid. "Two sentences, no exclamation marks, mention organic cotton" beats "make it sound good" every time. Specificity is the single biggest lever for output quality.
Review Before Accepting
Read every diff before clicking Accept. Claude is highly capable but not infallible — especially on code it can't fully see or test. You are the final reviewer. This applies to copy as well as code — always verify facts, dates, and claims.
Build Team Conventions
Shared CLAUDE.md files, a prompt library, and agreed-upon patterns mean every team member gets the same quality baseline. Don't let good prompts live only in one person's head.
The Daily Workflow Checklist
Start each session with CLAUDE.md in place
Ensure your project's CLAUDE.md is current — project context, conventions, and any task-specific instructions. This saves you re-explaining the same things every session. Review it weekly and update when conventions change.
Use /clear between unrelated tasks
Don't let context from a product-copy task contaminate a code-review task. A clean context window produces cleaner outputs. A common mistake is carrying over a long conversation about feature A when you start asking about feature B — Claude will mix concerns.
Attach files — don't paste
Use @filename rather than pasting content. It's faster, keeps the chat cleaner, and Claude can reference the file path when explaining changes. Pasting large blocks of code into chat wastes context window space on formatting overhead.
Iterate, don't over-specify upfront
A good first prompt + two refinement turns beats a 200-word prompt that tries to anticipate everything. Start broad, then tighten. Each iteration builds on Claude's understanding from the previous turn.
Save great prompts as team resources
When a prompt produces consistently excellent results, save it — in a Notion doc, a prompts/ folder in the repo, or as a custom slash command in CLAUDE.md. Treat prompts as reusable assets, just like code libraries.
Production-Ready Patterns
When Claude-generated outputs go into production — customer-facing copy, deployed code, or automated workflows — you need additional safeguards beyond "it looked good in the chat panel."
Human-in-the-Loop
For any customer-facing output, always have a human review step. Set up a workflow where Claude drafts and a human approves. Never let Claude publish directly without review — not because Claude is bad, but because even a 1% error rate is unacceptable for customer communication at scale.
Version Control Everything
Treat prompts like code: version them, review changes, and track which prompt version produced which outputs. When a prompt changes, log why. This is critical for debugging when output quality suddenly drops — you can diff the prompt versions.
Test with Edge Cases
Before deploying a prompt to production, test it with adversarial inputs: empty data, very long text, text in other languages, special characters, and deliberately misleading content. A prompt that works on your 5 test cases might fail on the 6th.
Structured Output Validation
When Claude returns JSON or structured data, always validate against a schema before using it. Claude occasionally produces almost-valid JSON (trailing commas, missing closing brackets). A validation step catches these before they break your pipeline.
Error Handling Best Practices
Things go wrong. Here is how to handle the most common failure modes when working with Claude:
| Error | Cause | Fix |
|---|---|---|
| Output is generic/off-topic | Missing context — Claude doesn't have enough information | Attach relevant files with @, add background context, specify what "good" looks like with examples |
| Output contradicts your instructions | Conflicting instructions in CLAUDE.md or the conversation | Review CLAUDE.md for contradictions. Use /clear and start fresh with a single, consistent set of instructions |
| Claude refuses a legitimate request | Safety classifier false positive | Rephrase with clear, professional intent. Add context about why you need this. Be specific about the business use case |
| Code edit breaks something | Claude couldn't see all dependent files | Before accepting edits, @ mention all files that depend on the changed code. Ask Claude to check for breakage |
| Output quality degrades mid-conversation | Context window filling up with old, irrelevant content | Use /compact to summarise history, or /clear to start fresh for the new task |
| JSON output is malformed | Claude truncated output due to max_tokens limit | Increase max_tokens, simplify the requested output structure, or ask for one section at a time |
| Different results every time | High temperature or ambiguous prompt | Add more constraints to the prompt. In API calls, set temperature to 0 for deterministic output |
The most dangerous errors are the ones that look correct but aren't. A product description that sounds great but contains a factual error. A code change that passes tests but introduces a subtle race condition. Build review processes that catch these: automated tests for code, fact-checking workflows for content, and schema validation for structured data.
Cost Optimisation
Claude costs are per-token, and they add up at scale. Here are the practical levers for controlling spend:
Use the Right Model for Each Task
Haiku for classification, routing, and quick summaries. Sonnet for most daily work. Opus only for tasks where quality materially differs. The cost difference between Haiku and Opus is roughly 10x — at 1,000 requests/day, this matters.
Minimise Context Window Usage
Don't attach your entire codebase when Claude only needs one file. Be selective with @ mentions. Use /clear between tasks to avoid carrying unnecessary context. Each token in the context window costs money — even on input.
Set Appropriate max_tokens
If you need a 2-sentence answer, don't leave max_tokens at 4096. In the API, set it to what you actually need. In Claude Code, specify length in your prompt: "Answer in one paragraph" prevents Claude from writing a 500-word essay when you needed 50 words.
Cache Repeated Prompts
If you send the same system prompt with every request (common in production), use Anthropic's prompt caching feature. Cached prompt tokens cost 90% less after the first request. See Module 18 (Advanced Techniques) for implementation details.
Batch Non-Urgent Work
Anthropic's Batch API processes requests asynchronously at 50% cost. If your task doesn't need real-time results (e.g., processing 2,000 product descriptions overnight), use batching.
Right Model for the Right Task
| Task | Model | Why | Approximate Cost per 1K Requests |
|---|---|---|---|
| Quick drafts, summaries, short copy | Haiku | Fastest, cheapest — ideal for high-volume routine tasks | ~$0.50 |
| Code generation, reviews, most daily work | Sonnet | Best balance of speed, quality, and cost | ~$5.00 |
| Complex reasoning, architecture, security review | Opus | Most capable — worth the cost for high-stakes decisions | ~$50.00 |
Security Best Practices
Using Claude in a professional context requires awareness of what data you are sending and how it is handled.
Know What You're Sending
Every file you @ mention and every message you type is sent to Anthropic's servers for processing. Do not send passwords, API keys, customer PII, or confidential financial data in casual chat. If you need to work with sensitive code, redact secrets first.
Use Environment Variables
Never hardcode secrets in files you share with Claude. Use .env files (which should be in .gitignore) and reference environment variable names, not values. Ask Claude to write code that reads from env vars, not code that contains them.
Review Generated Code for Security
Claude writes secure code most of the time, but you should verify: Are inputs validated? Is authentication checked? Are SQL queries parameterised? Is error output sanitised? Use Claude itself to do a security review of its own code — it catches many issues on the second pass.
Understand Data Retention
Anthropic's data retention policies vary by plan. Enterprise plans offer zero data retention and no training on your data. Consumer plans may use conversations for model improvement. Check your plan's terms and use the appropriate tier for sensitive work.
If your application passes user input to Claude (e.g., a customer support bot that includes the customer's message in the prompt), be aware of prompt injection — where the user crafts input designed to override your instructions. Mitigations: use XML tags to separate trusted instructions from untrusted input, validate Claude's output against expected formats, and never give Claude access to destructive actions (database deletes, payment processing) without human confirmation.
Monitoring and Scaling
As your Claude usage grows from experimental to production, you need visibility into what is happening:
Track Usage Metrics
Monitor tokens consumed per team member, per task type, and per model. This identifies waste (someone running Opus for classification tasks) and capacity needs. Use the Anthropic Console dashboard or API usage endpoints.
Log Inputs and Outputs
For production integrations, log every prompt and response (with sensitive data redacted). When output quality drops, you can trace back to the exact prompt that caused it. This is essential for debugging and auditing.
Set Rate Limits and Budgets
Anthropic enforces rate limits per tier. Know your limits and design for them. Set budget alerts so a runaway script doesn't burn through your monthly allocation in an hour. Most teams set per-project budget caps.
Build Fallback Logic
The API can return 429 (rate limited), 529 (overloaded), or 500 (server error). Your production code should retry with exponential backoff, fall back to a simpler model, or queue the request for later. Never let a single API failure crash your user experience.
Quality Scoring
For production outputs, implement automated quality checks: Does the JSON validate? Is the sentiment correct? Does the response contain forbidden words? Automated scoring catches degradation before customers see it.
Team Alignment Checklist
Before rolling out Claude to a team, spend 30 minutes aligning on these decisions:
| Decision | Options | ThreadCo's Choice |
|---|---|---|
| Which model for which task? | Define a routing table | Haiku for classification, Sonnet for daily work, Opus for architecture |
| What goes in CLAUDE.md? | Project context, coding standards, brand voice | 500-word file covering voice, code standards, and forbidden patterns |
| Where do prompts live? | Notion, repo folder, or shared doc | prompts/ folder in the repo, version-controlled with the code |
| What data can be shared? | Define sensitivity levels | No customer PII, no API keys, no financial data in chat |
| Review workflow for outputs? | Human review, automated checks, or both | Automated schema validation + human review for customer-facing content |
| Budget and usage tracking? | Per-person, per-project, or per-task | Per-project budget caps, monthly usage review |
If your team needs to call Claude from custom code or automate workflows beyond what Claude Code's IDE tools support, see Module 19: API Usage for the developer/API track.
Common Anti-Patterns to Avoid
These are the mistakes teams make most often in their first month of Claude adoption. Knowing them upfront saves weeks of frustration.
The "One Size Fits All" Prompt
Using the same prompt for every task type. A prompt optimised for product descriptions will produce bad code reviews. Build task-specific prompts and store them in your prompt library. A library of 10 great prompts beats one mediocre generic prompt.
Ignoring CLAUDE.md
The most common anti-pattern: not creating a CLAUDE.md at all. Without standing instructions, every team member starts from zero every session. Spend 20 minutes writing a CLAUDE.md and you save 5 minutes per session, per person, forever.
Context Window Overload
Attaching every file in the workspace "just in case." More context is not always better — it dilutes Claude's attention. Attach only the files relevant to the current task. Use /clear between unrelated tasks. Be surgical with your @ mentions.
Skipping the Review Step
Clicking "Accept" on every diff without reading it. Claude's accuracy is high but not perfect — and the errors it makes are often subtle (wrong variable name, missing edge case, outdated API usage). The review step is where you catch the 2% that matters.
Anti-Pattern: Prompt Drift
A prompt that worked great last month slowly degrades because the underlying data or requirements changed, but nobody updated the prompt. Treat prompts like code — review them regularly, version them, and update them when the context changes.
Anti-Pattern: "Fix Everything" Requests
Asking Claude to "fix all the bugs in this file" or "improve everything" produces unfocused results. Claude works best with specific, scoped requests. "Fix the null reference on line 42" is far more effective than "fix the bugs."
Anti-Pattern: No Feedback Loop
Using Claude's output without ever telling it what was good or bad. If Claude produces a description that is almost right, tell it what to change: "The tone is right but the length is too long." This teaches Claude your preferences within the session and produces better results on the next request.
Anti-Pattern: Opus for Everything
Using the most expensive model for every task because "it's the best." For 80% of tasks, Sonnet produces identical quality at 1/5 the cost. Reserve Opus for the 20% where depth and nuance genuinely matter. Track where Opus makes a real difference — you will find it is less often than you think.
Anti-Pattern: No Structured Output Validation
Trusting Claude's JSON output without validating it against a schema. Claude occasionally generates invalid JSON (especially under token pressure). Always parse and validate before using the output in downstream systems. A simple try/catch around JSON.parse saves production incidents.
Measuring Claude Output Quality
You cannot improve what you do not measure. Here is a practical framework for tracking Claude's output quality over time:
| Metric | How to Measure | Target |
|---|---|---|
| Accuracy | Spot-check 5% of outputs against ground truth or human judgment | > 95% factually correct |
| Format compliance | Automated check — does the output match the requested format (JSON schema, word count, etc.)? | > 99% valid format |
| Brand voice match | Weekly review of 10 random outputs against brand guide | > 90% on-brand (no forbidden words, correct tone) |
| Code correctness | Do generated tests pass? Does generated code compile? Does it pass linting? | > 90% passes on first run |
| User satisfaction | Track how often team members accept vs reject Claude's suggestions | > 80% acceptance rate |
| Time saved | Compare task completion time with and without Claude (sample periodically) | > 30% time reduction for routine tasks |
Quick Reference — Best Practices Summary
| Category | Do | Don't |
|---|---|---|
| Context | Attach specific files with @. Use CLAUDE.md for standing context. | Paste large blocks into chat. Attach entire workspace. |
| Prompts | Be specific about format, length, and constraints. Use XML tags. | Say "make it better" or "be creative" without constraints. |
| Review | Read every diff. Verify facts. Run tests before merging. | Accept all suggestions blindly. Skip the diff view. |
| Models | Use Haiku for simple tasks, Sonnet for daily work, Opus for complex reasoning. | Use Opus for everything. Use Haiku for complex analysis. |
| Sessions | Use /clear between tasks. Use /compact for long sessions. | Let context from Task A bleed into Task B. |
| Security | Redact secrets before sharing. Use env var names, not values. | Paste API keys or customer PII into chat. |
| Team | Share CLAUDE.md, prompt library, and model routing decisions. | Let each person discover best practices independently. |
| Cost | Route models, cache prompts, batch non-urgent work. | Ignore token usage. Send unnecessary context. |
Common Anti-Patterns to Avoid
These are the patterns that consistently lead to poor results. Learning to recognise them is as valuable as learning the best practices themselves.
The "Kitchen Sink" Prompt
Cramming every possible instruction into a single message. "Write copy, make it SEO-friendly, add keywords, keep it under 50 words, make it funny, mention sustainability, target millennials, and don't use passive voice." Claude tries to satisfy every constraint and satisfies none well. Break it into steps or prioritise 3-4 key constraints.
The "Fire and Forget" Workflow
Sending one prompt and accepting whatever comes back without review or refinement. The best results come from a dialogue: prompt, review, refine, review. Budget for 2-3 turns on any non-trivial task.
The "Context Hoarder"
Attaching every file in the project "just in case." More context is not always better — irrelevant context dilutes Claude's attention and increases cost. Attach only the files Claude needs for this specific task.
The "Model Maximiser"
Using Opus for everything because "it's the best." Opus is the best for complex reasoning tasks. For classification, simple drafts, and routine code, Haiku or Sonnet produce equivalent quality at a fraction of the cost and with lower latency.
| Anti-Pattern | Symptom | Fix |
|---|---|---|
| No CLAUDE.md | Team members re-explaining the same context every session | Create a CLAUDE.md with project context, conventions, and rules |
| Pasting instead of @ | Chat gets cluttered, tokens wasted on formatting | Use @filename for all file references |
| Never using /clear | Context pollution — old conversation bleeds into new tasks | Use /clear between unrelated tasks |
| Accepting code without testing | Bugs ship to production | Always run tests after accepting Claude's edits |
| Sharing secrets in chat | API keys, passwords, PII sent to external servers | Redact secrets before sharing; use env var references |
| Not versioning prompts | Can't reproduce results; no audit trail | Store prompts in version-controlled prompts/ folder |
| Ignoring token costs | Surprise bills at end of month | Set budget alerts; track usage per project |
Building a Team Prompt Library
A prompt library is one of the highest-leverage investments you can make for consistent Claude usage across a team. Here is the structure ThreadCo uses:
prompts/
README.md # How to use and contribute to the library
product-description.md # Template for writing product descriptions
email-reply.md # Template for customer email responses
code-review.md # Template for code review requests
bug-report-analysis.md # Template for analysing bug reports
competitor-analysis.md # Template for competitor comparisons
weekly-report.md # Template for weekly summary generation
# Product Description Template
# Version: 2.3 — Last updated: 2026-04-10 by Maya
# Model: Sonnet (Haiku for bulk batches)
# Average quality score: 8.5/10
## Instructions for Claude
You are a ThreadCo copywriter writing product descriptions.
<brand_voice>
Friendly, direct, slightly playful. Never corporate.
Sustainability is a feature, not a badge — mention it naturally.
Forbidden words: vibrant, perfect, stylish, must-have, luxurious
No exclamation marks.
</brand_voice>
<format>
Exactly 2 sentences.
Sentence 1: What the product is (material, design, origin).
Sentence 2: How it feels or what it's like to wear.
</format>
<examples>
Product: Sunset Gradient Tee
Description: Made from 100% organic cotton in Portugal, the Sunset
Gradient fades from amber to rose across the chest. Relaxed fit,
pre-shrunk, and softer after every wash.
</examples>
## Usage
Write a description for [PRODUCT NAME]. Details: [PRODUCT DETAILS]
Each template includes: a version number, the last editor, the recommended model, a quality score from testing, and structured instructions with XML tags. Version the templates alongside your code so changes are tracked and reviewable.
Measuring Output Quality
You cannot improve what you do not measure. Here are practical quality metrics for different output types:
| Output Type | Quality Metrics | How to Measure |
|---|---|---|
| Product copy | Brand voice match, constraint compliance, factual accuracy | Human rubric (1-10), automated check for forbidden words and format |
| Code | Tests pass, type safety, no security issues, follows conventions | Automated: test suite, linter, type checker. Human: code review |
| Customer emails | Tone appropriate, factually correct, actionable, correct contact info | Human review sample (10%), customer satisfaction score |
| Structured data (JSON) | Schema valid, all fields populated, values in expected ranges | Automated schema validation, range checks, completeness checks |
| Analysis / reports | Conclusions supported by data, no hallucinated facts, actionable recommendations | Human expert review, fact-checking against source data |
Claude gets 90% of outputs right with minimal effort. The remaining 10% require careful review and occasional correction. Your quality processes should be designed for that 10% — the errors that slip through, the edge cases that confuse the model, the subtle hallucinations that look correct at first glance. Do not build your process assuming 100% accuracy — build it assuming 90% accuracy with excellent review for the rest.
Hands-On Exercises
Open your project's CLAUDE.md (or create one if it doesn't exist). Review it against the guidelines in this module: Is it under 500 words? Does it cover role, coding standards, brand voice, and "do not" rules? Remove anything vague. Test it by starting a new session and asking Claude a project-relevant question — does it follow the instructions without being reminded?
Deliberately create each error scenario from the Error Handling table above: give Claude a task with no context, introduce conflicting instructions, fill the context window until quality degrades. Practice the recovery technique for each. This builds muscle memory for when these issues occur during real work.
Estimate your team's Claude usage for the next month. For each task type, calculate: (number of requests) x (average tokens per request) x (price per token for the appropriate model). Compare the total cost if you use Sonnet for everything vs. a routed approach (Haiku for simple tasks, Sonnet for medium, Opus for complex). How much does routing save?
Review your last 5 Claude conversations. Did you accidentally share any sensitive data — API keys, customer emails, internal URLs, passwords? Create a "before sharing" checklist for your team that covers what to redact. Store it in CLAUDE.md under a "## Security" section.
Run a 30-minute team meeting using the Team Alignment Checklist above. For each row, make a decision and document it. Assign someone to implement each decision (update CLAUDE.md, create the prompts folder, set up budget tracking). Schedule a follow-up in 2 weeks to check adoption.