What Are AGENTS.md and CLAUDE.md?
The Rules Files You Write for AI Coding Tools

What AGENTS.md and CLAUDE.md actually are

• In one line: standing instructions you write ahead of time for AI coding tools. Every time one gets to work, it reads this file first and follows it.
• Format: plain text plus Markdown syntax, with the .md extension—written the same way as a README.
• Location: by convention it sits in the project's root directory, and the filename is usually all caps (AGENTS.md / CLAUDE.md).
• How it differs from typing in the chat box: what you type in the chat box only applies that one time; rules written into AGENTS.md are "long-term memory" that takes effect every time, so you don't have to repeat yourself.

Why this file is suddenly popping up everywhere

More and more people have been using AI to write code in recent years. Tools like Claude Code, Codex, and Cursor can read your project and edit your files directly, but at first they have no idea about the particulars of your project.

So people realized: instead of repeating "we use TypeScript, write commit messages in English, don't touch that config" at the start of every new conversation, it's better to put it in a fixed file and let the tool read it itself.

That's how AGENTS.md and CLAUDE.md came about. They're not some newly invented, mysterious format—they're just an "I can't be bothered to say it every time, so I'll write it down" memo—the only twist is that the audience is an AI tool rather than a teammate.

Where you'll run into AGENTS.md / CLAUDE.md

Filename cheat sheet: which tool reads which

Different tools recognize slightly different filenames. Here are a few common ones—always defer to the official docs of the tool you're actually using, since this area changes fast.

You don't need to create all of them. Just write the one that matches the tool you use; some tools can also read the general-purpose AGENTS.md.

What's usually inside, and how to read it

Open up an AGENTS.md and the content usually centers on a few areas. You don't have to read it word for word—skim it against the table below and you'll know what the author is laying out.

The trick to reading it: start with "Project overview" to confirm it's what you want, then read "What not to do" to avoid the landmines; save the rest for when you actually start working. It's a reference, not an article you have to read in one sitting.

It's not the same thing as README.md or plan.md

These three files look alike, but they serve different purposes—don't mix them up.

• README.md: the project's manual, mainly for people—what it is, how to install it, how to use it. See What Is README.md for details.
• plan.md: a plan document the AI drew up and generated for you on a particular occasion, recording "how this task is going to be done." See How to Read Codex plan.md for how to read it.
• AGENTS.md / CLAUDE.md: the standing rules you write for AI coding tools, read before every task to constrain how they work.

The simple split: README is for people, plan is a one-off plan, and AGENTS.md is the rules that stay in effect for the long term.

Open your local AGENTS.md with NoteLoom

Whether this file was generated by an AI or you're writing it yourself, once it lands on your disk it's just a local .md file. NoteLoom is an editor that reads and writes local md files right in the browser, which makes it a good fit for opening AGENTS.md.

Let's be clear about the boundaries up front: NoteLoom has no AI whatsoever, and it doesn't integrate with Claude Code, Codex, or Cursor. It won't write rules for you, won't summarize, won't understand your project, and certainly won't carry out what's in AGENTS.md. All it does is let you open this file, read it clearly, edit it, and save it back to your disk.

It gives you three views for reading the same file:

Here's roughly how you use it:

1. Open app.noteloom.cc in Chrome, Edge, or Arc.
2. Select the local folder that contains AGENTS.md (NoteLoom has to mount a folder before it can read or write).
3. Open AGENTS.md or CLAUDE.md from the file tree.
4. Use the reading view to see the formatting first; switch to live or source when you want to edit.
5. When you're done, it writes straight back to the original local file—no account involved, nothing goes to the cloud.

How to write AGENTS.md: a good-enough example

No need to overcomplicate it. A first version that clearly covers "what the project is, how to run it, and what not to touch" is plenty. Here's what good-enough looks like:

# AGENTS.md

## What this project is
A personal blog written in Astro, deployed on Cloudflare Pages.

## How to run it
- Install dependencies: npm install
- Local preview: npm run dev
- Build: npm run build

## Rules to follow when writing code
- Use TypeScript, don't use any
- Put components in src/components/, one component per file
- Write commit messages in English, one line that clearly says what changed

## What not to do
- Don't change the deployment config in src/config.ts
- Don't write secrets into the code

A few key points:

• Use plain language, don't pile on jargon. It should be something both people and the AI can understand.
• Write down specific conventions that are easy to get wrong, like "write commit messages in English" or "don't touch that config file"—these are far more useful than a vague "keep the code clean."
• Keep it short—ideally readable within a screen or two; if it's too long, both the AI and you will tend to skip it.
• To get symbols like #, -, and code blocks right, see How to Write Markdown.

While writing, just use the live view to type and watch the formatting at the same time; what you type and which rules you set are entirely up to you—NoteLoom won't generate anything for you, it has no AI.

Common pitfalls

• Opening it in Notepad shows a pile of # and -: that's just unrendered text, not a broken file. Switch to an editor that can display Markdown formatting and it'll look fine.
• Assuming only programmers need to deal with it: you'll run into it even if you don't write code—ask an AI to build a little tool or organize a project for you, and it may create one. Just read it as a project briefing.
• Writing it too long and exhaustive: a rules file that runs hundreds of lines is one neither the AI nor you will bother reading. Write down just the few most important, most error-prone points.
• Assuming the tool will follow it strictly: AGENTS.md is a "strong suggestion," not a hard lock. The AI will generally take it into account, but there's no guarantee it follows every line, so review the important changes yourself.
• Expecting NoteLoom to understand or execute it for you: it won't. NoteLoom only opens, reads, edits, and saves this local file—it doesn't connect to any AI tool and doesn't run the rules inside.