{"id":3508,"date":"2026-05-15T01:07:36","date_gmt":"2026-05-15T01:07:36","guid":{"rendered":"https:\/\/aiopsschool.com\/blog\/?p=3508"},"modified":"2026-05-15T01:08:13","modified_gmt":"2026-05-15T01:08:13","slug":"introducing-claude-md-your-projects-memory-for-claude","status":"publish","type":"post","link":"https:\/\/aiopsschool.com\/blog\/introducing-claude-md-your-projects-memory-for-claude\/","title":{"rendered":"Introducing CLAUDE.md \u2014 Your Project’s Memory for Claude"},"content":{"rendered":"\n

What is CLAUDE.md<\/code>?<\/h2>\n\n\n\n

CLAUDE.md<\/code> is a plain markdown file that Claude Code reads automatically every time you start a session. It’s how you give Claude persistent context<\/strong> about your project \u2014 architecture, conventions, commands, gotchas \u2014 so you don’t have to re-explain everything each time you come back.<\/p>\n\n\n\n

Think of it as an onboarding document, but written for Claude instead of a new teammate.<\/p>\n\n\n\n

How Claude Loads It<\/h2>\n\n\n\n

When you run Claude Code from any directory, it walks upward<\/strong> through the folder tree and loads every CLAUDE.md<\/code> it finds. The files stack<\/strong> \u2014 Claude reads all of them together. No manual loading, no special commands.<\/p>\n\n\n\n

That’s why a two-layer setup works so well for multi-repo projects.<\/p>\n\n\n\n

The Two-Layer Setup<\/h2>\n\n\n\n

Layer 1 \u2014 Root CLAUDE.md<\/code> (parent project folder)<\/h3>\n\n\n\n

Lives at the workspace root, above all your repos:<\/p>\n\n\n\n

~\/projects\/my-app\/\n\u251c\u2500\u2500 CLAUDE.md          \u2190 root (shared context)\n\u251c\u2500\u2500 repo-frontend\/\n\u251c\u2500\u2500 repo-backend\/\n\u2514\u2500\u2500 repo-shared-lib\/\n<\/code><\/pre>\n\n\n\n
This file holds cross-cutting context<\/strong> \u2014 things that are true for the whole project, not just one repo.<\/p>\n\n\n\n
Layer 2 \u2014 Per-repo CLAUDE.md<\/code> (inside each service\/repo)<\/h3>\n\n\n\n
Lives inside each repo folder:<\/p>\n\n\n\n
repo-backend\/\n\u251c\u2500\u2500 CLAUDE.md          \u2190 repo-specific context\n\u251c\u2500\u2500 src\/\n\u2514\u2500\u2500 package.json\n<\/code><\/pre>\n\n\n\n
This file holds repo-specific details<\/strong> \u2014 folder layout, local commands, internal patterns unique to that codebase.<\/p>\n\n\n\n
When you work inside repo-backend\/<\/code>, Claude automatically loads both repo-backend\/CLAUDE.md<\/code> and the root CLAUDE.md<\/code>. You get the big picture and the local detail at the same time.<\/p>\n\n\n\n
Rule of Thumb \u2014 What Goes Where<\/h2>\n\n\n\n
Goes in root<\/strong> CLAUDE.md<\/code><\/th>Goes in per-repo<\/strong> CLAUDE.md<\/code><\/th><\/tr><\/thead>
System architecture and how repos relate<\/td>This repo’s folder structure<\/td><\/tr>
Cross-repo workflows (e.g., signup spans 3 services)<\/td>Entry points and main modules<\/td><\/tr>
Shared conventions (commit style, PR rules, branch naming)<\/td>Local build, test, and run commands<\/td><\/tr>
Glossary of domain terms<\/td>Repo-specific gotchas and quirks<\/td><\/tr>
Tech stack overview across repos<\/td>Internal patterns and idioms<\/td><\/tr>
Deployment topology<\/td>Dependencies and external integrations specific to this repo<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Quick test when you’re unsure:<\/strong> if the info is true for more than one repo, lift it to the root. If it only matters when working inside one specific repo, keep it there.<\/p>\n\n\n\n
Getting Started in 3 Steps<\/h2>\n\n\n\n
    \n
  1. Create the root file.<\/strong> From your project root, create CLAUDE.md<\/code> and write a short overview: what the project does, list of repos with one-line descriptions, shared conventions.<\/li>\n\n\n\n
  2. Create per-repo files.<\/strong> Inside each repo, run \/init<\/code> in Claude Code to auto-generate a starter CLAUDE.md<\/code>, then refine it by hand.<\/li>\n\n\n\n
  3. Keep it alive.<\/strong> Treat CLAUDE.md<\/code> like code \u2014 review it in PRs, update it when conventions change, delete stale parts. The more current it is, the better Claude works.<\/li>\n<\/ol>\n\n\n\n
    Tips<\/h2>\n\n\n\n
      \n
    • Keep each file under ~500 lines. Long context files get skimmed, not read carefully.<\/li>\n\n\n\n
    • Commit CLAUDE.md<\/code> to git so the whole team benefits.<\/li>\n\n\n\n
    • For personal or sensitive notes, use CLAUDE.local.md<\/code> (add it to .gitignore<\/code>).<\/li>\n\n\n\n
    • If the same info is repeating across repo files, lift it to the root. If the root is getting bloated with details only one repo cares about, push them down.<\/li>\n<\/ul>\n\n\n\n
      <\/p>\n","protected":false},"excerpt":{"rendered":"
      What is CLAUDE.md? CLAUDE.md is a plain markdown file that Claude Code reads automatically every time you start a session. […]<\/p>\n","protected":false},"author":4,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[916],"tags":[],"class_list":["post-3508","post","type-post","status-publish","format-standard","hentry","category-claude"],"_links":{"self":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/3508","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=3508"}],"version-history":[{"count":1,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/3508\/revisions"}],"predecessor-version":[{"id":3509,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/3508\/revisions\/3509"}],"wp:attachment":[{"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=3508"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=3508"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/aiopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=3508"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}