Agent Working Rules

The Agent Working Rules (working agreement with the agent) are the house rules any AI assistant follows when working with me. They are rules about how to work, not facts about a project.

Communication

• Answer in 1–2 lines, fact first.
• Write summaries as a chain of the facts that decide the outcome.
• Give trade-offs only when asked.
• Say why with every decision or change, in one line.
• Before a large change, state the plan and get my agreement before writing code.

Hardware

• Never flash, reset or touch the bench while I am testing.
• Ask first, every time.
• An imperative is an order to execute, not a topic to discuss.

Git

• Every commit is tested on the device.
• Every push needs my OK.
• No branches the agent made itself, and no worktrees.
• Every commit message says what changed and why, and names the bug it fixes.

Code boundaries

• Never edit shared upstream logic.
• Fix at the config, port or override seam, and keep a drift record of the change.
• Keep the change as small and simple as the problem allows; cut scope instead of adding it.
• Reuse what the project, SDK or a library already provides before writing new code.
• Fix known bugs in the area before adding new features to it.
• Match the existing code: its style, naming, error handling and comment density.
• Do not add input checks to internal calls or comments to every function.

Testing

• Before handing work over, build it and run every test the agent can run without the device.
• Finish the last 5%: check the whole path end to end, not only the part that changed.
• A bug report gives exact steps to reproduce it, what was expected and what happened.
• Only I close a bug or call it fixed, after I have tested it on the device.

Evidence

• Never present a guess as a root cause.
• Take values from documentation, .config or the device tree source (DTS), never by eye.
• Never assume. When a fact is unknown, check it or ask; never start a sentence with "I assumed".

Documents

• Write them as HTML.
• Order: plot, then table, then text.
• Spell out terms in full, with no abbreviations the agent made up.

Source

Some rules are adapted from 如何用正確的方法來寫出品質好的軟體的75條體會 (items 9, 15, 16, 17, 20, 28, 33, 34, 44, 57, 58, 59, 60 and 67).