If you've been following along with my earlier articles, you already know how powerful Claude Code is as a terminal-based AI coding agent. If you haven't read that piece yet, I'd strongly recommend starting there first — it covers the installation, authentication, and the day-to-day commands you'll use constantly.
Reference: Claude Code: The Terminal AI
Good? Let's move on.
Once you spend a few sessions with Claude Code and start going beyond the basic "fix this bug" type of requests, you'll notice something interesting that Claude starts generating .md files in your project. Or maybe you already know about them and you're wondering what they actually do, why they exist, and whether you should be editing them yourself.
That's exactly what this article is about.
The Elephant in the Room: Why .md Files?
Markdown files feel like documentation. And yes, technically they are. But in the context of Claude Code, these .md files aren't just documentation for humans — they're instructions for Claude itself.
Think of it this way. Every time you open a new Claude Code session, Claude doesn't remember your previous conversations. It's stateless by default. So how does it know your project's coding conventions? How does it know you prefer TypeScript over JavaScript, or that your team always writes unit tests before pushing? How does it know what tools are already installed, or that you're building a microservices architecture with a specific naming pattern?
The answer: .md files. They're Claude's memory, its context, its understanding of who you are, what you're building, and how you want to work.
Once you understand that, the whole picture starts to make sense.
The Most Commonly Used .md Files in Claude Code
Let's go through each one that Claude either generates, reads, or expects to find — and understand the job each one is doing.
1. CLAUDE.md — The Master Instruction File
Location: Project root (/CLAUDE.md) or home directory (~/.claude/CLAUDE.md)
Purpose: This is the single most important .md file in Claude Code's world. Think of it as the first thing Claude reads when it opens your project. It contains project-wide instructions, preferences, and rules that Claude follows for the entire session.
Objective: To give Claude persistent context about your project so you don't have to re-explain things every single session. It's the difference between saying "remember, we always use async/await, not .then() chains" once versus saying it in every conversation.
What goes inside it:
• Tech stack details (language, framework, runtime version)
• Coding style preferences
• Folder structure explanations
• Commands Claude is allowed to run automatically
• Commands that require your explicit confirmation
• Testing conventions
• Environment-specific notes
Scenario: Imagine you're working on a Node.js + Express REST API. Your team follows a specific pattern: controllers in , services in , all errors returned as . Without CLAUDE.md, you'd have to explain this every time. Here's a sample CLAUDE.md:
Now Claude understands your project the moment it opens. You'll notice a huge difference in response quality — it stops suggesting patterns that don't match your setup.
2. README.md — More Than Just Documentation
Location: Project root
Purpose: While README.md is traditionally for humans, Claude Code actively reads it to understand your project's purpose, how to run it, its dependencies, and its overall structure.
Objective: Claude uses your README.md as a source of ground truth about what the project is supposed to do. If your README says "this is a real-time chat application using WebSockets," Claude won't suggest a polling-based architecture when you ask it to build a new feature.
Scenario: You're starting a session and you ask Claude: "I need to add push notifications to this project."
If your README.md documents that you're already using Firebase Cloud Messaging, Claude will correctly pick up that integration point rather than suggesting a brand new notification service from scratch. It reads the README, understands the existing ecosystem, and gives you a suggestion that actually fits.
This is also why a well-written README pays off double — it helps your teammates and it makes Claude smarter about your project.
3. CHANGELOG.md — Claude Writes This So You Don't Have To
Location: Project root
Purpose: Claude Code can generate and maintain a CHANGELOG.md file as it makes changes to your project. When you ask Claude to implement a feature or fix a bug, you can instruct it to append an entry to the changelog automatically.
Objective: Automated, consistent change tracking. Every developer knows changelogs are important and almost nobody keeps them updated manually. Claude changes that.
Scenario: You tell Claude: "Add email validation to the registration endpoint and update the changelog." Claude implements the feature and appends something like this:
This is the kind of thing that used to fall through the cracks. Now it's automatic.
4. SPEC.md — Giving Claude a Blueprint
Location: Project root or /docs folder
Purpose: A file you write (or ask Claude to help you write) that describes what you're building before you start building it. Feature list, user stories, API contracts — whatever level of detail you prefer.
Objective: When Claude has access to a spec file, it stops making assumptions. Instead of filling in the blanks with "sensible defaults," it follows your blueprint. The result is code that matches what you had in mind, not what Claude thought you meant.
Scenario: You're building an e-commerce product listing page. Before writing a single line of code, you ask Claude to help you create a SPEC.md:
Now when you say "build the product listing page," Claude has a contract to work against, not just a vague instruction.
5. TODO.md — Your Living Task List
Location: Project root
Purpose: Claude Code can read and write a TODO.md file to track pending tasks, in-progress work, and completed items across sessions. Since Claude doesn't retain memory between sessions, this file bridges that gap.
Objective: Session continuity. You close your laptop, come back the next morning, and instead of spending five minutes re-explaining where you left off, Claude reads the TODO.md and picks up the thread.
Scenario: End of a Tuesday session. You ask Claude: "Update the TODO with where we left off."
Next morning, you open a new Claude session and say: "Read the TODO.md and continue where we left off." Claude reads the file, picks up the in-progress items, and you're immediately back in context. No catching up. No re-explaining. Just work.
6. ARCHITECTURE.md — The System Map
Location: Project root or /docs
Purpose: A high-level document describing the system design — how different parts of the application connect, what each module is responsible for, data flow, external integrations, and dependencies between services.
Objective: For anything beyond a simple CRUD app, Claude needs to understand how the pieces fit together. Without an architecture doc, Claude might suggest a technically correct solution that completely breaks your service boundaries.
Scenario: You're working on a distributed system with separate services for auth, orders, notifications, and payments. Claude is helping you add a webhook handler for payment confirmations. With ARCHITECTURE.md in place:
Now Claude correctly places the webhook handler in the API Gateway service and publishes the right event type. This is the difference between code review comments and clean merges.
7. SKILL.md — Teaching Claude How to Do Things Your Way
Location: Typically inside a /skills or .claude/skills/ directory
Purpose: A SKILL.md file is a reusable instruction playbook for a specific task. Instead of explaining how to do something every single time — say, how to create a new API controller, scaffold a React component, or set up a database migration — you write it once and Claude follows that exact process every time.
Objective: Standardization and consistency. When you're working on a team project, everyone wants Claude to generate code that looks like it came from the same person. SKILL.md is how you enforce that. It removes the randomness from repeated tasks.
What goes inside it:
• Step-by-step instructions for a specific workflow
• Templates and boilerplate patterns to follow
• File naming conventions specific to the task
• What to check before and after completing the task
• Known pitfalls to avoid for this particular operation
Scenario: Your team has a very specific way of creating new Express route handlers. New devs (and Claude by default) always get it slightly wrong on the first try. You create a SKILL.md:
Now when you tell Claude: "Add a new orders resource to the API," it doesn't improvise. It follows this exact playbook for right file names, right structure, right patterns, every time.
8. HOOK.md — Wiring Claude Into Your Workflow Events
Location: Project root or .claude/ directory
Purpose: HOOK.md defines automated behaviors that Claude should trigger at specific points in your development workflow before a commit, after running tests, when a build fails, when a new file is created. It's Claude's event listener configuration written in plain English.
Objective: To make Claude proactive rather than reactive. Most of the time we use Claude by asking it something that's reactive. Hooks flip that around. Claude watches for something to happen and automatically responds, without you having to ask.
What kinds of hooks can you define:
• Pre-commit hooks (check for console.logs, validate code style, run a quick security scan)
• Post-test hooks (if tests fail, automatically analyze why)
• File-watch hooks (when a new component is created, auto-generate its test file)
• Build hooks (when a build error occurs, automatically diagnose and suggest fixes)
• Custom workflow hooks (whatever makes sense for your specific pipeline)
Scenario: You're tired of accidentally committing console.log statements and commented-out code. You set up a HOOK.md:
The result? Claude becomes your silent co-developer. You write code, it keeps an eye on the guardrails. The pre-commit hook alone will save you embarrassing moments in code review.
What makes this powerful is the combination that use HOOK.md to tell Claude when to act, and SKILL.md to tell Claude how to act. Together they turn Claude Code from a conversational tool into something much closer to an automated development assistant.
9. .claude/ Memory Files — Preferences That Stick
Location: .claude/ folder at project root
Purpose: The .claude/ directory works alongside markdown files. Claude Code stores session-specific memories and settings here. When you tell Claude to "remember" something during a session, it persists that to memory files in this directory.
Objective: Project-level and global-level persistence of Claude's learned context.
Scenario: Mid-session you say: "Always use pnpm instead of npm for this project." Claude stores this preference. Next session, without you saying anything, it will use pnpm for any install commands. Small thing but over weeks of development, these little preferences add up to a noticeably smoother experience.
How Claude Reads These Files: The Priority Order
Here's something worth knowing: Claude doesn't treat all .md files equally. There's a reading priority:
Global ~/.claude/CLAUDE.md — applies to all your projects
Project root CLAUDE.md — applies to everything in the project
Subdirectory CLAUDE.md files — applies to that specific folder and its children
Other .md files — read when referenced or when Claude decides they're relevant to the task
If you have conflicting instructions (global says "use 2 spaces," project says "use tabs"), the more specific file wins a project override global, subdirectory overrides project.
Wrapping Up
These .md files are the closest thing Claude Code has to a persistent brain. Without them, every session starts cold. With them, Claude feels like a developer who actually knows your project — your conventions, your architecture, your preferences, your current tasks.
The investment is small. A few lines in CLAUDE.md when you start a project. A quick SPEC.md before a big feature. A SKILL.md for that one task your team repeats every sprint. A HOOK.md with two or three guards that keep your codebase clean. Letting Claude update a TODO.md at the end of a session. None of it takes more than a few minutes, and the compounding effect over weeks of development is significant.
The developers who get the most out of Claude Code aren't necessarily the ones asking the cleverest prompts. They're the ones who've set up them .md files thoughtfully, so Claude walks into every session already knowing the rules of the game.
Further Reading
Join the conversation! Your thoughts help the community grow.