What belongs in the brief
Briefs fail by being too long far more often than by being too short. A filter for deciding what earns a line.
The brief is in the context window of every session, costing attention budget every turn. A 400-line brief is not four times as effective as a 100-line one; it is usually less effective, because the important lines are diluted by lines that are merely true.
The filter
1. Would the agent get this wrong without it? no -> cut 2. Is it visible from the code itself? yes -> cut 3. Does it apply to most sessions? no -> move to a skill (5.4) 4. Can a check enforce it instead? yes -> write the check (5.5)
Question 2 removes most of the bloat. An agent reading your code can see that you use TypeScript, that components are functions, that you use Tailwind. Writing those down spends context restating what a single file read would show.
Question 4 is the strongest. A lint rule enforces a convention deterministically, costs zero context, and works when the agent is deep in the dumb zone. Anything expressible as a check should be a check.
Belongs in the brief
- Commands — especially the check command and how to run one test.
- Invisible conventions — rules the code follows that reading one file will not reveal: architectural boundaries, error philosophy, what must never be imported where.
- Danger zones — applied migrations, generated files, the module with the subtle invariant.
- Hard prohibitions — do not add dependencies, do not edit lockfiles, do not touch production config.
- Known inconsistencies — the legacy corner that violates the rules, so the agent does not "fix" it or copy it.
- Pointers — where to find the detail when it is needed.
Does not belong
- Your tech stack. Visible from package.json.
- Style rules a formatter enforces. Let the formatter enforce them.
- General coding advice. "Write clean, maintainable code" changes nothing and costs tokens.
- Task-specific detail. That belongs in the session, or in a ticket.
- Long explanations. The brief is a reference card, not documentation.
- Politeness scaffolding. "You are an expert senior engineer" earns nothing against a modern model.
Write it as rules, not prose
| Weak | Strong |
|---|---|
| "We try to keep the domain layer pure." | "src/domain/ must not import from src/server/ or any framework package." |
| "Be careful with migrations." | "Never edit a file in db/migrations/ that has an entry in schema_migrations. Add a new one." |
| "Prefer good test coverage." | "Every bug fix adds a regression test that fails without the fix." |
Each strong version is checkable, which means you could promote it to a lint rule later and delete the line entirely. That is the direction to push.
Watch out
Briefs grow monotonically because adding a line is easy and deleting one feels risky. Reread yours monthly with the four-question filter and cut. A brief nobody prunes becomes a brief the agent skims.
Try it
Run the filter over every line of your brief. Move anything that fails question 3 into a separate file for later. For the top two lines that fail question 4, actually write the lint rule this week.
Takeaways
- Cut anything visible from the code, enforceable by a check, or applicable to only some sessions.
- Write checkable rules, not aspirations.
- Prune monthly; briefs grow by default.
Why is a lint rule strictly better than a brief line for the same convention?
It costs no context, it applies deterministically regardless of session length, it cannot be forgotten in the dumb zone, and it fails loudly inside the agent’s own feedback loop so it self-corrects without you. The brief line depends on attention; the rule does not.
A course by Pieter Zandbergen