# Contract: Module Atomicity Version: 1.1 ## 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. ## Repository Tooling - Keep repository-owned helper programs and scripts under one root `tools/` directory, regardless of language. Do not create parallel `scripts/`, `script/` or `tool/` directories for the same purpose. - Group a tool's supporting code, fixtures and usage notes with that tool; use named subdirectories when several files implement one tool. - Fixed-location integration entry points, such as Git hooks and CI workflow files, stay where their runner requires them. Reusable helper logic belongs in `tools/`. Application source and package-local test fixtures stay with their owning packages. - When moving an existing tool, update callers, CI, documentation and planned paths together. Preserve executable permissions and repository-root resolution. - Generated reports and logs are output artifacts, not tools. Keep them untracked and document their output location. If the operator wants a report beside the standalone script, ignore that report in Git. Credentials and backup data must follow the applicable secrets and backup contracts.