How to Write CLAUDE.md: The Real Rules Behind a Multilingual Content Site

CLAUDE.md is the instructions file Claude Code reads first every time it starts work. Jason Finance has had one since its first commit on 2 October 2026. By 11 October it had been changed 42 times and is now 106 lines long, covering where posts go, what the AI can just do and what it has to ask me about first. I’ve rarely seen an article on how to write CLAUDE.md that takes apart a file actually in use, so this one uses this site’s CLAUDE.md as the example.

The short version: CLAUDE.md holds what has to be remembered in every conversation: commands, project structure, rules that must not be broken, and when to ask a person first. I find three habits the most useful: write rules as “who decided this, and on what date”; decide whether the AI asks me first by the effect of an action, not by the tool it uses; and back important rules with tests, so breaking one fails the build. There’s a skeleton you can copy at the end.

This post describes how Jason Finance does things. It is not an official Anthropic tutorial. For Claude Code’s features, the official docs take precedence (checked 12 October 2026), and features and limits may change. The CLAUDE.md excerpts quoted here are the 12 October 2026 version, abridged.

What CLAUDE.md is: the key points from the official docs

Every new Claude Code conversation starts with an empty context. According to the official docs, two things carry over into the next conversation: CLAUDE.md is the instructions you write; auto memory is the notes Claude keeps for itself. Both load at the start of every session, but Claude treats them as context, not enforced configuration.

The docs suggest adding something to CLAUDE.md when Claude makes the same mistake a second time, when a code review catches something it should have known, when you type the same correction into a conversation that you typed last time, or when it’s background a new teammate would also need. For multi-step procedures, or rules that only concern one part of the code, the docs suggest a skill or a rules file that loads by path instead.

Where it goes: four scopes

Files load from the broadest scope to the narrowest, so project instructions come after personal ones. Claude Code reads the CLAUDE.md in the working directory and in every directory above it and concatenates them all; none overrides another. A CLAUDE.md in a subdirectory loads only when Claude reads or writes files in that subdirectory.

Importing other files with @

In CLAUDE.md you can write @path to import another file. Relative paths resolve from the file containing the import, and imports nest up to four levels deep. A path wrapped in backticks is just text and is not imported. One thing to note: imported files load at startup along with CLAUDE.md. Splitting into several files makes them easier to manage, but does not reduce the context they take up.

Two other commands you’ll use: /init analyzes the code and generates a starter CLAUDE.md, and /memory lists where all current CLAUDE.md files and auto memory live and lets you open them for editing.

How the docs recommend writing it

• Specific enough to check: write “run npm test before committing”, not “remember to test”.
• Length: aim for under 200 lines per CLAUDE.md; a longer file takes up more context and is followed less reliably.
• Structure: group with Markdown headings and lists, which read better than one big block of text.
• Consistency: when two rules contradict each other, Claude may pick either one, so clear out outdated rules regularly.

The docs also say plainly that to block an action whatever Claude decides, use a PreToolUse hook, not CLAUDE.md. That line shaped how I later turned rules into tests.

What Jason Finance’s CLAUDE.md looks like

Jason Finance is a personal finance content site in four languages. Its posts are Markdown files in GitHub, and the whole architecture is described in Jason Finance from Zero to One. Its CLAUDE.md sits at the repo root and is written in English. I can’t read code; most of the rules in it are decisions I made in Chinese, which Claude Code then organized and wrote in.

The order of these seven sections is deliberate: first tell Claude where to find answers, then the rules, and only then the commands and code structure.

How it’s written, section by section

Authoritative documents: telling Claude where to find answers

The first section only lists documents and what each one governs. The details stay out of CLAUDE.md. Take architecture:

TECH-STACK.md is authoritative for architecture. Do not substitute a different architecture because another approach is more conventional. Proposed changes go to the user first.

The second sentence is written for the AI. An AI will readily replace an existing design because “another approach is more common”, and this line closes that door in advance. Topic taxonomy, article layout and the SEO self-check list are written the same way: one sentence naming the file and its scope, with the content left in that document.

This section has two more practices worth copying:

• A hand-off list: docs/TODO.md is the hand-off list between sessions. Read it at the start of every session. Every conversation starts by reading the to-do list, and anything done, added or changed gets updated, so work carries over from one conversation to the next.
• Importing a document maintained by another project with @: SEO monitoring is a separate project whose working guide is synced to this repo every week. CLAUDE.md imports it with a single line, @seo/CLAUDE-SEO.md, and notes that the file must not be edited here.

Content rules: Git is the CMS, slugs don’t change, one topic per post

Content rules are the longest section of the CLAUDE.md, because the site itself is content. The most basic ones:

Git is the CMS and the source of truth for published content. Posts live in src/content/posts/{slug}/{lang}.md

Slugs are immutable once published. If a slug must change, add a 301 in public/_redirects.

Every article belongs to exactly one pillar (pillar frontmatter). Pillars are the directory names under src/content/pillars/; do not hard-code a second list.

A language version exists only if its Markdown file exists. Never substitute another language.

The last one is specific to a multilingual site. The site has Traditional Chinese, Simplified Chinese and English, with Spanish only for the crypto topic. If a language has no file, that page is not generated, and English does not stand in for it. The translation workflow is also in this section: once I confirm the Traditional Chinese version is final, Claude Code creates the other language versions without asking me again, and translations may not add anything the original doesn’t say.

This section also has a very long rule on “compliance for financial content” that sets out what personal finance and crypto posts can and can’t say. The details are off topic here, so I won’t go into them, but one habit is worth borrowing: for rules like these that carry legal risk, each one has the date I made the decision attached. I’ll explain why below.

Security rules: four technical bottom lines

There are only four security rules, and they’re written rigidly:

No production secrets in Git — no .env, keys, tokens, connection strings or credentials.

Never disable Supabase RLS, not even temporarily as a troubleshooting shortcut. Fix missing data access with policies or grants.

Never introduce service-role credentials into the application. Admin queries run with the signed-in user’s JWT; RLS decides.

/admin* must fail closed (src/middleware.ts).

The second rule specifically says “not even temporarily”. When an AI can’t read some data, the laziest way to debug is to switch off the database’s permission protection (RLS) for a while. This line rules out that shortcut ahead of time and says how the problem should be fixed instead. “Fail closed” in the fourth rule means that whenever anything goes wrong in the admin area, such as no sign-in, a user who isn’t an admin or a database that can’t be reached, access is refused. An error never lets anyone through.

Working agreement: the effect, not the tool

I can’t read commands, so I can’t approve every step the AI runs one by one. The rules therefore start with this:

Approval depends on the effect of an operation, not on the tool that performs it (Bash, SSH, Git, npm, Wrangler/Cloudflare, Supabase, database clients, deployment tooling). Never ask the user to approve command syntax.

Then it splits into tiers:

One more sentence makes the whole system work:

An explicit user request is approval for the routine steps needed to implement it.

When I ask for something, that counts as agreeing to the routine steps needed to finish it. The AI only stops to ask if, partway through, it reaches a consequence I didn’t authorize. In practice these rules really do make the AI stop; I’ve written about how that went in Building a Website Without Reading Code and Running WordPress Without Knowing SSH.

Communication language, commands and code structure

The last three sections are short:

• Communication language: Always communicate with the user in Traditional Chinese. A sentence after it adds that this doesn’t affect the site’s content languages, code, commit messages or file contents. The point is to draw a clear line: talk to me in Chinese, and everything else follows its own conventions.
• Commands: npm test, npm run check, npm run build and npm run verify, one line each, with a note on what each does.
• Code structure: shared logic goes in src/lib/ and must be TypeScript that Node can also run directly; the few kinds of JavaScript public pages are allowed to have are listed one by one.

Four principles for writing CLAUDE.md

Write rules as decisions: who, and on what date

Many rules in this CLAUDE.md end with a note in parentheses, such as (owner decision 2026-10-11) or (standing approval, 2026-10-03). Writing them this way does three things:

• Claude knows it’s a decision I made, not a convention it can “improve” while it’s at it.
• When a rule changes, the old rule can be traced. For example, the rule on the writing polish tool states that it replaces the old tool from 5 October, so Claude doesn’t use both.
• When I look back, I know why I decided what I did, and together with the Git history I can find that day’s changes.

The effect, not the tool

Permissions split by tool, such as “Git is fine, SSH needs my approval”, quickly stop working: the same SSH session can just read logs or can delete production data. Split by effect, the rules don’t have to change every time the tools do. For someone who can’t read commands, it’s also the only judgment I can make: I can understand “which data will be deleted”, but not the command itself.

Turn important rules into tests

The official docs say CLAUDE.md is context, not enforced configuration. Another post, Running Multiple Claude Code Remote Controls on One Server, also notes that rules written only in CLAUDE.md are not access control. So I write the important rules a second time, as code:

Rules grow, so tidy them regularly

Most of the 42 changes added rules. It’s 106 lines now, within the 200 lines the docs recommend, but the single line holding the compliance rules for financial content is over 2,600 characters long, so line count alone doesn’t tell you the length. My way of tidying up is to move the details into dedicated documents under docs/ and leave CLAUDE.md with one sentence and a link. The article layout guide and the SEO self-check list were both split out like that.

A CLAUDE.md template you can copy

Below is a skeleton based on this site’s structure. Replace the paths and commands with your own. Writing the rules in English and having Claude talk to you in Chinese is my habit, not a requirement.

# CLAUDE.md — your-project

## Authoritative documents
- `docs/architecture.md` is authoritative for architecture. Do not substitute
  a different approach because it is more conventional. Proposed changes go to the owner first.
- `docs/TODO.md` is the hand-off list between sessions. Read it at the start of
  every session; update it when an item is done, added or changed.

## Content rules
- Git is the source of truth for published content: `content/{slug}/{lang}.md`.
- Slugs are immutable once published. A rename needs a 301 redirect.
- A language version exists only if its file exists. Never substitute another language.
- <rule> (owner decision YYYY-MM-DD; enforced by `tests/<name>.test.ts`)

## Security rules
- No secrets in Git: no `.env`, keys, tokens or credentials.
- Never disable database row-level security, not even temporarily.
- No admin or service-role keys in the application.
- `/admin*` must fail closed.

## Communication language
- Always reply to the owner in Traditional Chinese. Code, commit messages
  and file contents follow their own conventions.

## Working agreement
Approval depends on the effect of an operation, not on the tool that performs it.
Never ask the owner to approve command syntax.
An explicit request is approval for the routine steps needed to implement it.

### Autonomous
- Reading, searching, tests, builds, normal commits and non-force pushes.

### Tell the owner in plain language
- Content direction, design and layout choices.

### Ask for a decision
- Publishing content the owner has not approved, production settings, DNS,
  payments, anything costly or irreversible. Explain: what changes, why,
  impact, main risk, recommended implementation.

### Never without a decision
- Rewriting Git history, force pushes, destructive operations outside the task.

## Commands
- `npm test`: unit tests
- `npm run build`: production build

## Code layout
- `src/lib/`: shared logic

When you use this skeleton, I suggest writing “Working agreement” and “Security rules” first. Those two sections decide whether the AI does things you didn’t see coming. The other sections can wait until Claude makes the same mistake a second time.

What CLAUDE.md can’t do

• It isn’t access control: Claude may not follow it. For anything that really has to be blocked, use hooks, tests, database permissions, or separate Linux users and credentials.
• It doesn’t update itself: when a rule changes, remember to change the file; old rules left in place will contradict the new ones.
• It can’t hold secrets: CLAUDE.md travels with Git, so keys and passwords belong somewhere outside Git.
• It doesn’t replace judgment: whether to publish, or whether to take on a given risk, is still my call. CLAUDE.md only spells out when Claude should ask me.

For the whole architecture, see Jason Finance from Zero to One; for what each service costs and how permissions are designed, see Building a Website Without Reading Code. More posts are on the AI Startup topic page.

FAQ

What is CLAUDE.md?

CLAUDE.md is a Markdown file for Claude Code to read. It holds a project's long-term instructions, such as build commands, coding conventions, project structure and rules that must always be followed. Claude Code reads it at the start of every new conversation.

Where does CLAUDE.md go?

The official docs list four scopes: a managed policy file for the organization, a personal ~/.claude/CLAUDE.md, a project ./CLAUDE.md or ./.claude/CLAUDE.md at the project root, and a ./CLAUDE.local.md kept out of version control. Project rules go at the repo root, where they are shared with the team through Git.

Can CLAUDE.md reference other files?

Yes, with the @path syntax, for example @docs/git-instructions.md. Relative paths resolve from the file that contains the import, and imports can nest up to four levels deep. Imported files load at startup along with CLAUDE.md, so splitting it into several files does not reduce the context it takes up.

How long should CLAUDE.md be?

The official docs recommend keeping each CLAUDE.md under 200 lines; a longer file takes up more context and is followed less reliably. Jason Finance's CLAUDE.md is 106 lines, but a few of its rules are very long single lines, so line count alone does not tell you its length.

Will Claude always follow the rules in CLAUDE.md?

Not necessarily. The official docs say Claude treats CLAUDE.md as context, not enforced configuration; to block an action no matter what, use a PreToolUse hook. I also write my important rules as tests or data format checks, so breaking them fails the build.

Can someone who can't read code write a CLAUDE.md?

Yes. I can't read code. Most of Jason Finance's rules are decisions I made in Chinese, which Claude Code then organized and wrote into CLAUDE.md. What I write most often is when to ask me, what must never be done and where posts go, none of which requires knowing how to code.