From 014b28be77d256fdcf5f509be02a4616bee3ab6c Mon Sep 17 00:00:00 2001 From: Michael Chus Date: Fri, 12 Jun 2026 09:41:46 +0300 Subject: [PATCH] Add module atomicity contract to always-on set Co-Authored-By: Claude Fable 5 --- AGENT-BOOTSTRAP.md | 1 + rules/patterns/module-structure/contract.md | 36 +++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 rules/patterns/module-structure/contract.md diff --git a/AGENT-BOOTSTRAP.md b/AGENT-BOOTSTRAP.md index b99ce8a..6534dc4 100644 --- a/AGENT-BOOTSTRAP.md +++ b/AGENT-BOOTSTRAP.md @@ -20,6 +20,7 @@ If you are editing this `bible/` repository itself, read the target contract and Read these on most tasks: - `bible/rules/patterns/kiss/contract.md` +- `bible/rules/patterns/module-structure/contract.md` - `bible/rules/patterns/task-discipline/contract.md` - `bible/rules/patterns/testing-policy/contract.md` - `bible/rules/patterns/secret-management/contract.md` diff --git a/rules/patterns/module-structure/contract.md b/rules/patterns/module-structure/contract.md new file mode 100644 index 0000000..6e614e9 --- /dev/null +++ b/rules/patterns/module-structure/contract.md @@ -0,0 +1,36 @@ +# Contract: Module Atomicity + +Version: 1.0 + +## Principle + +Each file has one clear responsibility. A file that does many unrelated things is a liability, +not a convenience. + +## Rules + +- One concept per file. A file should be nameable in a single noun: `user_validator.go`, + `session_store.go`, `invoice_pdf.go`. If the name requires "and" or "misc", the file is too broad. +- Do not append new functionality to an existing file because it is nearby or already open. + When a new piece of logic does not belong to the existing concept, create a new file. +- A file that grows past ~200 lines is a signal to split, not a mandate — but treat it as a + prompt to ask whether all the code in it shares a single responsibility. +- Package-level `utils.go`, `helpers.go`, or `common.go` files are banned. Name the file after + what the code actually does. + +## Anti-patterns + +- Adding a new handler to `handlers.go` because there is already a handler there. +- Putting unrelated functions in the same file to avoid creating a new one. +- A single file containing models, queries, business logic, and HTTP concerns at once. +- Files named after their location or role in the codebase rather than their concept: + `api.go`, `misc.go`, `util.go`, `shared.go`. + +## When to split + +Split a file when: +1. You cannot describe all of its functions in one short sentence. +2. A new function you are adding does not share the domain of the existing ones. +3. The file has more than one reason to change independently. + +Do not wait until a file is "too big." Split at the moment the second responsibility appears.