Covers repository structure, architecture, commands, PR requirements and testing. Two of its sections are about the file itself: one instructs the agent to keep it updated, and one records preferences accumulated from previous work.
Quoted passages are verbatim. Open one to see it in the source.
01 / From this file
A section of accumulated corrections
Learned User Preferences records five specific preferences from earlier sessions: use worktrees for parallel work, avoid premature helpers, keep long interaction tests as a readable flow rather than forcing DRY, put story descriptions in JSDoc above the meta const, and keep telemetry string names stable across versions when renaming.
Source excerpt starting at line 417.
417- Keep e2e and long interaction tests as a readable continuous flow; do not force DRY with loops or heavy helpers when repetition is clearer.
02 / Pointing at the source of truth
The file names itself as canonical
Other agent entrypoints are directed to reference this file rather than duplicate it, and the agent is instructed to update it when architecture, commands, versions or release flows change. A Maintenance Rules section states both in full.
Source excerpt starting at line 5.
5This file is the canonical instruction source for coding agents. Files like `CLAUDE.md` should point here instead of duplicating instructions.
03 / Behavioral framing
Principles labelled as observed failure modes
The Code Authoring Principles section is introduced as recurring failure modes in agent-authored changes to this repo, and lists verifying environment assumptions with a throwaway probe before encoding them, preferring static checks over tests, and avoiding coverage already guaranteed by types or linting.
Source excerpt starting at line 389.
389These are recurring failure modes in agent-authored changes to this repo. Apply them when writing or reviewing code, not just when asked.
04 / From this file
An inverted default for component tests
For React components the file directs behavior, accessibility and interaction assertions into stories with play functions, and reserves unit test files for pure utilities, hooks and non-React modules.
05 / Hard prohibitions
A ban on direct global assignment in tests
Assigning a global directly is prohibited, with the mechanism given: Vitest does not restore it, so the assignment leaks into unrelated test files and produces order-dependent flakiness. The replacement API and its cleanup call are both named.
Source excerpt starting at line 321.
321> Under no circumstances may a test mutate a global by assigning it directly (e.g. `globalThis.FEATURES = {...}`, `globalThis.window = ...`, `global.fetch = ...`). Direct assignment leaks across tests and files — Vitest does not restore it — so it silently changes behavior in unrelated tests and creates order-dependent flakiness.
06 / From this file
Commands the agent should not run
Two commands are listed under a Commands To Avoid heading, with the reason that they start long-running development servers, which the file describes as the wrong default for an agent.
Put it to work
Borrow this for your repo
01Keep a section for corrections that came up in review. It is the cheapest way to stop repeating the same feedback.
02Name the commands that start long-running processes and tell the agent not to run them.
03When a test rule exists because of a framework behavior, state the behavior. "Vitest does not restore it" is what makes the rule stick.
04If your repo has several agent entrypoints, name one canonical file and make the rest point at it.
Storybook's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.
