From 97f3f05d0c3c9e330ac9219f74e52bf98f0b6b12 Mon Sep 17 00:00:00 2001 From: Christopher Tso Date: Wed, 15 Apr 2026 00:27:13 +0000 Subject: [PATCH] docs(agents): add self-describing rules for headers and test contracts Add two rules that were missing from existing AI-First Design guidance: - Stale file headers must be updated when module behavior changes - Tests are executable contracts that must reflect behavioral changes Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 404b499e..cf1406ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,6 +61,7 @@ AI agents are the primary users of AgentV—not humans reading docs. Design for - Prefer data-driven patterns (static mappings, config tables) over conditional chains — AI can extend a mapping by adding an entry, but has to trace logic to extend an if/else tree - No dead code or speculative infrastructure; if it's unused, delete it - When a module has an extension point, include a short recipe in the header (e.g., "To add a new provider: 1. Create a matcher, 2. Add it to the mapping") +- When changing a module's behavior, update its file header to match. Stale headers are worse than no headers. **Scope:** Applies to skills, repo structure, documentation, SDK design, and source code — anything AI might need to reason about or extend. @@ -258,6 +259,7 @@ Tests should be lean and focused on what matters. Follow these principles: - **One test per distinct behavior.** Don't write separate tests for trivially different inputs that exercise the same code path. - **No tests for obvious code.** If a function returns `undefined` for missing input and that's a one-line null check, you don't need a test for it unless it's a regression risk. - **Regression tests > comprehensive tests.** A test that would have caught the bug is worth more than five tests that exercise happy paths. +- **Tests are executable contracts.** When a module's behavioral contract changes, the tests must reflect the new contract — not just the happy path. If you change what a function promises, update its tests to assert the new promise. ### Verifying Evaluator Changes