Helping AI understand your project: context and rules files

As Module 05, Lesson 5 explained, the model itself remembers nothing, and every conversation starts from zero. AI coding tools are the same. Yesterday you spent half an hour explaining "our tests must be run with make test, not pytest directly"; today you open a new conversation and it runs pytest straight away.

The fix is to write these "things you have to explain every time" into a file that the tool reads into its context automatically on every start. This lesson covers how to write that file.

What these files are called

Different tools read different files. As of September 2026, according to each vendor's official docs:

AGENTS.md is an open format, now maintained by the Agentic AI Foundation under the Linux Foundation; its website (agents.md) lists more than twenty tools that support it. Its role is simple: a README is written for people, AGENTS.md is written for AI coding tools.

Claude Code's docs state explicitly that it reads CLAUDE.md, not AGENTS.md. If your project already has an AGENTS.md, the officially recommended approach is to create a CLAUDE.md containing one line, @AGENTS.md, to pull it in, so both kinds of tool read the same content and you don't maintain two copies:

@AGENTS.md

## 只对 Claude Code 生效的补充
改动 src/billing/ 下的代码之前，先进入计划模式。

File names and rules change between versions, so check the latest docs of the tool you use first. The advice below on how to write them applies to all files of this kind.

Where they go, and which wins

These files can usually live at several levels:

• Personal, global: such as ~/.codex/AGENTS.md or ~/.claude/CLAUDE.md, for your own preferences across all projects.
• Project root: committed to git and shared by the whole team.
• Subdirectories: in a large repository, a subproject can have its own file that applies only when working on files in that directory.

When several files exist, the general rule is: the closer to the file being worked on, the higher the priority. In the words of the AGENTS.md website, "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything": the file nearest the edited file applies, and what you say directly in the conversation has the highest priority of all. Codex and Claude Code concatenate the files at each level from the root down to the current directory, with those nearer the current directory later, so later content naturally overrides earlier content.

What to write

Use one question to decide: is this something I'd have to explain to the AI all over again every time?

What's worth including is usually:

How to build, test and check. This is the most important item. After changing code, the AI needs to be able to verify it itself. Give the exact commands:

## 命令
- 安装依赖：`uv sync`
- 运行全部测试：`uv run pytest -q`
- 只跑一个文件：`uv run pytest tests/test_retrieval.py -q`
- 代码检查：`uv run ruff check .`

The project's structure. Which code lives in which directory, where the entry points are. Only what the AI can't tell from the file names.

Rules specific to this project. Places where you depart from common practice are the most worth writing down:

## 约定
- 所有调用大模型的代码都通过 `llm.py` 里的函数，不要直接 new 一个 OpenAI 客户端。
- 价格表在 `llm.PRICES`，改价格只改这一处。
- 用户能看到的文字一律用中文。

Pitfalls you've hit. A mistake the AI made once, written down so it doesn't make it again:

## 注意
- 检索器里调用本地模型必须持有 `_MODEL_LOCK`，多线程同时调用会互相争抢到几乎卡死。
- `data/httpx-docs/` 是第三方文档的副本，不要修改里面的文件。

What not to write

• Things the AI can learn by reading the code. Which files are in a directory, which dependencies are used: it'll look for itself. Writing them in just wastes context.
• Vague principles. "Write high-quality code", "be careful about security": nothing in them can be checked, so writing them achieves nothing.
• Long procedures. A long process needed only for one kind of task doesn't belong in a file read every time. Some tools have dedicated mechanisms for loading things on demand (such as Claude Code's skills and Cursor's conditionally applied rules).
• Secrets. Keys, passwords, internal addresses: never. This file gets committed to git and goes into the model's context.

Claude Code's docs suggest keeping a CLAUDE.md under 200 lines. The reason is straightforward: the whole file is read into the context every time, so the longer it is the more room it takes, and the more rules there are, the harder it is for the model to follow them all.

Be specific to be followed

Compare two ways of writing:

The specific versions have one thing in common: they can be checked. Whether the AI did it is obvious at a glance. With the vague versions, the AI will believe it already has.

Rules mustn't contradict each other. If the root file says "indent with 2 spaces" and a subdirectory's says "4 spaces", the model may pick either. Read these files through regularly and delete anything outdated or conflicting.

A rules file is context, not enforcement

This point is crucial, and the most easily misunderstood.

Claude Code's official docs say it plainly: CLAUDE.md is given to the model as context, and the model tries to follow it, but strict compliance is not guaranteed. It isn't an enforced rule. Write "don't modify .env files" in it, and most of the time the model will comply, but there will always be exceptions.

The experiment in Module 05, Lesson 8 is a good comparison: with security rules spelled out clearly in the prompt, the stronger model still broke them 4 times out of 5. Rules files and prompts are essentially the same thing.

So things that truly must not be touched need to be restricted with the enforcement mechanisms the tool provides, not written in a rules file in the hope the model behaves:

• Permission settings: most tools let you configure which commands and files need your confirmation and which are forbidden outright. For example, Claude Code can take deny rules in its settings, and Codex can use a read-only sandbox or one that writes only inside the workspace.
• Hooks: some tools can run your scripts automatically at specific moments, such as running the formatter after every file edit, or checking whether a command is dangerous before it runs. A hook is the program executing, not the model's judgement.
• git and code review: every change the AI makes goes through a git commit, and you look it over before merging. This is the last, and most reliable, checkpoint.

In one sentence: rules files tell the AI "how to do better"; enforcement mechanisms guarantee "what must never be done".

Start from an empty file

Don't start by writing a big, all-encompassing rules file. A better way:

1. Generate a first draft with the tool's own initialisation command. Claude Code and Codex both have a /init command that analyses your project and writes basics like build commands and directory structure.
2. Delete whatever the AI could learn by reading the code, and add what it can't know: team conventions, pitfalls you've hit.
3. From then on, whenever the AI makes the same mistake a second time, or you catch yourself explaining the same thing in a conversation again, add a line to the file.

Like an evaluation set, a rules file grows little by little through use.

Exercises

1. Write an AGENTS.md (or CLAUDE.md) for one of your own projects, under 50 lines. When you're done, go through it against this lesson's "What not to write" section and cut.
2. Pick a rule you want the AI to follow strictly (such as "never modify the migrations directory"), and find out whether the AI coding tool you use can turn it into an enforced limit rather than just a line in a rules file.
3. Write an AGENTS.md for this course's RepoBot v4. Think about it: what are the few things an AI coding tool opening this project for the first time most needs to know?

Self-check

1. Your project already has an AGENTS.md. How do you get Claude Code to read the same content?

Claude Code reads CLAUDE.md, not AGENTS.md. Per the official docs, create a CLAUDE.md containing the line @AGENTS.md to pull it in, and you can add Claude Code-specific content below that; if you need nothing extra, you can also create a symlink pointing to AGENTS.md.

2. You wrote "don't modify .env files" in the rules file. Is it guaranteed the AI won't?

No. The rules file is given to the model as context; the model tries to follow it, but it isn't guaranteed. Things that truly must not be touched need to be restricted with enforcement mechanisms like the tool's permission settings and hooks, with every change reviewed through git.

3. What is most worth writing in a rules file, and what should never go in it?

Most worth writing is information the AI can't work out itself but needs every time: how to build and test (exact commands), conventions specific to the project, pitfalls you've hit. What shouldn't go in is anything the AI can learn by reading the code, vague principles that can't be checked, and any keys or passwords.