A CLAUDE.md for people who don't code: my template, with blanks for yours

A rules file is a map, not a prompt. It tells the agent which accounts belong to which project, where the keys are and what never happens without asking. A prompt lives for one conversation. The map is read at the start of every session, in every project.

This is my global CLAUDE.md with my accounts, IDs and keys taken out. The structure and the rules stay. Where my data was, there are blanks for yours.

Why I wrote one

Between July 28 and August 1 I explained my GitHub, SSH and Cloudflare setup in four different projects. On the evening of August 1 I complained to the agent: in every new conversation I had to explain again which keys, which GitHub and which Cloudflare go with what.

The agent checked and found the reason. I had no global rules file at all, and only two of the ten folders in my workspace had a CLAUDE.md of their own. By its count, my keys sat in eight places: text files in four projects, environment files in two, a password vault and a CSV file.

Two minutes later it wrote the first version: 56 lines. Three rules from that version have never changed. Keep this file compact. Never print a key. Nothing that costs money without my “yes”.

Before · until August 1

Every new conversation started from zero: which GitHub, which Cloudflare, where the key is. In five days I explained it in four projects.

After

The agent reads the map first. The folder tells it the identity, the identity tells it the accounts, and a key comes from the vault by name and never appears on screen.

Where CLAUDE.md lives

• Global: ~/.claude/CLAUDE.md, in your home folder. Claude Code reads it in every session, in every project. The template is for this file.
• Per project: a CLAUDE.md in the project folder, read on top of the global one. Mine hold a short passport, more on that below.
• After an edit, start a new session so the agent reads the new version.

On a Mac the .claude folder is hidden. In Finder, press Cmd, Shift and the full stop key together to see it. Or ask Claude Code to save the file there for you.

What goes where: a fact the agent needs in every project goes into the global file. A fact about one project goes into that project’s file. A procedure, like launching a site or checking backups, goes into a skill. On August 6 a section on cleaning up access left my file exactly this way and became a skill of its own.

How the file grew

Lines in my global CLAUDE.md, day by day

77 lines at the end of August 1, 132 on August 6, 170 on August 8, 205 on August 18. It stayed at 205 until October 3 and ended that day at 214.

0100200Aug 1: first day, 77 linesAug 6: rules for how to work

Aug 1Sep 1Oct 3

The setup days added accounts and commands. The later jumps each came after a failure:

• August 6: rules for how to work. I had found that I’d set something up in one project and not in another, while sure I had done both. Backups were one example.
• August 7: the protocol for handing over a key, after a token was lost.
• August 8, after midnight: the first progress rule. A long job ran with its output piped through tail, so nothing showed until it finished.
• August 16: the same rule rewritten as “visible to me, not to you”. Two days earlier, background tasks had sat on “No output yet” for nine minutes, and now the panel was empty again.
• August 18: no deletion without a “yes”, after a git history rewrite wiped design files off the disk.

From August 18 to October 3 the file stayed at 205 lines. On October 3 the last rule changed: every text the agent writes for a person now follows my style guide.

What 214 lines hold

What the 214 lines of my CLAUDE.md are about

Keys 86 lines, rules for how to work 74, accounts and projects 28, project standard 13, everything else 13.

Keys: where they live, how a new one arrives 86

How to work: nine rules 74

Accounts and which project uses which 28

Project standard and list of skills 13

Title, language, deploy and money 13

Two fifths of my file sits in the two sections about keys. More than a third of that is an inventory: which account, which Google Cloud project, which old files held keys before the vault. It’s useful to me and to nobody else. The template keeps only the rules: one vault, one naming scheme, never print a value, and how a new key arrives.

When the agent first offered a helper script for keys, my question was whether it was home-made, and whether I could open the vault myself. We settled on a free password manager: an app for me, a command line for the agent. Pick yours by the same test.

A CLAUDE.md example, block by block

Block	What you fill in	Why it's there
Language	The language the agent talks to you in.	Code, commits and docs follow each project's own rules. Replies to you shouldn't depend on the project.
Identities	One row per area of your life: Google account, GitHub, SSH host, hosting account, what it's for.	On my machine the default GitHub address uses my work key. Without the map, nothing stops personal code going out under work credentials.
Projects → identity	Each project folder and the identity it works under.	The agent picks accounts by folder, not by guessing.
Where keys live	Your vault, the naming scheme, the command that reads one key.	Eight places on August 1. Now one vault, and the old files move into it one by one. Values are never printed, not even in a log.
A new key	The name of your inbox file.	A token was saved cut short, an undefined answer was read as success, and the file was deleted. Now: check with a live request, then empty the file and keep it.
How I want work done	Nine rules. Keep mine, change the examples.	Most came after a failure. The longread has the stories.
Project standard	What every project must have: a passport and one backlog.	So nothing is set up in one project and forgotten in the next.
Deploy and money	How your sites go live. What needs your “yes”.	There from day one: no domain and no other purchase without my “yes” and the price in front of me.

One identity, and everything that belongs to it

An identity is not an account. It’s a set: one Google account plus the Cloudflare and GitHub accounts tied to it. My file has four: my job, a client, my content sites and my personal projects. A project works under exactly one of them.

Identity

personal — one area of your life

Google

you@example.com — analytics and Search Console for these sites

Hosting

Cloudflare account “Personal” — domains and sites

GitHub

you-personal — always through its own SSH host, gh-personal

Keys

personal/cloudflare-token, personal/openai — names in the file, values only in the vault

Projects

~/Projects/blog, ~/Projects/shop — each says “personal” in its passport

Don’t know a value yet? Write “to check”. My own map still has “to check” in three cells. A marked gap is better than a guess that looks like a fact.

A passport for every project

Each project folder gets its own short CLAUDE.md. At the top sits a passport: the same questions in every project, so a gap shows at once.

## Project passport (updated YYYY-MM-DD)

- Identity: … | Deploy: …
- Analytics: … | Search Console: …
- Backup: … (restore tested on …)
- Backlog: BACKLOG.md
- Open: … (→ BACKLOG.md)

Two rules: only checked facts go in, and anything unknown says “to check”. A separate skill audits a project against the standard and fills in the passport. It checks ten things: identity, the rules file, the backlog, secrets, analytics, Search Console, backups, deploy, the design system, and monitoring and indexing. My project files run from 12 lines for a small tools site to 258 for the houseplant encyclopedia.

Five questions to check it works

Start a new session in any project folder and ask:

1. “Which identity is this project under, and which GitHub account will you push with?”
2. “Where are my keys, and how will you read one?” The right answer: from the vault, by name, value never shown.
3. “I’ve put a new key in the inbox file. What do you do?” Move it, check it with a live request, empty the file, keep the file.
4. “Delete the old drafts folder.” The right answer is a list of what would go, and a wait for your “yes”.
5. “When is a task done?” When the result is checked on the live page or in real data. Not when the code is written.

A wrong answer means an unclear line. Fix the line, start a new session, ask again.

CLAUDE.md best practices I’d keep

• Start with accounts, not instructions. The map is what saved me the daily re-explaining.
• Write the failure next to the rule. My key protocol ends with “why exactly like this” and the date the token was lost. I now distrust any rule that comes without a story.
• Facts here, procedures in skills, project details in the project.
• Names of keys, never values. Emails and account IDs help the agent, so they can stay in your own file. But the file is a map of your accounts: don’t post it anywhere as it is.
• Keep it short enough to read yourself. The opening lines of my file say “keep it compact”, and the file still grew to 214 lines. The template is 136 once you delete its opening note.