An AI model starts every conversation knowing nothing about you. Not your name, not your language, not that you hate semicolons, not that the tests are run with a Makefile and not npm. It is a very well read stranger. The single highest leverage thing you can do with any AI tool is to fix that, and every tool now has a place to do it: a Markdown file in your repo, a file in your home directory, or a settings box on the web. This post is about those places and what to put in them.
The idea: a standing brief
Think of how you would onboard a contractor. You would not re-explain the codebase every morning. You would write a page: here is how to run things, here is what we care about, here is what not to touch. Instruction files are that page, and the tool reads it silently at the start of every session. The model still starts as a stranger, but a stranger who has read your brief.
Under the hood, the file is simply pasted into the system prompt, the hidden text sent before your first message. That has two consequences worth holding onto. It costs tokens on every turn, so it should be short. And it is instructions, not a database, so it is for things the model must know, not everything it might.
Where each tool looks
| Tool | Project level | Personal, all projects |
|---|---|---|
| Claude Code | CLAUDE.md in the repo root, plus CLAUDE.md in subfolders for that folder only, plus CLAUDE.local.md for private notes that stay out of git | ~/.claude/CLAUDE.md |
| Codex | AGENTS.md in the repo, also read by a growing list of other agents | AGENTS.md in the Codex home folder |
| Cursor | .cursor/rules/ folder of rule files, each can be scoped to file patterns | User rules in settings |
| GitHub Copilot | .github/copilot-instructions.md | Personal instructions in settings |
| ChatGPT | Project instructions inside a Project | Custom instructions in settings, plus memory it collects on its own |
| Claude.ai | Project instructions inside a Project | Personal preferences in profile settings |
| Gemini | Gem instructions | Saved info |
The names differ and the mechanism is identical. The coding tools are converging on reading each other's files, AGENTS.md in particular, so a repo with one good file increasingly works everywhere. Check the tool's docs for the exact current paths, they shift a little each release.
Layering: global, project, folder
The coding tools stack the files. Your personal file loads first, then the project file, then any folder file for the code you are working in. More specific wins on conflicts. This lets you split the brief the way you would split it for a human:
- Global, about you. Language you want replies in. Commit message style. "Never commit unless I say the word commit." "I am learning shell, explain flags instead of just running commands." Your priorities. These follow you into every project.
- Project, about the code. How to build, test and deploy. The folder layout. Conventions the linter does not catch. What is generated and must not be hand edited. Which tool the project is optimising for.
- Folder, about one area. The frontend folder uses a different test runner. The migrations folder has a naming rule. Only loaded when the agent is in there, so it costs nothing otherwise.
Claude Code also lets a file pull in other files with an at sign import, so a CLAUDE.md can say "read docs/conventions.md" instead of duplicating it. And it has a shortcut: start a message with a hash and what you type gets saved into the file, which is how most good instruction files are built, one correction at a time.
What actually belongs in it
Here is a real project file from a small site, lightly edited. It is fourteen lines, and it does most of the work:
# Project notes
This is a free developer tools site. Frontend is in app/, Vite multi page build,
html pages are picked up automatically, no need to register them.
Blog posts are generated. Sources are in app/blog-src/, run npm run blog to
rebuild. Never edit app/blog/*.html by hand.
Deploy uses the makefile in the repo root. Server is Docker plus nginx.
Priorities, in order: paid VS Code extension, ads, affiliate links. When I
suggest something that does not serve those, say so instead of going along.Notice what it is not. It is not a tour of the codebase, the agent can read the code. It is not a style guide, the linter handles that. It is the stuff a new colleague would get wrong in their first week: the generated files, the non obvious build step, the deploy path, and what the owner actually cares about.
A good personal file is even shorter and mostly about taste and boundaries:
Reply in Chinese, keep code and comments in English.
Never run git commit or git push unless I literally ask for it in the
current message. Finishing a task is not permission to commit.
Commit messages: lowercase, casual, no colons or dashes, like a person
typing quickly. Not "Fix: Update the handler to correctly..." but
"fix handler dropping empty payloads".
I have a day job and this is a side project. If a task will not make
money or teach me something, say so.What does not belong in it
- Long documents. Every line is sent every turn. A 3,000 word file is a tax on every message and the model attends to it less, not more. Aim for under a screen. Link out for detail.
- Things the code already says. The agent can read package.json. Tell it what it cannot infer.
- Vague virtues. "Write clean, maintainable code" changes nothing. "Functions under 40 lines, no default exports" changes behaviour.
- Secrets. The project file is usually committed. Keys go in the local, ignored file or nowhere.
- Rules you do not enforce. If you say "always run the tests" and then accept work where it did not, the rule is noise. Keep the rules you check.
The web versions: custom instructions and memory
The chat products have the same feature with a friendlier name. ChatGPT's custom instructions and Claude's personal preferences are a settings box that gets prepended to every conversation. The same rules apply. Things that work well there:
- Who you are in one line, so the answer is pitched right. "Backend developer, ten years, new to machine learning."
- The format you want. "Short answers first, detail only if I ask. No bullet points for prose. Code in fenced blocks."
- What to skip. "No disclaimers about consulting a professional. No restating my question."
- Language and units.
ChatGPT also builds a memory on its own from things you say, and Claude and Gemini have versions of this. It is convenient and it is also a slow leak: months of half remembered preferences accumulate and start steering answers in ways you did not choose. Look at the stored memories every so often and delete the stale ones. A written instruction you control beats an inferred memory you do not.
A workflow that builds a good file
Do not write the file up front. Start with three lines: how to run tests, how to build, one thing you care about. Then use the tool. Every time it does something you did not want, ask whether a sentence in the file would have prevented it. If yes, add the sentence. After a couple of weeks you have a file that is short, specific and entirely made of lessons the tool actually needed. Every few months, read it top to bottom and delete what no longer applies. The best instruction files are maintained like code: small diffs, reviewed, pruned.
The payoff is not just fewer mistakes. A tool that knows your priorities can push back. The last line of that project file, the one about saying so when an idea does not serve the goal, has saved more time than every other line combined. For how the same file also affects your bill, see reducing token use with instructions. For the wider picture of what these agents can and cannot do, start with what changed for developers in 2026.