CLAUDE.md guide: the global file is an inventory, not rules

What most CLAUDE.md guides get wrong

Claude Code reads ~/.claude/CLAUDE.md at the start of every session, in every directory, on every project — the memory docs call it user instructions, the broadest personal scope there is. The usual advice is to fill it with your preferences and conventions. That reach is exactly the problem: a convention that's right for one project is wrong for the next, and a global file full of conventions quietly biases everything you build toward whatever you built last.

So invert it: the global file is an inventory, not a rulebook. It catalogs what's installed and available — languages, frameworks, CLIs, MCP servers, plugins, skills — section by section, with nothing about when to use any of it, and it opens by disclaiming any authority over decisions. Here are the first lines of a real one:

Read the disclaimer closely, because it's the entire pattern in one breath: "This file is a catalog of what is installed and available globally. It is not a set of rules, defaults, conventions, or guidelines." Two lines later comes the escape hatch — if a project needs something not listed, install it. An inventory informs; it never constrains. Notice also the "Last synced" date in the frame, 2026-06-08: an inventory is a snapshot of a machine, and snapshots need dates.

Build your global CLAUDE.md in ten minutes

1. 01Create the file: touch ~/.claude/CLAUDE.md, then open it in any editor. The ~/.claude directory already exists — Claude Code made it during install.
2. 02Paste the skeleton below. The disclaimer paragraph is the load-bearing part — keep its wording intact and your future projects stay unbiased.
3. 03Let Claude take the inventory. Launch claude from your home directory and paste the audit prompt (the second block below). It checks versions, lists ~/.claude/skills, runs claude mcp list, and writes what it can actually verify under your headings.
4. 04Confirm it loads. In any session, type /memory. Your new file appears in the list of loaded memory files — if it's listed, every future session starts with it.

# Available Inventory

This file is a catalog of what is installed and available globally. It is
**not** a set of rules, defaults, conventions, or guidelines. Nothing in this
file should bias the design, stack, or approach of any project.

Every project is different. Pick whatever the brief calls for. If a project
needs something not listed here, install it.

> _Last synced with the filesystem: YYYY-MM-DD._

## Languages

## Package Managers

## Frontend Frameworks

## Styling

## Animation

## Backends & Infra

## CLIs

## MCP Servers

## Plugins

## Skills

## Hooks

Audit this machine and fill in my global CLAUDE.md inventory at
~/.claude/CLAUDE.md. The section headings and disclaimer are already there —
keep both untouched.

Verify before listing: check node --version, pnpm --version, git --version,
look in ~/.claude/skills and ~/.claude/commands, run claude mcp list for MCP
servers, and check which of these CLIs respond: gh, vercel, supabase, stripe,
shopify.

List only what you can confirm exists — no guesses, no recommendations, no
"you should install" suggestions. Update the Last synced date to today.

Here's what the file buys. A fresh session, no project context, asked a planning question — which animation libraries are available: it answers Lenis, GSAP + ScrollTrigger, Framer Motion, React Three Fiber — the inventory's Animation section, verbatim — then shortlists a pairing and explains why. Nothing was installed, nothing was searched. Claude planned with what you own, which is exactly what a studio does.

Why a catalog and not a rulebook

The counterintuitive part is that global scope is the worst place for your strongest opinions. "Always use Tailwind" is a great line — in a project that uses Tailwind. Loaded globally, it leaks into the Swift experiment, the Liquid theme, the plain-CSS one-pager. Rules belong where they're true, which is the job of the per-project CLAUDE.md — a short file at the project root that commands where this file merely informs.

The test for any candidate line is whether it stays true when you change projects. "Tailwind CSS v4 — installed and available" passes. "Always use Tailwind" fails. "This project uses pnpm only, never npm" belongs in the project file, where it's true. And anything that must hold every single time — a typecheck before every commit — eventually wants to be a hook, not prose.

There's a mechanical reason too. CLAUDE.md content is context, not configuration — the docs are explicit that Claude treats it as instructions to weigh, not settings it enforces. Instructions compete for attention, and every line you load is a line Claude might trade off against another. A catalog sidesteps the fight: lists don't contradict anything, so there's nothing to misweigh. Hard guarantees come from hooks; mechanical defaults belong in settings.json, which is enforced configuration rather than weighed prose.

One honest divergence to flag: the docs target under 200 lines per CLAUDE.md file, and the catalog above runs 329. That's a deliberate, eyes-open trade — the guidance exists because long instructions decay, and a pure catalog skims more like a menu than a contract. A catalog also fails more gracefully when it ages: an out-of-date list omits a tool, while an out-of-date rule actively misdirects. If you ever mix rules in, the 200-line ceiling starts mattering fast.

The full memory hierarchy — managed, user, project, local — plus the @path import syntax lives in the memory docs. The pattern itself compresses to one sentence, and one card deck at the global CLAUDE.md inventory: this file says what exists; the project file says what to use.