How to Manage Your AI Coding Rule Files
Sorting out a pile of AGENTS.md and CLAUDE.md

Why you end up with a pile of rules files

It's not that you're messy—this convention naturally sprouts a lot of files. Three reasons stack up:

• Each tool reads its own filename: Claude Code tends to read CLAUDE.md, Cursor reads .cursorrules, Copilot reads .github/copilot-instructions.md. Switch tools, and you gain another file.
• One set per project: rules travel with the project, so however many projects you have, that's how many sets you get.
• Temporary files creep in: the one-off plan.md or spec.md an AI generates is also markdown, and piled together it blurs with your standing rules.

So "lots of files" is normal. The goal isn't to merge them into one—it's to keep each in the place it belongs, short enough to read, and free of duplication.

First, get clear on what you have and who owns which

Before organizing, square the accounts. Here are the common ones—always defer to the official docs of the tool you're actually using, since this area changes fast. For what each file is, see What Are AGENTS.md / CLAUDE.md.

Once you've read this table, you can match the pile of .md files on your disk to their owners: which one is for which tool, and where it's meant to live. The ones you can't match, or that sit in the wrong place, are what you'll tidy next.

How to tidy them up: five rules that are enough

No need for an elaborate folder system. Hold to these five, and a pile of rules files won't keep growing into a mess.

The core is one line: keep rules files with the project, never duplicated, short enough to finish reading. If what you want is the more general "how to tidy scattered .md notes," see How to Organize .md Files; this article only targets dev-scenario rules files.

How to be sure the AI read it, so the rules file isn't just for show

Plenty of people write a stack of rules but aren't sure the tool actually followed them. A few practical checkpoints:

• Put it in the right place, with the right filename: a tool only reads it under specific paths and filenames. Defer to the official docs—don't place it on a hunch.
• Keep the content short: rules readable within a screen or two are more likely to be used; hundreds of lines get skipped.
• Write specific, verifiable conventions: "write commit messages in English" or "don't touch that config file" beats a vague "keep the code clean"—and it's easier to check afterward whether the tool followed it.
• It's a suggestion, not a lock: a rules file is a strong suggestion; the tool generally takes it into account but won't necessarily follow every line. Review the important changes yourself.

In the end, "readable" is the prerequisite—rules you can't be bothered to finish reading won't get much care from the tool either. So first you need a way to open these files quickly and read them clearly.

Open these rules files across projects with NoteLoom

Whether these files were generated by an AI or written by you, once they land on your disk they're just local .md files. NoteLoom is an editor that reads and writes local md files right in the browser, which makes it a good fit for opening, reading, and editing these rules files.

Let's be clear about the boundaries up front: NoteLoom has no AI whatsoever, and it doesn't integrate with Claude Code, Codex, Cursor, or git. It won't organize them for you, won't generate or summarize, won't carry out what's in a rules file, and can't make an AI "listen to you better." All it does is let you open these files, read them clearly, edit them, and save them back to your disk.

For the "pile of rules files" problem, two things come in handy:

• Mount multiple folders: bring in several project folders at once and open each project's CLAUDE.md / AGENTS.md from one interface, without hunting through directories in your file system.
• Three views for the same file:

Here's roughly how you use it:

1. Open app.noteloom.cc in Chrome, Edge, or Arc.
2. Mount the local project folders that hold your rules files (NoteLoom has to mount a folder before it can read or write); mount several for several projects.
3. Open a project's CLAUDE.md / AGENTS.md / copilot-instructions.md from the file tree.
4. Use the reading view to read it clearly first; switch to live or source to trim or add.
5. When you're done, it writes straight back to the original local file—no account involved, nothing goes to the cloud.

What a good-enough rules file looks like

The other half of tidying is "don't write it too long." 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:

# CLAUDE.md

## What this project is
A marketing site 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 read clearly to both people and the AI.
• Write specific conventions that are easy to get wrong—those are far more useful than vague principles.
• 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; which rules you set is entirely up to you—NoteLoom won't generate anything for you, it has no AI.

Common pitfalls

• Moving several projects' rules into one folder: tools look in each project's own root, so moving them away means they can't be read. To view them together, just mount the project folders in the editor—don't move the files.
• Writing the same rules across several files: change one and forget the other, and the rules contradict each other. Keep one file per tool, and have the rest point to it.
• Mixing standing rules with one-off plans: move the one-off plan.md out, and keep only the long-lived rules in the rules file. For reading a plan, see How to Read Codex plan.md.
• Letting it grow until no one reads it: a rules file of hundreds of lines is as good as none. Keep the few most important points and re-read to prune the stale ones.
• Expecting NoteLoom to understand or execute it: it won't. NoteLoom only opens, reads, edits, and saves these local files—it doesn't connect to any AI tool and doesn't run the rules inside.