I recently saw a discussion about global memory files for AI coding: after projects add files such as Claude.md or AGENTS.md, the results do not necessarily improve. In some cases, success rates may even drop while reasoning cost rises.

At first, this feels counterintuitive. We usually assume that if we give AI more project background, more rules, and more explanation, it should write code more accurately.
The real issue is that Claude.md is not an ordinary document. It is a global memory file that gets injected into the context on every conversation. The more it contains, the more the model has to read every time; the vaguer it is, the more judgment the model has to make; and if it contains workflows that should not always run, the model may trigger unnecessary actions in unrelated tasks.

So the hard part of writing Claude.md is not making it complete. It is deciding which pieces of information deserve to occupy context permanently.

What Claude.md Is

In AI coding tools, files such as Claude.md and AGENTS.md are essentially global memory files.

Normal conversation enters the context, but context length is limited. Once the conversation becomes long, historical content is compressed and some details are lost. A global memory file fixes important rules in place so the model can see them at the beginning of every task.

This means two things:

• Content written there is harder to forget
• Content written there also costs something on every task

It is not like a README that is read only when needed. It is more like a long-lived set of working constraints. Once something is placed there, it affects the model’s judgment by default.

Therefore, Claude.md is not a project introduction, not a collection of tips, and not a place to dump every development process. It should only store rules that the model is likely to violate repeatedly if it does not know them.

Why It Can Make Things Worse

A poorly written global memory file usually causes three kinds of problems.

First, it consumes context.

If Claude.md has one thousand lines, those lines stay in the model context for a long time. Code, error messages, and requirements that are actually relevant to the current task may get squeezed. Context is not free space. The larger the global rule file, the easier it is to dilute the current task.

Second, it can trigger unnecessary behavior.

For example, a global file might say:

1
2

Before every task, fully read the project directory.
After every change, run a complete end-to-end test.

These lines look responsible, but in a global memory file they become “do this for every task.” Even if the task is only changing one line of copy, the model may perform unnecessary exploration and tests because of these rules. The result is slower work, higher cost, and sometimes more interference.

Third, it increases the burden of judgment.

Statements like “keep code elegant, concise, maintainable, and extensible” sound correct, but they are weak constraints. Every time the model generates code, it has to decide what elegant or extensible means, without receiving a clear boundary.

A better approach is to write concrete prohibitions or counterexamples instead of abstract virtues. For example:

1
2
3

Do not add a generic abstraction for a single call site.
Do not change shared parsing logic without test coverage.
Do not put temporary scripts in the application source directory.

These rules are more specific and easier to follow.

What Should Go In

You can use a simple standard to decide whether something belongs in Claude.md:

If the AI will repeatedly make the same mistake without it, then it is worth writing down.

Content suitable for a global memory file usually has these traits:

• It is durable
• It is strongly tied to the current repository
• It cannot be naturally inferred from the code structure
• It clearly changes model behavior
• It is preferably a constraint, prohibition, path rule, or fixed command

For example:

1
2
3
4

For all Hugo posts, only edit index.zh-cn.md and do not automatically generate other language versions.
Article front matter must include title/date/draft/tags/categories/slug/description.
Do not modify generated artifacts under public/.
On PowerShell, use scripts/deploy.ps1 for deployment.

These are not vague suggestions. They are tied to how the repository actually works. If the model does not know them, it may make mistakes; once it knows them, it can avoid real missteps.

What Should Stay Out

Many people turn Claude.md into a project manual. That is usually unnecessary.

Content that generally does not belong there includes:

• Project vision and background
• Large directory structure descriptions
• Temporary task plans
• One-off debugging steps
• Abstract code quality slogans
• Long workflows that are only needed in a few situations

For example, a description like “this is an e-commerce project with product, order, and user modules” helps very little with a concrete coding task. During real development, the model should rely on the current requirement, specification, code structure, and tests, not on a rough project introduction in global memory.

The same applies to directory structure. Unless a directory has a special convention, such as “shared components must be imported from this directory,” there is no need to write the entire tree into the file. The model can read the project directory itself. A static directory description is easy to become stale.

Workflows Belong in Skills or Commands

If a section says “first do this, then do that, then do the third thing,” it may not belong in Claude.md.

Long-lived workflows can be turned into skills, scripts, or commands. The benefit is that the global memory only needs to keep the name and trigger condition, while the detailed steps are loaded only when needed.

For example:

1
2

When the user asks to translate a Hugo post, use the post-translate skill.
When the user asks to deploy the site, run the hugo-rsync-deploy workflow.

This is lighter than putting the full translation and deployment processes into Claude.md. Global memory stays short, and detailed workflows live in triggerable tools.

Claude’s newer initialization flow is also moving in this direction. It does not only generate a Claude.md; it also tries to split reusable workflows into skills and fixed events into hooks. The underlying idea is clear: global memory should be an entry point, while details should be loaded on demand.

Claude.md Needs Iteration

Claude.md should not be written once and then ignored.

A better approach is to keep it short at first and let real tasks expose problems. If an error happens once, handle it manually. If the same kind of error appears two or more times, it may deserve to become a global rule.

This kind of iteration is more useful than writing a huge set of rules at the beginning. Early on, you do not know which rules are truly useful or which lines will become noise. As the project grows, collaboration increases, and the model’s behavior becomes clearer, you can gradually add the high-frequency problems.

There is also an important trend: the stronger the model, the shorter the global memory file should become.

Many requirements that once had to be written into prompts are now handled naturally by the model. Continuing to put those basic requirements into Claude.md only increases context load. Global memory should shrink as model capability improves, keeping only what is unique to this repository and cannot be inferred automatically.

A More Practical Way to Write It

When writing Claude.md, think in this order:

1. What special conventions does this repository have?
2. Which mistakes has the model made more than once?
3. Which directories, files, or commands must never be misused?
4. Which workflows should become skills, scripts, or commands instead of permanent context?
5. Which parts are merely introductions and can be deleted?

The final file may be only a few dozen lines. It does not need to fully explain the project. It needs to constrain behavior precisely.

A good Claude.md might look like this:

1
2
3
4
5
6
7

# Working Rules

- Only edit files related to the current task.
- Do not modify generated artifact directories such as public/ or resources/.
- Hugo post rewrites only process index.zh-cn.md and do not generate other language versions.
- If deployment is involved, run the Hugo build first, then execute the existing rsync script.
- When there are existing user changes, do not revert them. Continue from the current state.

It is short, but every line affects real behavior. That is the kind of content worth keeping in context permanently.

Final Thought

The value of Claude.md is not to make AI “know more.” It is to make AI “avoid fixed mistakes.”

It is not a knowledge base or project encyclopedia. It is a long-lived constraint file for AI coding.
The more specific, shorter, and closer to real mistakes it is, the more useful it becomes. The more generic, longer, and more like a project introduction it is, the more likely it is to slow the model down or even make results worse.

Treat global memory as a scarce resource, not an unlimited scratchpad. That may be the most important principle for writing a good Claude.md.