CLAUDE.md project management is one of the most practical features in Claude Code (the CLI tool). Place a CLAUDE.md file at your project root and Claude Code reads it automatically at the start of every session — no re-explaining your stack, no repeating past decisions.

A previous post covered the basics of MD file-based AI collaboration. This one goes further: structuring a docs/ folder alongside CLAUDE.md, and setting up trigger-based rules that automatically log a change history at the bottom of each document.

What CLAUDE.md Does

The contents of CLAUDE.md become part of Claude's system prompt. Every conversation starts with this context already loaded, eliminating the need to explain basic project information repeatedly.

Claude starts every session with no memory of the last one. It does not know your code style preferences, how to run your tests, or your team's branch naming conventions. CLAUDE.md is the file that fixes this.

Without a CLAUDE.md, Claude makes reasonable guesses about your project. With one, it knows your project exactly and works accordingly. — J.D. Hodges

Starting with /init

Running /init generates a starter CLAUDE.md based on your current project structure. It detects build systems, test frameworks, and code patterns to give you a solid foundation to refine. Treat it as a starting point, not a finished product.

Designing the docs Folder Structure

Cramming everything into a single CLAUDE.md file makes it hard to maintain as the project grows. Splitting by role into a docs/ folder is cleaner and easier to keep current.

project-root/
├── CLAUDE.md            ← master hub (rules + doc references)
└── docs/
    ├── roadmap.md       ← goals, priorities, milestones
    ├── structure.md     ← current file/folder map with descriptions
    ├── decisions.md     ← key decisions and reasoning
    └── context.md       ← tech stack, constraints, background

Keeping each file's scope distinct is what makes the system reliable.

File	Contents	When to Update
roadmap.md	Goals, milestones, priority changes	When direction shifts
structure.md	File structure and descriptions	When files are added or removed
decisions.md	What was decided and why	After any significant choice
context.md	Stack, constraints, background	At setup, occasionally after

You do not need all four from the start. roadmap.md and structure.md alone are enough to begin.

Writing Trigger-Based Update Rules in CLAUDE.md

The real leverage comes from writing rules as condition → action pairs. Vague instructions tend to be ignored. Specific triggers behave consistently.

[code lang="markdown"]

CLAUDE.md

Project Overview

• Stack: Next.js 14, TypeScript, Tailwind CSS
• Dev: npm run dev / Deploy: Vercel
• Docs location: docs/

docs Update Rules

• When a file or folder is added or removed → update the relevant entry in docs/structure.md
• When goals or priorities change → update docs/roadmap.md
• When a technical or architectural decision is made → log it in docs/decisions.md with date, description, and reasoning
• After completing any task → verify that relevant docs reflect the current state

Response Rules

• Always specify language in code blocks
• Include a list of modified files at the end of each task summary
• Ask for clarification rather than guessing when something is uncertain [/code]

Vague vs. Specific Rules

• Vague: "Keep all documents up to date."
• Specific: "Whenever a file is added or removed, update the corresponding entry in docs/structure.md."

The first leaves timing and scope undefined. The second pairs a concrete trigger (file change) with a concrete action (update structure.md), which Claude can follow consistently.

Auto-Logging Change History in Each docs File

To track when and why each document changed, add a changelog section at the bottom of every docs file and include a rule in CLAUDE.md that keeps it updated automatically.

docs File Bottom Section

Add this section to the bottom of each document:

[code lang="markdown"]

Changelog

Date	Change	Trigger
2026-04-08	Initial draft	Project start
[/code]

Add the Changelog Trigger to CLAUDE.md

[code lang="markdown"]

Changelog Rules

• Whenever a docs/ file is modified → append a new row to that file's Changelog table
• Format: | YYYY-MM-DD | one-line summary of the change | what triggered it |
• Fill in the date automatically; if the date is unavailable, write [DATE] rather than asking [/code]

With this in place, saying "added a payments module" is enough. Claude updates structure.md, adds the new entry, and logs a changelog row — all in one step. Months later, searching "when did payments come in?" means opening structure.md and reading the history at the bottom.

What a Populated Changelog Looks Like

[code lang="markdown"]

Changelog

Date	Change	Trigger
2026-04-01	Initial draft	Project start
2026-04-03	Added components/ui folder	ShadcnUI integration
2026-04-07	Added api/payments	Payment module kickoff
2026-04-08	Removed legacy/ folder	Old codebase cleanup done
[/code]

No separate changelog tool needed. Each document carries its own history.

What This Structure Actually Delivers

CLAUDE.md works best when treated as a living document. You do not write perfect code on the first try, and the same applies here — refactor and improve over time. When Claude makes an assumption you want to correct, add it to CLAUDE.md. Real-world issues inform the instructions, and better instructions prevent future issues. A feedback loop forms and the file grows organically from actual use.

In practice, CLAUDE.md project management means:

• No "here's what this project is about" explanation at the start of each session
• Automatic record of why each file was created, in decisions.md
• Claude always operating from the current state of the project, not an outdated memory

Closing

The point of CLAUDE.md project management is not to write more rules — it is to pair specific triggers with specific actions. Structure a docs/ folder by role, add a changelog section to the bottom of each file, and let CLAUDE.md do the bookkeeping. The longer the project runs, the more that upfront investment compounds. Thirty minutes of setup at the start can save you from re-explaining context dozens of times down the road.