Stop re-explaining your project: writing an AGENTS.md that works

In the last post, I covered a four-part formula for requests and the habit of reviewing a plan before any code gets written. Try them for a day and one annoyance shows up immediately: every new conversation starts with explaining your project from scratch. The stack, the scale, the things not to touch...

This post is about fixing that with a single file.

1. The one flaw in a good prompt

The formula from last time (purpose, features, constraints, deliverable) works. But it has one flaw:

Anything you only say out loud disappears.

In practice, it looks like this:

• Open a new conversation, and you explain everything again.
• Come back tomorrow, and you explain it again.
• Hand the project to a friend, and they need the whole explanation too.
• Leave something out, and the AI decides for itself.

That last one is the real problem. Last time I said to start a fresh conversation when one goes in circles. But if resetting means a full re-briefing every time, you stop resetting, and you end up clinging to a conversation that's already broken.

The fix is simple: write it down. Then you don't have to repeat yourself, the context survives new conversations, and the AI reads it before it starts planning. Handing the project to a friend becomes a matter of copying one more file.

This approach even has a name: spec-driven development. You pin down what you're building in documents first, and the code follows from them. There are dedicated tools for it now, like GitHub Spec Kit and AWS Kiro, but we don't need to go that far. Two files are enough.

2. AGENTS.md is a standard, not a vendor feature

The file is called AGENTS.md. What matters is that it isn't one company's feature; it's an open format. OpenAI introduced it in August 2025, it has since moved to a foundation under the Linux Foundation, and more than 60,000 open-source projects use it.

That means you can switch tools and keep the file. Claude Code, Codex CLI, and Antigravity all read AGENTS.md, and Claude Code also recognizes its own CLAUDE.md. If you run into CLAUDE.md or .cursorrules in older guides, think of them as earlier names for the same idea. As of 2026, AGENTS.md is the default. (I first assumed I'd need a separate file for every tool. You don't.) Each tool discovers these files a little differently, though, so it's worth checking your tool's documentation once.

3. Don't let the AI write it for you

This is the most important part of the post. It's tempting to just type "write me a rules file." I was tempted too, but the research points the other way.

A 2026 study by Gloaguen and colleagues compared coding agents working with no context file, with one generated by an LLM, and with the file the project's developers had actually written:

• LLM-generated files didn't help. Resolution rates dropped in 5 of 8 settings, by 0.5% and 2% on average across the two benchmarks.
• They made agents work harder. Agents took 2.45 to 3.92 more steps per task, and inference cost rose by 20 to 23%.
• Developer-written files did better. They improved results by about 2.4% on average (not statistically significant on its own) and clearly outperformed the generated files, though they also raised costs by up to 19%.

Put simply:

Why would that be? Honestly, I think it's the result you'd expect. The AI doesn't know what you want, so it writes plausible generalities like "keep the code clean." That isn't a rule; it's noise. It eats up context without helping any real decision. The study's authors land in a similar place: keep the file to instructions an agent can't find elsewhere, such as your project's specific conventions.

(For balance, another 2026 study, by Lulla and colleagues, measured efficiency on repositories that already had an AGENTS.md. With the file in place, agents finished about 20% faster and used about 20% fewer output tokens. The file isn't automatically a cost. What you put in it is what matters.)

So there's one principle: rules are decisions you make, so write them yourself. If you hand the job off without giving any direction, you'll likely spend more time fixing things later. If typing is the obstacle, dictate it with voice input (Google Docs works fine). Just make sure the words are yours.

4. Four blocks: what to write

I write mine in four blocks:

# Project rules

## Stack (do not change)
- Frontend: Vite + React + Tailwind CSS
- Hosting: Vercel
- Database: none yet

## Scale
- About 30 users, fewer than 5 at the same time

## Must
- Never put API keys in code. Use .env.
- Before any large change, show a plan and wait for approval.

## Must not
- Add features nobody asked for (no over-engineering).

Each block prevents a specific kind of accident:

• No stack, and the AI picks different technology every time. React yesterday, Vue today.
• No scale, and you get infrastructure for massive traffic on an app used by thirty people.
• No "must," and keys get hard-coded while code shows up without a plan.
• No "must not," and features you never asked for keep piling up.

The last one matters most. Remember "overreach" from the last post, where you ask for a new button color and the AI rebuilds the whole structure? AI tends to add unrequested extras to look helpful, so you have to rule them out explicitly.

Rules also come in good and bad versions:

The test is simple: if you can see at a glance whether a rule was followed, it's a good rule. There's no way to check "clean," but you can count to 50.

Once the file exists, test it. Open a new conversation and ask, "Read this project's rules and summarize them." If it repeats your rules back, it's working. To be thorough, ask for something on your "must not" list. If it pushes back with something like "the rules say not to do that; are you sure?", your rules are alive.

5. SPEC.md: the constitution and the laws

There's one more file, SPEC.md, and it has a different job:

• AGENTS.md says how to build: the stack and the prohibitions. It rarely changes.
• SPEC.md says what to build: the purpose, the users, the feature list. It changes with every feature.

Think of the rules as the constitution and the spec as the laws passed under it. The section I care about most in SPEC.md is "Not building":

## Features
- [x] Show the shift schedule
- [ ] Automatic scheduling

## Not building
- Payroll calculation
- Message notifications

That list is what keeps the scope from growing forever. I'd guess it's behind most of the side projects that wander off course.

6. When the rules don't stick

If you've written rules and the AI seems to ignore them, check three things:

• Ignored completely: is the file in the project root, and did you open that folder in your tool?
• Followed only partly: the rules are too long or too vague. Make them shorter and checkable.
• Not picked up in a new conversation: add one line to your prompt, "Follow AGENTS.md."

Rules can also live at two levels. Global rules are your personal preferences, like "explain things in Korean" or "show a plan before big changes." Project rules are the conditions of this particular job, like the stack and the scale. Project rules alone are plenty to start with.

Today's five rules

1. Keep context in files, not in chat. It survives new conversations.
2. AGENTS.md is an open standard. It moves with you across tools.
3. Write the rules yourself. AI-written rules can make things worse.
4. Use four blocks: stack, scale, must, must not.
5. A good rule is one you can check at a glance.

You probably wrote "API keys go in .env" into your rules today. The next part of the series (in Korean for now) shows why that single line matters, with real incidents, and finally puts your project on the internet.

Sources

• Gloaguen et al., Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv
  .11988, 2026): the comparison of LLM-generated and developer-written files.
• Lulla et al., On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents (arXiv
  .20404, 2026): the runtime and token measurements.
• AGENTS.md: the format and its adoption.