The Complete Guide to CLAUDE.md Files

What is CLAUDE.md?

CLAUDE.md is a special markdown file you place in your project root to provide Claude with project-specific context, conventions, and instructions. Think of it as a "README for AI" that helps Claude understand your codebase better.

Why Use CLAUDE.md?

Without CLAUDE.md

❌ Claude makes generic assumptions ❌ May suggest wrong frameworks or patterns ❌ Doesn't know your code style ❌ Unaware of project-specific commands

With CLAUDE.md

✅ Claude understands your architecture ✅ Follows your conventions ✅ Uses correct commands and patterns ✅ Provides context-aware suggestions

Basic Structure

# CLAUDE.md

## Project Overview
Brief description of what your project does

## Technology Stack
List of frameworks, libraries, and tools

## Development Commands
Common commands for running, testing, building

## Architecture
How your code is organized

## Conventions
Your coding standards and patterns

Essential Sections

1. Project Overview

## Project Overview

BAK3R.NET is a Django-based personal hub with:
- Public wiki and contact form
- Private dashboard and file transfer
- Cyberpunk-themed UI

Purpose: Gives Claude immediate context about what you're building.

2. Technology Stack

## Technology Stack

**Backend:**
- Django 4.2.8 (Python 3.9+)
- SQLite database

**Frontend:**
- Pure HTML/CSS (no frameworks)
- Bootstrap Icons
- Highlight.js for syntax highlighting

Purpose: Prevents Claude from suggesting React when you're using vanilla JS, or Flask when you're using Django.

3. Development Commands

## Development Commands

### Initial Setup
\`\`\`bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
\`\`\`

### Running
\`\`\`bash
python manage.py runserver
\`\`\`

### Database
\`\`\`bash
python manage.py makemigrations
python manage.py migrate
\`\`\`

Purpose: Claude can run these exact commands instead of guessing.

4. Architecture

## Architecture

### URL Routing
- `/admin/` - Django admin
- `/` - Public pages (core app)
- `/files/` - File transfer (files app)

### Apps
- **core**: Authentication, wiki, dashboard
- **files**: Secure file upload/download

Purpose: Helps Claude navigate your codebase structure.

5. Conventions and Patterns

## Conventions

### Template Pattern
Avoid Bootstrap grid classes for width control:
\`\`\`html
<!-- Use this -->
<div style="max-width: 500px; margin: 0 auto;">

<!-- Not this -->
<div class="col-md-4">
\`\`\`

### Form Styling
Use `.form-control-cyber` class with:
- width: 100%; box-sizing: border-box;
- Neon cyan borders (#00ffff)

Purpose: Claude follows YOUR patterns, not generic ones.

Advanced Sections

File Organization

## File Structure

\`\`\`
bak3r_site/
├── core/
│   ├── models.py      # Article, Category, Tag
│   ├── views.py       # Public/private views
│   └── middleware.py  # TrafficCounterMiddleware
├── files/
│   ├── models.py      # SecureFile
│   └── views.py       # Upload/download logic
└── templates/
    └── base.html      # ALL CSS lives here
\`\`\`

Security Guidelines

## Security

### Protected Routes
Always use `@login_required` decorator:
\`\`\`python
@login_required
def dashboard(request):
    # Private view
\`\`\`

### File Permissions
- Upload: All authenticated users
- Download: Owner OR is_public=True
- Delete: Owner only

Testing Instructions

## Testing

### Run Tests
\`\`\`bash
python manage.py test
\`\`\`

### Test Data
\`\`\`bash
python manage.py loaddata fixtures/test_data.json
\`\`\`

Real-World Example

Here's a section from BAK3R.NET's CLAUDE.md:

## Template System

**Base Template** (`templates/base.html`):
- Contains ALL CSS styling (no separate CSS files)
- CSS variables for cyberpunk theme
- Conditional navigation based on authentication

**Key Pattern:**
When creating templates, avoid `col-md-4` for width control.
Use: `<div style="max-width: 500px; margin: 0 auto;">`

This tells Claude: 1. Where all CSS lives (not to create separate CSS files) 2. The theming approach (CSS variables) 3. A specific pattern to avoid (Bootstrap columns issue)

Best Practices

1. Update Regularly

## Recent Changes (Updated 2025-03-15)

- Migrated from SQLite to PostgreSQL
- Added Redis caching layer
- Updated to Django 5.0

2. Include Examples

## Database Queries

Preferred pattern for filtering:
\`\`\`python
# Good
articles = Article.objects.filter(
    published=True,
    category__name='AI & Claude'
).select_related('category')

# Avoid
articles = Article.objects.all()
articles = [a for a in articles if a.published]
\`\`\`

3. Document "Why"

## Architecture Decisions

### Why Monolithic CSS?
We keep all CSS in base.html because:
- Single source of truth for theming
- No build process needed
- Easy theme customization
- Project is small enough to manage

4. Link to Resources

## Additional Documentation

- API Docs: `docs/api.md`
- Database Schema: `docs/schema.md`
- Deployment Guide: `docs/deployment.md`

What NOT to Include

❌ Entire codebase - Too much information ❌ Secrets or credentials - Security risk ❌ Auto-generated docs - Claude can read the code ❌ Obvious information - "Python is a programming language"

Testing Your CLAUDE.md

Ask Claude these questions to validate:

"How do I run this project?"
"What's the database migration command?"
"Where should I add a new model?"
"What's the recommended way to style forms?"

Claude's answers should reflect your CLAUDE.md content.

Example Template

# CLAUDE.md

## Project Overview
[What your project does]

## Technology Stack
[Languages, frameworks, tools]

## Development Commands
### Setup
[Installation steps]

### Running
[How to start dev server]

### Testing
[How to run tests]

## Architecture
[How code is organized]

## Conventions
[Your coding standards]

## Common Tasks
### Adding a Model
[Your process]

### Creating a View
[Your pattern]

## Gotchas
[Known issues and workarounds]

Integration with Claude Code

When using Claude Code CLI, it automatically: 1. Reads your CLAUDE.md on startup 2. Uses it to inform all suggestions 3. Follows your documented patterns 4. Executes your specified commands

Conclusion

A well-crafted CLAUDE.md transforms Claude from a generic assistant into a project-specific expert. Invest time in creating one, and you'll get better, more accurate assistance.

Start small, iterate, and expand as your project grows.

This guide itself is an example of the type of documentation Claude can help you create!

Mastering CLAUDE.md - Tailoring AI for Your Project