BEPULJANG Blog
Vibe Coding for EveryonePart 3

How to Write a CLAUDE.md — Helping AI Understand Your Project

Learn how to write a CLAUDE.md file that helps Claude Code remember your project's structure and rules, with good and bad examples.

#Claude Code#CLAUDE.md#Vibe Coding

Once you’ve installed Claude Code, it’s time to actually start building a project. But there’s one problem: Claude Code is incredibly powerful, but it knows nothing about your project. It has no idea what technologies you’re using, how your folders are organized, or what rules you follow.

CLAUDE.md solves this problem. Place it inside your project folder, and Claude Code will automatically read it every time it starts working, so it understands your project’s context. A well-written CLAUDE.md makes a huge difference in the quality of the AI’s work.

Why You Need a CLAUDE.md

When you first start vibe coding, you’ll run into this experience.

At first, Claude Code builds exactly the code you want. But as time passes and the project grows, the AI starts adding code in strange ways — using a different library instead of the one you’d already settled on, ignoring your folder structure conventions, or recreating functions that already exist.

The reason is simple: the AI only knows what’s in the current chat. Once you start a new conversation, or enough time passes, it forgets the rules and structure you established earlier.

CLAUDE.md is the most basic and effective way to solve this problem. Claude Code reads this file at the start of every task to understand your project’s current state and rules.

Where to Put CLAUDE.md

Create a file named CLAUDE.md in your project’s top-level folder (the root directory).

my-project/
  CLAUDE.md       ← put it here
  src/
  package.json
  ...

When Claude Code runs inside your project folder, it automatically finds and reads this file.

What to Include in CLAUDE.md

Think of a good CLAUDE.md as a document you’d hand to a new team member to explain the project. It should contain everything the AI needs to know the first time it looks at your project.

1. Project overview Explain in a sentence or two what kind of service this project is.

2. Tech stack Specify which languages, frameworks, and libraries you’re using. This keeps the AI from reaching for the wrong technology.

3. Folder structure Explain what each major folder is responsible for.

4. How to run it Note how to start the dev server and how to build the project.

5. Important rules and cautions Note coding style, files that must never be touched, and anything that requires special care.

Good CLAUDE.md vs. Bad CLAUDE.md

Let’s compare with real examples.

Bad CLAUDE.md — too short and abstract

# My Project

A website built with React.

With this little information, the AI has no way of knowing which version of React you’re using, how state is managed, or how styling is handled. The more it works, the more it’ll end up picking technologies on its own.

Good CLAUDE.md — specific and practical

# Project Overview

An online book club platform. Users can create clubs, register books, and manage schedules.

## Tech Stack

- Frontend: React 18, Vite, TailwindCSS
- Backend: Node.js 20, Express 4
- Database: PostgreSQL 16
- State management: Zustand (not Redux)

## Folder Structure

```
src/
  components/   shared UI components
  pages/        page-level components
  hooks/        custom hooks
  api/          API call functions
server/
  routes/       API routers
  data/         DB query functions
```

## How to Run

```bash
# Frontend
cd src && npm run dev

# Backend
cd server && npm run dev
```

## Important Rules

- Styling must use TailwindCSS classes only. No inline styles, no adding CSS files.
- API calls must be functions inside `src/api/`. Do not call fetch directly from components.
- We don't use TypeScript. JavaScript only.
- Always ask for confirmation before installing a new package.

With the second example, the AI knows exactly what technology to use and where to create files the moment it starts working.

If You’re Starting a Brand New Project

If you’re just starting a project and don’t have a structure yet, it’s fine to write down just your intent.

# Project Overview

I want to build a cafe menu recommendation web service.
Users pick their mood and the weather, and it recommends a matching drink.

## Technical Direction

- Keep it as simple as possible, without relying on too many libraries.
- I want to build this as frontend-only, with no backend.
- Start with HTML, CSS, and vanilla JavaScript.

Even this much is enough to keep the AI from building an unnecessarily complicated structure.

When to Update CLAUDE.md

CLAUDE.md isn’t a document you write once and forget. You need to update it every time your project changes.

Here are situations that call for an update:

  • When you adopt a new library or framework
  • When your folder structure changes significantly
  • When you establish a new coding rule
  • When the AI keeps making the same mistake (add that mistake as a caution)

That last one matters most. If the AI keeps making the same kind of mistake, it’s a sign that there’s a rule that isn’t spelled out in CLAUDE.md.

Tip: Have the AI Draft Your CLAUDE.md

If your project is already somewhat underway, you can ask Claude Code to draft a CLAUDE.md for you directly.

Look at the current project structure and draft a CLAUDE.md file.
Include the tech stack, folder structure, and how to run it.

The AI reads the files in your current folder and produces a draft. From there, you just need to review it and fill in anything that’s missing.

Summary

CLAUDE.md is the most fundamental file when building a project together with AI. Write it well, and the AI will understand your project’s context and produce consistent code. It’s fine if it’s short — start right now by creating a CLAUDE.md for your project with just the tech stack and key rules.

In the next post, we’ll walk step by step through actually building your first screen together with Claude Code.