From 86c3c3a6ef85e526e6c2cfeb876be5803bdee2f2 Mon Sep 17 00:00:00 2001 From: Hiroshi Shinaoka Date: Sat, 31 Oct 2026 08:57:19 +0900 Subject: [PATCH] rules: the implementation outranks the documentation Agents follow whatever a document asserts, so a stale paragraph about a removed mechanism is more damaging than a missing paragraph. State the precedence explicitly at the top of the index, and give the operational procedure in the docs rules: verify behaviour against the code, tests and CI; never edit code to satisfy stale prose; fix or file the document with a file:line reference; and retire the describing documents in the same change as the implementation. Recent examples in this organisation: a design note still presented the removed CubeCL backend as the current GPU contract, an architecture page still assigned the primitive AD registry to a crate whose registry has no callers, and a performance guide still described a thread pool API that the caller held engine replaced. --- rules/common/docs-and-tests.md | 23 +++++++++++++++++++++++ rules/index.md | 12 ++++++++++++ 2 files changed, 35 insertions(+) diff --git a/rules/common/docs-and-tests.md b/rules/common/docs-and-tests.md index 6b28220..c16382b 100644 --- a/rules/common/docs-and-tests.md +++ b/rules/common/docs-and-tests.md @@ -17,6 +17,29 @@ still blocked (missing trait or function signatures, how to construct core objects). +## Documentation Is Subordinate To The Implementation + +- The implementation, its tests, and the CI configuration are the source of + truth. A document that disagrees is stale by definition, however specific or + authoritative it reads. +- Never change code to satisfy a stale document. In particular, do not restore a + removed mechanism (an old dependency, a session style API, a feature flag, a + backend, an adapter layer) because a design note still describes it. +- When you find a stale statement, fix it in the same change if it is in scope and + name the code reference you used (`file:line`) in the commit or pull request so + the correction is checkable. If it is out of scope, open an issue with that + reference rather than leaving the prose in place. +- Treat these as high risk and verify them before acting: design documents marked + required reading, architecture pages that assign ownership of a module, and any + text stating which crate or package is the source of truth. Ownership drift in + these pages silently misdirects the next change, including the next agent. +- If you cannot tell which side is current, read the tests and the CI jobs for + that area. If they still disagree, ask before acting; do not assume the document + is right. +- When you delete an implementation, delete or rewrite the documents that describe + it in the same change. A removal that leaves the old description behind will be + reverted by a later agent acting on that description. + ## Examples - User-facing examples verify behavior, not just compile. diff --git a/rules/index.md b/rules/index.md index 2658079..efde256 100644 --- a/rules/index.md +++ b/rules/index.md @@ -1,5 +1,17 @@ # Tensor4all Agent Rules Index +## The Implementation Outranks The Documentation + +The code, its tests, and the CI configuration define current behavior. When a +document, design note, guide, code comment, or bundled skill says something the +code no longer does, the code wins. Read the stale sentence as a defect to report +and fix, never as an instruction to restore what it describes. + +Agents are pulled toward whatever a document asserts, so a confident paragraph +about a removed mechanism does more damage than a missing paragraph. Before you +act on any statement about behavior, confirm it against the implementation. If the +two disagree, do not edit code to satisfy the prose. + Read only the files relevant to the task: common rules first, then the applicable workflow and language rules.