diff --git a/AGENTS.md b/AGENTS.md index 2688faf..e6ebb5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,9 +23,6 @@ the vocabulary — read it before naming a concept in code, a test name, or an i ## Architecture -Behavior detail has no prose home — it lives in the code and its `INVARIANT:`-marked tests. Before -writing prose about a capability, run the admission check in **Where a fact goes** below. - Every module under `faststream_outbox/` is named for what it does; read it. What a single-file read will **not** tell you: @@ -49,38 +46,11 @@ real fetch and worker loops against the fake, which retry, lease-expiry, and sch ## Workflow -Two things outlive the PR, and there are exactly two places to put them: an alternative **rejected** -with reasoning becomes an ADR in [`docs/adr/`](docs/adr/) (`NNNN-slug.md`, sequential), and real work -**not scheduled** becomes a GitHub issue. There is no third state and no truth-home directory — a -behaviour change is reviewed with the diff, not promoted to a page. - -### Where a fact goes - -Four homes, one owner each: - -| Home | Holds | -|---|---| -| `faststream_outbox/` | anything readable from the module — the default | -| a named test | an **invariant**: must stay true, and a change could silently break it | -| `docs/adr/` | a rejected alternative, with the reasoning that would otherwise be re-litigated | -| `docs/` | anything a user needs | - -Before writing a line anywhere: - -> Can an agent get this by reading `faststream_outbox/`? → **don't write it.** -> Would a wrong change here fail a test? → it belongs **in the test**, not in prose. -> Does a user need it? → **`docs/`**. -> Otherwise it does not get written. - -**Prose about mechanism has no home. There is no file to add a paragraph to.** This file included: -it is always loaded, so a line that restates a docstring, a justfile comment, or `pyproject.toml` -costs every turn and rots in two places at once. +Real work **not scheduled** becomes a GitHub issue. An invariant is a test whose name is the claim, with a docstring opening `INVARIANT:` and a second paragraph naming **what breaks it** — design rationale, not a report of what this one test catches; -a sibling test may be the one that trips. `tests/test_invariant_census.py` enforces that shape. Both -ADRs and `INVARIANT:` docstrings ratchet: nothing prunes a record once its call is settled. Keeping -them lean is a standing habit. +a sibling test may be the one that trips. `tests/test_invariant_census.py` enforces that shape. ## Code Style @@ -88,7 +58,7 @@ them lean is a standing habit. catches them; if `# noqa: PLC0415` looks like the fix, hoist the import instead. - Docstrings: public API documents the contract; internal helpers get a one-line contract, plus at most 1–2 lines for a genuinely non-obvious constraint. Never narrate implementation or justify - code to a reviewer — cross-file rationale lives in an `INVARIANT:` test docstring or an ADR. + code to a reviewer — cross-file rationale lives in an `INVARIANT:` test docstring. - Lint suppressions are intentional and carry their reason at the site. The recurring cluster is everything downstream of `BrokerUsecase`'s invariance on its config type.