
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:
What you only put in chat can get lost.
As a project grows, the conversation gets compacted. Unless you save the decisions somewhere yourself, details can slip out of context.
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 you can have the AI read 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. It's an open Markdown format for project instructions, so the rules you write can travel with the project when you change tools. You don't need a special editor or a complicated template.
That doesn't mean every tool loads every filename in the same way. AGENTS.md, CLAUDE.md, and .cursorrules serve a similar purpose, but they aren't interchangeable names. Check your tool's documentation for the filename and location it reads, and whether any setup is needed. The useful part is keeping your decisions in a file you can carry over, instead of writing them again in every chat.
3. Write the direction yourself
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 before handing it off, you need to decide what you want the rules to say.
The AI doesn't know what you want unless you tell it. Without that direction, it can fill the file with plausible generalities like "keep the code clean." That gives it little help with an actual decision and takes up context along the way.
If you ask for a rules file without setting that direction, you may end up with more to fix later. Getting the direction right at the beginning helps the rest of the work go smoothly. 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:
| Vague | Checkable |
|---|---|
| "Write clean code." | "Keep functions under 50 lines, one screen." |
| "Be careful about security." | "API keys go in .env, never in code." |
| "Make it user-friendly." | "Error messages in Korean, saying what to do next." |
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 accurately, you know it has read them. 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?", you can see the rule affecting its response. Keep checking it during the actual work too.
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? Check that the tool is set up to load that filename too.
- Followed only partly: the rules may be too long or too vague. Make them shorter and checkable.
- Not picked up in a new conversation: add one line to your prompt, "Read AGENTS.md and follow the project rules."
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
- Keep context in files, not in chat. It survives new conversations.
- AGENTS.md is an open format. Carry the rules with your project, and check how your tool loads them.
- Write the direction yourself. Dictate it if typing is a chore.
- Use four blocks: stack, scale, must, must not.
- 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 shows why that single line matters, with real incidents, and finally puts your project on the internet. The requirements.txt from part 1 and GitHub from part 2 come into play then, so get those ready if you haven't yet.
Keep going!
Sources
- AGENTS.md: the open format and examples.
- Codex: Custom instructions with AGENTS.md: how Codex discovers instruction files.
- Claude Code: How Claude remembers your project: instruction filenames and loading behavior.