Claude Code: Best Practices for Coding
- Team Ellenox
- Aug 9
- 4 min read
Claude Code works best when it has the right context, a clear workflow, and a disciplined approach to planning, coding, and managing knowledge. Before diving in, you should read the official Claude documentation to understand its features, limitations, and intended usage.
In this guide, we break down how to structure Claude sessions and use CLAUDE.MD files effectively.
1. Core Principles
Context is fuel: Claude’s output quality depends directly on what you provide.
Plan when needed: Do not over-plan; start coding when the path is obvious.
Keep context clean: Avoid bloated sessions that dilute important details.
Stay in control: Review every AI-generated change for quality, security, and consistency.
2. CLAUDE.md and Other Markdown Files
What Is CLAUDE.md
CLAUDE.md is a Markdown file that Claude automatically loads at the start of every session in the relevant directory.
It is technically a normal Markdown file, but its importance comes from how Claude uses it to establish context before you start work.
This file acts as persistent working memory. It should contain:
Project-wide coding conventions
Set up and environment instructions
Preferred tools and commands
Testing strategy
Domain-specific guidance Claude should always follow
If you want to go further and create a Claude Code agent, see this Pastebin prompt. It is designed to generate the CLAUDE.md file and other requirements according to these best practices.
Example – Root-level CLAUDE.md
# Project Context
Tech stack: Python 3.11, FastAPI, PostgreSQL 15
Code style: PEP8 + Black formatting
Test strategy: pytest with coverage threshold 90%
Deployment: GitHub Actions → AWS Lambda
File Placement
CLAUDE.md can be:
In the repo root for project-wide settings
In a subdirectory for module-specific rules in a monorepo
In a parent directory for shared settings across multiple repos
In your home folder (~/.claude/CLAUDE.md) for global defaults
Claude merges these contexts, giving priority to the closest file.
Core File Types
File | Purpose | Audience |
Persistent context and rules | Claude | |
Scoped feature plan | Humans and Claude | |
Prioritized to-do list | Humans and Claude | |
Product requirements document | Humans | |
Architecture and technical decisions | Humans |
Difference from PRD.md or TechDesign.md
CLAUDE.md: concise, directive, and auto-loaded
PRD.md and TechDesign.md: longer narrative documents for humans; not auto-loaded and must be opened explicitly
Other .md files are standard documentation unless you tell Claude to read them.
Best Practices for CLAUDE.md
Keep it short (a few hundred words)
Store high-level project goals, coding conventions, naming schemes, and architecture notes
Avoid pasting entire PRDs; link to them instead
3. Planning Mode
When to Use
For complex, multi-step tasks where Claude should outline a sequence before execution
When requirements are unclear and need clarification
When to Skip
For small, well-defined changes where extra planning overhead is not worth it
If you already know the exact implementation path
Recommended Workflow
Try executing directly for small tasks
If results are wrong or messy, restart and use Planning Mode
Storing Plans
Save significant plans to a .md file (FeaturePlan.md or Roadmap.md)
Avoid storing every minor plan to reduce clutter
4. Managing Markdown Files and Context
How Many .md Files are too Many
Every .md file you load consumes part of the context window. Too many large files can:
Push out important details mid-session
Confuse Claude if the information is duplicated or contradictory
Best practice:
Keep the number of active .md files small and purposeful
Use one for base context (CLAUDE.md), one for backlog, and a small set for major features
Level of Abstraction
CLAUDE.md: project overview, coding style, high-level principles
Feature files: targeted and scoped to one area
Avoid large combined files containing everything; Claude will skim or miss details.
5. Commands, Sessions, and Context Hygiene
When to Run /compact
Only if you truly need to shrink a long conversation without losing core points.
It is a temporary tool, not a long-term archive
Frequent use can remove nuance and important details
Instead:
Start a new session when the context gets noisy
Break big work into smaller, fresh sessions
Does /compact Save to CLAUDE.md?
No. It only condenses the current chat context in memory. To preserve something, manually paste it into an .md file.
Session Lifecycle
Start fresh sessions for new major features or bug categories
Use /init to set up a clean environment with your base files
For exploratory sessions, you can start without prep, but load your key .md files first for important work
Exploration Output
Save valuable exploration results to a dedicated .md file
Avoid keeping huge exploratory logs in context
6. Backlog and TODO Management
Why Backlog.md Exists
Centralizes tasks so Claude can easily reference them. Unlike scattered TODOs, Claude knows to check Backlog.md if you point it there.
Best Practices
Keep backlog items small and actionable
Update regularly to prevent drift
Archive completed items separately to keep context clean
7. Sub-Agents and External Tools
When to Use Sub-Agents
Parallelizable work, such as generating multiple feature stubs or testing different designs
Cross-domain tasks where one agent codes and another writes documentation
Risks
Can consume tokens quickly (often four times higher usage)
Merging outputs can be messy
Claude Swarm vs. Plain Claude Code
Swarm or MCP servers: scalable workflows, more complexity
Plain Claude Code: simpler and easier for most teams
Agent Output Management
Save agent results in agent_reports/featureX.md
Avoid adding temporary outputs to CLAUDE.md
8. Staying in Control of Your Code When Using AI
Provide complete context: problem description, code samples, edge cases, and non-functional requirements
Keep architecture consistent: check for deviations from your established design
Understand the implementation: read AI-generated code before merging
Prevent security oversights: verify authentication, authorization, and data handling before production
9. Picking the Right Way to Work With AI
Prototype-First Approach: For low-impact features, let the AI draft freely, then review
Continuous Review Approach: For sensitive or business-critical features, guide the AI step-by-step
Comments