Guide

How to Write a CLAUDE.md File

The context file that transforms vague AI sessions into focused, productive work.

Skip the manual work — generate a CLAUDE.md from your rough idea in 30 seconds.

What Is a CLAUDE.md File?

A CLAUDE.md file is a project context document that you place in the root of your repository before starting a session with Claude Code (Anthropic's AI coding assistant). It tells the AI everything it needs to know about your project before you write a single line of code.

Think of it as a briefing document. You're not explaining the code — you're explaining the project: the goals, the constraints, the tech stack, the conventions, and the scope. Claude reads it at the start of every session and uses it to stay grounded in your actual project rather than making up its own assumptions.

Without a CLAUDE.md, every AI session starts from zero. The AI makes educated guesses about your tech stack, your naming conventions, your MVP scope. Those guesses are often wrong, and correcting them takes time. With a good CLAUDE.md, you start every session with aligned context.

Why It Matters

The single biggest source of wasted time when using AI coding assistants isn't the AI's capabilities — it's context drift. The AI builds something that mostly matches what you wanted but misses a key constraint, uses the wrong library, or drifts toward features you explicitly didn't want.

A well-written CLAUDE.md prevents this by:

Anchoring scope — explicitly stating what's in and out of MVP
Establishing conventions — naming patterns, folder structure, testing approach
Calling out traps — common AI mistakes to avoid for this specific project
Providing architecture context — decisions already made that the AI shouldn't undo

A CLAUDE.md is not documentation. It's a briefing. Write it for the AI, not for other developers. Assume the reader is capable but has no prior context about your project.

What to Include in a CLAUDE.md

1. Project Overview

2-3 sentences: what it is, who it's for, the core problem it solves. Be specific. "A web app" is not useful. "A browser-only spec generator that takes rough project ideas and outputs PRDs, GitHub tickets, and CLAUDE.md files in 30 seconds" is useful.

2. Tech Stack

List every relevant technology: backend language/framework, frontend framework (or none), database, hosting, any key libraries. Include versions if they matter for behavior (e.g., Flask 3.x vs 2.x).

3. Architecture Decisions

Document the decisions that constrain the implementation. Why SQLite instead of PostgreSQL? Why vanilla JS instead of React? These decisions have reasons, and those reasons often eliminate entire classes of AI suggestions you don't want.

4. Key Files and Their Purpose

A quick map of the codebase. What does app.py contain? What's in templates/? This helps the AI make changes in the right place without asking.

5. Development Commands

How to run the project locally. How to run tests. How to deploy. This prevents the AI from inventing commands that don't work.

6. Naming Conventions

Snake_case vs camelCase? How do you name routes? Components? Database columns? The AI will follow whatever you tell it. If you don't tell it, it will guess.

7. Current MVP Scope

What is in scope for this sprint/session. This is the most important section. Be explicit. "The MVP does NOT include user accounts, saved specs, or team features."

8. What NOT to Do

This section is underused and extremely valuable. List the specific mistakes you want to avoid: don't add TypeScript, don't use ORM patterns, don't introduce new dependencies without asking, don't add authentication. Call out known AI failure modes for your specific project.

A Complete Example

# CLAUDE.md — SpecForge

## Project Overview
SpecForge is a browser-only web tool that converts rough project ideas into structured specs 
(PRD + GitHub tickets + CLAUDE.md) using the Anthropic API. Built for solo developers who 
use Cursor or Claude Code and want to start sessions with real context instead of vague prompts.

## Tech Stack
- Backend: Python 3.11 / Flask 3.x
- Frontend: Vanilla HTML/CSS/JS (no framework)
- Database: SQLite at /data/specforge.db
- AI: Anthropic claude-opus-4-5 via streaming API
- Hosting: Fly.io (Chicago region)

## Architecture Decisions
- No user accounts — all generation is anonymous, tracked by IP hash only
- Streaming response using SSE (Server-Sent Events) — do not refactor to polling
- Single-file backend (app.py) by design — do not split into modules
- SQLite on persistent volume — do not switch to PostgreSQL

## Key Files
- app.py — Flask routes, generation logic, DB operations
- templates/index.html — main UI with inline form and demo
- templates/example.html — static example output page
- fly.toml — Fly.io deployment config

## Development Commands
```
pip install -r requirements.txt
python app.py                    # runs on :8080
flyctl deploy                    # deploy to Fly.io
```

## Conventions
- Route names: lowercase with hyphens (/how-to-write-claude-md)
- DB functions: snake_case, start with verb (get_stats, record_generation)
- Template variables: snake_case
- CSS: no framework, dark theme (#0a0a0a background, #6ee7b7 accent)

## Current MVP Scope
- Anonymous spec generation (idea → PRD + tickets + CLAUDE.md)
- Email capture after generation
- /example page with static DevStreak example
- /how-to-write-claude-md, /cursor-project-planning, /ai-coding-spec-template SEO pages

## Out of Scope (do not add)
- User accounts or authentication
- Saved/persistent specs
- Team features
- TypeScript
- React or any frontend framework
- Any new npm dependencies
- Payment/subscription logic (not yet)

## What NOT to Do
- Do not add session storage or cookies
- Do not add JavaScript frameworks
- Do not refactor app.py into multiple files
- Do not change the streaming implementation
- Do not add database migrations (use CREATE TABLE IF NOT EXISTS)
- Do not add docstrings to every function — only where non-obvious

Common CLAUDE.md Mistakes

Too Short

A two-sentence CLAUDE.md is better than nothing, but it won't prevent scope drift. The sections that matter most are "what not to do" and "current MVP scope." If you skip those, the AI will fill them in with guesses.

Too General

"Use best practices" is not useful context. "Use snake_case for Python identifiers, camelCase for JavaScript variables, and kebab-case for CSS classes" is useful context.

Outdated

A CLAUDE.md that describes last sprint's scope will send the AI in the wrong direction. Update it before each major session. Treat it as living documentation that evolves with the project.

Missing the "What NOT to Do" Section

This is the section that actually prevents AI regressions. Every project has known anti-patterns. Write them down. The AI will thank you (by not introducing them).

How to Generate a CLAUDE.md

You can write a CLAUDE.md by hand using the template above. Or you can use SpecForge to generate one from a rough description in about 30 seconds. SpecForge will also generate a PRD and a set of GitHub-ready tickets at the same time.

The generated CLAUDE.md won't be perfect — no auto-generated document is. But it gives you a solid starting point that covers all the key sections, which you can then refine with your project-specific details.

Paste your rough project idea → get a complete CLAUDE.md + PRD + GitHub tickets in 30 seconds.

Generate My Spec Now →