BEPULJANG Blog
Vibe Coding for EveryonePart 3

CLAUDE.md — How AI Understands and Remembers 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: most AIs only know what’s in the current chat session. Once you start a new conversation, or enough time passes, it forgets the rules and structure you established earlier.

CLAUDE.md and other local docs are the most basic and effective way to solve this problem. Claude Code reads these files at the start of every task to understand your project’s current state and rules.

To do this, 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.

Auto-Generating CLAUDE.md with the /init Command

You don’t actually have to write CLAUDE.md by hand from scratch. Claude Code has a dedicated command for it: /init. Whether you’re starting a brand-new project or bringing Claude into one that’s already underway, run Claude Code inside your project folder and enter the command below.

/init

When you run this command, you’ll see Claude Code scan the files in your current folder — package.json, the folder structure, config files, and so on — and automatically draft a CLAUDE.md that fits your project. The basics like tech stack, folder structure, and how to run it get filled in all at once.

That said, don’t just leave the file /init produced as-is. Since Claude Code guessed at the content from reading your code alone, it may differ from your actual intent or miss a rule. /init is only a convenient starting point. You still need to read it over against the “good CLAUDE.md” standards below and refine it — either directly, or by adjusting the specifics through a conversation with Claude Code.

If you run /init again when a CLAUDE.md already exists, it can take the existing content as a basis, re-examine the project fresh, and improve the document.

What to Include in CLAUDE.md

Judging a good CLAUDE.md comes down to one question: is it a document detailed enough for a new team member to understand the project? Generally, it includes the following.

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.

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, Claude Code has no way of knowing which version of React you’re using, how state is managed, or how styling is handled. You could still work with this document, but the odds of mistakes are high — which makes it a risk factor for the project’s stability and maintainability.

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.

It captures the project’s goals and direction, technical specs, structure, deployment, and cautions. Even if you make changes without knowing the project well, the room for misunderstanding shrinks dramatically, and you can reduce or eliminate critical mistakes — raising the stability of your vibe coding project.

Adjust to the Project’s Stage and Nature

If you’re just starting a project and don’t have a structure yet — or it’s a project where you simply can’t fill in every item — it’s fine to describe only what you have ready.

# 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 leaning on too many libraries
- Build frontend-only, with no backend
- Start with HTML, CSS, and vanilla JavaScript

Like this, the size and scope of the document can vary with the project’s nature and stage. What matters is judging whether it’s well-formed as a kind of handoff document — one that helps you understand and remember the project.

Updating CLAUDE.md

CLAUDE.md isn’t a document you write once and forget. You need to update it periodically as the 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 Claude Code keeps making the same mistake (add that mistake as a caution)

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

Summary

CLAUDE.md is the most fundamental file when building a project together with Claude Code. Write it well, and Claude Code 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.