Two different questions
A rules file answers: how do we work in this codebase? A feature spec answers: what are we building right now, and why?
The first is the same for every task and changes a few times a year. The second is different for every feature and changes daily while it is being built. They have different readers, different lifetimes and different review needs, so they should not share a file.
What belongs in the rules file
A rules file is loaded at the start of every session. That is its strength and its cost: every line is read on every task, relevant or not. Put in it what is true for all of them.
- How to run the tests, the linter and the build.
- The layering rules: which module may import which.
- Conventions: naming, error handling, where new code goes.
- What never to do: edit a migration that already shipped, skip a test to get green.
- Where to find things: the schema file, the entry points.
Keep it short and keep it enforceable. A rule that a test or a linter checks is worth ten that rely on the agent remembering.
What belongs in the feature spec
The spec holds what is specific to one feature.
- The goal and the constraints.
- Decisions, and the alternatives you ruled out.
- The design: interfaces, data, states, split into sections.
- The tickets, each with acceptance checks and dependencies.
- Open questions, and the review threads that settled them.
None of this applies to the next feature, and most of it will change before this one ships.
A quick test
For any line you are about to write, ask two questions.
- Will this still be true in six months? If yes, it is probably a convention.
- Does it apply to every task in the repository? If yes, it belongs in the rules file. If it applies to one feature, it belongs in the spec.
| Line | Where |
|---|---|
"Run npm test before committing." | Rules file |
| "Services take the actor as their first argument." | Rules file |
| "Never modify an existing migration." | Rules file |
| "Failed payments retry after 1 minute, 10 minutes and 1 hour." | Feature spec |
"We chose a payment_attempts table over a JSON column, because we query by status." | Feature spec |
| "Ticket T2 depends on T1." | Feature spec |
| "The retry schedule is fixed for now; revisit after rollout." | Feature spec |
What goes wrong when you mix them
Feature details in the rules file. Every agent on every unrelated task loads your checkout retry schedule. The file grows, the important rules get diluted, and the details stay long after the feature shipped. Changing a decision needs a commit and a merge, so the file is always a step behind.
Conventions in the spec. The next feature does not inherit them. Each spec repeats "run the tests first", slightly differently each time.
Plans as loose markdown files. A third pattern: PLAN.md, checkout-notes.md, design-v2-final.md, spread across branches. They are specs without a home. A teammate on another branch does not have them, nobody reviews them, and they pile up.
How the two work together
An agent starts a session and loads the rules file: it now knows how this codebase works. Then it opens the brief for its ticket and the design section behind it: it now knows what to build today. The first is general and stable. The second is specific and current. Neither needs to contain the other.
When a feature produces a lasting rule, move it. If building checkout taught you that every payment call needs an idempotency key, that sentence graduates from the spec to the rules file, and ideally into a test.
Where Tuskway fits
Tuskway is the home for the second kind of document. Each feature gets one spec: notes, a design in sections, and ticket briefs. It lives outside the repository, so it reaches teammates on other branches and in other tools over MCP, and it comes with line comments, suggestions and history. Your AGENTS.md stays in the repository, short and about conventions.
Tuskway's own repository works this way: its AGENTS.md holds layering rules, commands and guarded paths, and each feature's design lives in a Tuskway epic.
Questions
Should I delete my AGENTS.md?
No. Keep it, and keep it short. Move feature plans and stray design notes out of it.
Where do architecture decisions go?
If the decision outlives the feature and applies broadly, record it where your team keeps long-lived documentation and add a one-line rule to the rules file. The discussion that led to it can stay in the feature's spec.
Does this apply to CLAUDE.md and Cursor rules too?
Yes. They play the same role: instructions loaded for every task in the repository.