Testing rules for AI agents

| # Testing Rules for AI Agents | | | ## Intent | | | - Never decide what "correct" means on your own. Ask for the behavior, or work from the scenarios you were given. | | | - Before writing code, propose behavior scenarios — group them as happy path / edge / error / non-goals — and wait for the human to approve, cut, and add to them. | | | ## Writing tests | | | - Test behavior, not implementation. The test should describe what the system does, never how the code is structured inside. | | | - Name the test after the behavior. The body is setup → action → expected result. | | | - A test must be able to fail. Write it first and watch it go red, or temporarily break the implementation to confirm it fails — a test you've never seen fail proves nothing. | | | - Mock only what you don't own (network, clock, filesystem, third-party APIs). Let the real domain code run. | | | - Never write a test that just confirms the current (possibly buggy) behavior. If there's no approved spec, ask before asserting. | | | ## Maintaining tests | | | - When a test fails, read the message and fix the code — don't edit the test to make it pass unless the expected behavior actually changed. | | | - If a refactor breaks a test but the behavior didn't change, the test was wrong — fix the test's coupling, don't chase the implementation. | | | - Keep failures specific: assert on meaningful values and messages, so the next failure says what broke, not just "expected true, got false." | | | ## Structure | | | - Put shared setup behind helpers written in domain language; hide noise, never meaning. | | | - Split tests by feature or behavior. Don't append everything to one giant file. | | | - Match the existing good tests in the repo — they are the template. If none exist, ask the human to seed the first ones. |