DEV Community

Joodi
Joodi

Posted on

Claude Code Best Practices: How to Use CLAUDE.md for Better AI Coding

#claude #ai #programming #frontend

Most developers are using Claude Code completely wrong.

They open a new session, type a prompt like:

build dashboard
Enter fullscreen mode Exit fullscreen mode

then wonder why the generated code has bad structure, inconsistent naming, weird architecture decisions, or UI patterns that do not match the project.

Here’s the thing:

Claude Code is powerful, but without context, it still has to guess.

And guessing inside a real production codebase creates problems fast.

The biggest difference between average AI-assisted development and professional AI-assisted development is not better prompting.

It is better context.

That is where CLAUDE.md becomes important.

What is CLAUDE.md?

CLAUDE.md is the most important file in a Claude Code workflow.

Every time Claude starts working on your project, it reads this file first.

This file explains:

  • what the project does
  • which technologies are used
  • architecture decisions
  • folder structure
  • coding conventions
  • UI patterns
  • development commands
  • reusable project rules

Without this file, Claude starts from zero every session.

That usually leads to:

  • inconsistent code
  • wrong assumptions
  • structural mistakes
  • repeated explanations
  • unnecessary refactoring
  • more editing after generation

With proper context, Claude becomes dramatically more accurate.

Two Types of CLAUDE.md

1. Global CLAUDE.md

Location:

~/.claude/CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

This affects every project.

Use it for personal engineering preferences.

Example:

- Always use TypeScript
- Prefer functional components
- Avoid inline styles
- Prefer composition over duplication
- Keep components small and reusable
Enter fullscreen mode Exit fullscreen mode

Think of this as your permanent engineering personality.

2. Project-Level CLAUDE.md

Location:

project-root/CLAUDE.md
Enter fullscreen mode Exit fullscreen mode

This one is project-specific.

Example:

- Project uses Next.js 15 App Router
- State management uses Zustand
- Server state uses React Query
- UI components use shadcn/ui
- Features are organized inside /features
- Forms use React Hook Form + Zod
Enter fullscreen mode Exit fullscreen mode

This gives Claude immediate understanding of your codebase.

Best Structure for Large Projects

For small apps, one file is enough.

For larger projects, splitting context into multiple files works much better.

Recommended structure:

project-root/
├── CLAUDE.md
└── .claude/
    ├── architecture.md
    ├── stack.md
    ├── conventions.md
    ├── commands.md
    └── product.md
Enter fullscreen mode Exit fullscreen mode

Inside the root CLAUDE.md:

@.claude/architecture.md
@.claude/stack.md
@.claude/conventions.md
@.claude/commands.md
@.claude/product.md
Enter fullscreen mode Exit fullscreen mode

Important detail:

Claude automatically reads only the root CLAUDE.md.

Files inside .claude/ are not auto-loaded unless they are imported from the root file.

Also add .claude/ to .gitignore.

.claude/
Enter fullscreen mode Exit fullscreen mode

What Each File Should Contain

architecture.md

Document:

  • folder structure
  • routing system
  • feature boundaries
  • server/client separation
  • data flow
  • API architecture
  • shared component strategy

Example:

- Features live inside src/features
- Shared UI lives inside src/components
- API clients are inside src/services
- Zustand stores are feature-based
Enter fullscreen mode Exit fullscreen mode

This helps Claude avoid creating random structures.

stack.md

Document every important library and why it exists.

Example:

- Next.js 15 → framework and routing
- React Query → server state management
- Zustand → client state management
- Zod → schema validation
- Tailwind → styling system
- Framer Motion → animations
Enter fullscreen mode Exit fullscreen mode

This prevents Claude from introducing unnecessary alternatives or conflicting patterns.

conventions.md

This file matters a lot.

Document:

  • naming conventions
  • component structure
  • import rules
  • hooks patterns
  • file naming
  • state patterns
  • API handling
  • error handling
  • form patterns
  • UI conventions

Example:

- Components use PascalCase
- Hooks start with use*
- Shared types live in src/types
- Forms use React Hook Form + Zod
- Server actions live inside actions/
Enter fullscreen mode Exit fullscreen mode

This creates much more consistent generated code.

commands.md

Useful project commands:

npm run dev
npm run build
npm run lint
npm run type-check
npm run test
Enter fullscreen mode Exit fullscreen mode

Simple, but extremely useful during long sessions.

product.md

A lot of developers skip this, but it is incredibly useful.

Document:

  • what the product actually does
  • target users
  • business logic
  • important workflows
  • user roles
  • permissions
  • feature behavior

Example:

- Admins can manage products and users
- Customers can only manage their own orders
- Dashboard supports Persian and English
- Mobile experience is prioritized
Enter fullscreen mode Exit fullscreen mode

This helps Claude make smarter product-level decisions, not just code-level decisions.

The Best Prompt for Generating These Files Automatically

At the start of a project, paste this into Claude Code:

Explore this project thoroughly before writing anything:

- Read package.json and all config files
- Scan the full src/ folder
- Identify architecture, routing, state management, API layer, UI patterns
- Analyze 2-3 real components/pages to understand conventions

Then create:

.claude/
├── architecture.md
├── stack.md
├── conventions.md
├── commands.md
└── product.md

For conventions.md include:
- Component library
- Icon usage
- Animation patterns
- Spacing and radius patterns
- Color system
- Layout strategy
- Dark mode implementation

Rules:
- Only document what actually exists
- No assumptions
- No generic advice
- Use concise bullet points

Create CLAUDE.md in the project root importing all files.

Then add .claude/ to .gitignore.

Finally summarize the key architectural decisions found in the project.
Enter fullscreen mode Exit fullscreen mode

This alone can save hours of setup time.

Prompt for Improving Existing UI Conventions

If the files already exist and you only want better UI understanding:

Read .claude/conventions.md first, then inspect the codebase for UI patterns.

- Open existing components
- Analyze forms, buttons, cards, modals
- Check spacing and radius usage
- Inspect Tailwind config and theme files
- Identify icon libraries
- Analyze animation usage

Then add a UI & Design section documenting:
- Component library
- Icon patterns
- Animation patterns
- Spacing conventions
- Radius conventions
- Color system
- Layout strategy
- Dark mode implementation

Only document real patterns found in the codebase.
Enter fullscreen mode Exit fullscreen mode

This improves design consistency significantly.

After the Files Are Generated

One more useful prompt:

Now read the CLAUDE.md you just created and rewrite it to be more professional, concise, and production-ready. Keep only useful information.
Enter fullscreen mode Exit fullscreen mode

This usually removes fluff and improves clarity.

Prompt Quality Still Matters

Good context does not fix vague prompts.

Weak prompt:

Build dashboard
Enter fullscreen mode Exit fullscreen mode

Strong prompt:

Build an admin dashboard with:
- responsive sidebar
- top navbar
- analytics cards
- users table
- loading states
- dark mode support
- Tailwind + TypeScript
Enter fullscreen mode Exit fullscreen mode

More specific prompts produce dramatically better results.

Keep the Context Updated

Your project evolves constantly.

Your AI context should evolve too.

Examples:

  • new feature → update architecture.md
  • new package → update stack.md
  • new repeated pattern → update conventions.md
  • new scripts → update commands.md
  • business logic changes → update product.md

Outdated context creates outdated AI decisions.

When Claude Gets Confused

Long sessions sometimes reduce output quality.

Easy fixes:

Read CLAUDE.md again
Enter fullscreen mode Exit fullscreen mode

Or:

/clear
Enter fullscreen mode Exit fullscreen mode

The chat resets, but your project context still exists through CLAUDE.md.

Important Workflow Rules

A few things improve results a lot:

1. Use a Separate Session Per Project

Avoid mixing unrelated projects inside one chat.

2. Break Large Tasks Into Smaller Steps

Bad approach:

build complete dashboard
Enter fullscreen mode Exit fullscreen mode

Better approach:

  1. build sidebar
  2. confirm structure
  3. build navbar
  4. connect API
  5. add loading states
  6. add animations

Smaller scoped tasks produce cleaner output.

3. Confirm Architecture Before Large Features

Before generating large systems, ask Claude to explain the plan first.

Example:

Before coding, explain the architecture and file structure you plan to create.
Enter fullscreen mode Exit fullscreen mode

This prevents large structural mistakes early.

Claude Memory

Claude can also remember long-term preferences between sessions.

Example:

Remember that I always want TypeScript.
Enter fullscreen mode Exit fullscreen mode

Or:

Remember that my projects use feature-based architecture.
Enter fullscreen mode Exit fullscreen mode

This reduces repetitive setup even more.

The Real Benefit of All This

You stop repeating things like:

  • use TypeScript
  • use App Router
  • use Zustand
  • use shadcn/ui
  • forms use Zod
  • project is RTL
  • features are inside /features

Claude already knows.

That leads to:

  • fewer structural mistakes
  • better architecture decisions
  • cleaner generated code
  • faster iteration
  • less editing
  • more consistent output

The difference becomes massive on large projects.

Final Thoughts

Most developers focus only on writing better prompts.

But prompting alone is not enough for serious AI-assisted development.

The real improvement comes from persistent context engineering.

Good context + clear prompts + updated project memory is what makes Claude Code actually feel professional.

Once you start using CLAUDE.md correctly, it becomes very difficult to go back.

Source

Most of the workflows, patterns, and recommendations in this guide were gathered directly from Claude AI itself, then tested and refined through real-world development usage.

Top comments (0)