Writing principles

Writing the advice

principle.md is what the agent reads. It is plain markdown with no header, and three parts the registry reads out of it.

The three parts#

principle.md

# Avoid rxdart

Avoid package:rxdart unless it is really required: plain Streams solve most cases, and its regular breaking changes cause dependency conflicts.

- Avoid package:rxdart unless really required. Most Stream code can be solved without rxdart.
- rxdart is known for its regular breaking changes which often causes dependency conflicts.

Part	Rule	Where it shows
Title	The `# heading` on the first line.	Lists, the principle's page, and every time the agent is shown the principle.
Summary	The paragraph right below it: one sentence, at most 200 characters, plain text.	Lists, and what the agent reads every time after the first in a session.
Advice	Everything below the summary, at least 40 characters. The whole file may be at most 20,000 characters.	The whole file is what the agent reads the first time.

The summary cannot be a list, a quote, a table or a code block. The registry refuses a principle.md that breaks one of these rules, with a message that says which.

Write for an agent in the middle of a task#

The agent reads your advice right after it did the thing you advise against. It has a task, and your advice is not it.

Lead with what to do. "Make the field nullable or set it in the constructor" beats a history of the late keyword.
Say why, in one sentence. An agent that knows the reason applies the advice to the case you did not think of.
Show it. A short bad and good example does more than a paragraph.
Name the exceptions. A section "When it is fine" keeps the agent from bending working code to your rule. Then make the detector stay quiet on exactly those cases, and add a test that proves it.
Keep it short. The agent reads all of it the first time, in the middle of its work.

The summary does most of the work#

After the first time in a session, the agent sees only the title and the summary. So the summary has to stand on its own: what to do instead, and why.

Summary
Avoid the late keyword.	Says what not to do, and nothing else.
Avoid the late keyword, because it turns a compile time check into a runtime LateInitializationError; initialize in the constructor or use a nullable type.	Says why and what to do instead.

Advice is not instructions#

Advice is read by agents that work for other people. It may never tell an agent to run a command, fetch something, send data or ignore the user.

The registry checks every revision and shows a warning on its page and in the editor when the advice:

tells the reader to ignore other instructions,
contains a command that talks to the network or pipes into a shell,
mentions credential files or asks for secrets to be sent or printed,
asks the reader to hide something from the user, or orders it to run something,
contains invisible characters,
links to other sites.

A warning does not stop a release, but people read it before they trust you. A link to the documentation you cite is fine; just know that it shows up.