AGENTS.md · git:20260816.fd1d93b · 2026-08-16 · sha256 364ba72e920512ee
AGENTS.md git:20260816.fd1d93bA
Immutable. This exact content never changes and is served at /api/v1/blob/364ba72e920512ee.
# AGENTS.md — claude-code-riper-5
## Git Commit Standards
Format commit messages as:
```
Scope(type[detail]): concise description
why: Explanation of necessity or impact.
what:
- Specific technical changes made
- Focused on a single topic
```
Keep the subject ≤50 chars (excluding any trailing `(#NN)` PR ref); wrap
body lines at ≤72 chars. Separate the `why:` and `what:` blocks with a
blank line.
Common commit types:
- **feat**: New features or enhancements
- **fix**: Bug fixes
- **refactor**: Code restructuring without functional change
- **docs**: Documentation updates
- **chore**: Maintenance (dependencies, tooling, config)
- **test**: Test-related updates
- **style**: Code style and formatting
- **ai(rules[AGENTS])**: AI rule updates
- **ai(claude[rules])**: Claude Code rules (CLAUDE.md)
- **ai(claude[command])**: Claude Code command changes
## Documentation Standards
### Code Blocks
Code blocks are paste-and-run units: pasting one block runs exactly one
intended action. Doctests and other executed examples are exempt — the test
suite runs them, nobody pastes them.
- **One command per block.** Multiple steps may share a block only when
explicitly chained with `&&`, `;`, or `\` continuations — the chain is
then one logical command.
- **Explanations go in prose above the block**, never as `#` comments inside it.
- **Command menus are per-command blocks with prose lead-ins**, not tables.
- **Shell commands use the `console` tag with a `$ ` prefix.** This separates
interactive commands from scripts and enables prompt-aware copy.
- **Split long commands with `\`** — one flag or flag+value pair per indented
continuation line, positional arguments last.
Good:
Show the last ten commits as a graph:
```console
$ git log \
--max-count=10 \
--graph \
--oneline
```
Bad:
```console
# Show the last ten commits as a graph
$ git log --max-count=10 --graph --oneline
```
## Comments earn their maintenance cost
A comment ships only if it passes all three gates. Fail any: delete or rewrite.
Borderline: delete — borderline means the information is reconstructible, which
is what makes deletion cheap.
**Loss.** Three years from now, would losing this cost a maintainer real time
rediscovering intent, an invariant, a constraint, or a failure mode the code and
tests do not already make obvious?
**Elite.** Would SQLite, Redis, the Go standard library, or CPython write this
comment, at this length? Those projects state the constraint and stop. They do
not argue with an imagined objector.
**Upkeep.** Will it stay true without maintenance? A comment that hand-syncs a
value the code owns — a count, an offset, a line reference, a duplicated
constant — is false the first time that value moves.
### Ceiling
One or two lines. A comment reaching four is either carrying several facts, in
which case split it, or arguing, in which case cut it to the fact.
Rationale, alternatives weighed, and the story of how the code got here belong
in the commit message: timestamped, attached to the exact diff, and free to
maintain.
A comment often holds both a constraint and the deliberation that found it. Keep
the constraint, cut the deliberation. "Runs at most once per second" survives;
"this is the right trade for now" does not.
### Keep
- Why over how: upstream quirks, protocol and compatibility constraints,
performance tradeoffs still part of the contract.
- Invariants, preconditions, ordering, lifetime, and concurrency requirements
that types and tests cannot express.
- Code that looks wrong but is not, so a later cleanup does not reintroduce the
bug.
- A high-level sketch of an algorithm whose local operations do not reveal the
whole.
### Delete
- Narration of the next lines; code translated into English.
- Restated names, types, defaults, or control flow.
- Values duplicated from the code and hand-synced.
- Justification, hedging, or apology for a choice.
- Speculation about future requirements.
- History version control already holds, including commented-out code.
- Ticket and issue numbers. They say nothing to a reader without tracker access,
and they rot when the tracker moves. Unfinished work goes in the tracker, not
the source.
- Transient observations — "currently", "for now", "the latest release" —
that go stale with no nearby edit.
### The upkeep gate in practice
It reaches values that track our own code. It does not reach frozen external
facts.
Bad (Delete):
```python
# There are 321 tests to complete for servers.
```
Good (Keep):
```python
# CPython < 3.11 has no ExceptionGroup, so this branch stays.
```
### Documentation exception
Doctests, minimal usage examples, and param, return, and raises lines on public
API are exempt from the loss gate — they serve the caller, not the maintainer.
They are exempt from nothing else. Ceiling: a good man page entry.
## AI Slop Prevention
Treat AI slop as **review-hostile noise**, not as proof that text or
code is wrong. The goal is to maximize information density by removing
artifacts that make the repository harder to trust or navigate.
### The Anti-Slop Rubric
Before committing, audit all AI-assisted changes for these noise
patterns:
- **AI Signatures:** Remove "Generated by", footers, conversational
filler ("Certainly!", "Here is..."), unexplained emojis (🤖, ✨), and
AI-tool metadata.
- **Brittle References:** Avoid hard-coded line numbers, fragile
file/test counts, dated "as of" claims, bare SHAs, and local
absolute paths unless they are strict evidentiary artifacts (e.g.,
benchmark logs).
- **Diff Narration:** Do not restate what moved, was renamed, or was
removed in artifacts the downstream reader holds: code, docstrings,
README, CHANGES, PR descriptions, or release notes. The diff and
commit message already carry this history.
- **Branch-Internal Narrative:** Do not mention intermediate branch
states, abandoned approaches, or "no longer" behavior unless users
of a published release actually experienced the old state (**The
Published-Release Test**).
- **Low-Value Scaffolding:** Remove ownerless TODOs (`TODO: revisit`),
unused future-proofing, debug artifacts, and defensive wrappers that
do not protect a currently reachable failure mode.
- **Prose Inflation:** Replace generic AI "tells" like *comprehensive,
robust, seamless, production-ready, leverage, delve, tapestry,* and
*best practices* with concrete descriptions of behavior,
constraints, or trade-offs.
- **Coded Labels:** Write rules, options, and findings as plain
imperatives. Don't tag them with codes like `[R1]`, `A1`, or
`Option B` in artifacts a human reads — the reader shouldn't have to
decode an index. Internal agent bookkeeping may use ids; shipped text
may not.
### Durable Source Links
Link to a pinned revision, never to trunk. A pinned permalink is not a
brittle reference; an unlinked SHA dropped into prose is. `blob/master/…`
links rot silently — the file moves, lines shift, and the anchor lands
on unrelated code while still resolving.
- Prefer a release tag (`blob/v1.4.0/…`). Most durable, and it tells
the reader which released version the claim held for.
- Otherwise use a 7-char commit ref (`blob/9a29b1a/…`) reachable from
trunk. Use when there is no tag or the claim is about unreleased
code. Never a PR-head SHA — it can be rebased or garbage-collected.
- Reserve `blob/master/…` for living documents meant to always show the
latest state, such as a contributing guide.
- Line anchors (`#L120-L145`) are only safe on a pinned ref.
### Preservation & Context
Subjective cleanup must never remove load-bearing rationale. Adjudicate
comments with the comment policy above; borderline cases are deleted, not
kept.
- **Preserve the "Why":** You MUST NOT delete comments that document
invariants, protocol constraints, platform quirks, security
boundaries, and upstream workarounds.
- **Evidence is Immune:** Preserve exact counts, dates, and SHAs when
they serve as evidence in benchmark results, release notes, stack
traces, or lockfiles.
- **Behavior Over Inventory:** A useful description explains what
changed for the *system or user*; it does not provide an inventory
of files or functions the diff already shows.
### Change Discipline
- Make the smallest coherent change that solves the verified problem;
keep unrelated cleanup out of it.
- Reuse an existing file, component, helper, API, or test before adding
a new one. Modify in place when the change fits the file's
responsibility.
- Keep new APIs private until a caller outside the module needs them.
- Add a file only for a durable boundary — a distinct responsibility,
independent reuse, or splitting an oversized high-touch module — not
for a single-use helper or a one-line re-export.
### Keep Instructions Lean
Treat this file like code and prune it.
- Delete a line whose removal would not cause a mistake.
- Move multi-step procedures into skills, path-specific rules into
nested AGENTS.md files, and hard limits into hooks or CI.
- Keep only non-obvious, broadly applicable defaults here. Anything a
reader can infer from the code, a manifest, or a linter does not
belong.
## Shipped vs. Branch-Internal Narrative
Long-running branches accumulate tactical decisions — renames,
refactors, attempts-then-reverts, intermediate states. Commit messages
and the diff hold *what changed* and *why*. Do not restate either in
artifacts the downstream reader holds: code, docstrings, README,
CHANGES, PR descriptions, release notes, migration guides.
When deciding what counts as branch-internal, use trunk or the parent
branch as the baseline — not intermediate states inside the current
branch.
**The Published-Release Test**
Before adding rename history, "previously" / "formerly" / "no longer
X" phrasing, "removed" / "moved" / "refactored" / "fixed" diff
paraphrases, or `### Fixes` entries to a user-facing surface, ask:
> Did users of the most recently published release ever experience
> this old name, old behavior, or bug?
If the answer is no, it is branch-internal narrative. Move it to the
commit message and describe only the current state in the artifact.
**Keep in shipped artifacts**
- Deprecations and migration guides for symbols that actually shipped.
- `### Fixes` entries for bugs that affected users of a published
release.
- Comments explaining *why the current code looks this way* —
invariants, platform quirks, upstream bug workarounds — that make
sense to a reader who never saw the previous version.
**Default**: when in doubt, keep the artifact clean and put the story
in the commit.
### Cleanup in Hindsight
When applying this rule retroactively from inside a feature branch,
first establish scope by diffing against the parent branch (or trunk)
to identify which commits this branch actually introduced. Then:
- **Commits introduced in this branch** — prompt the user with two
options: `fixup!` commits with `git rebase --autosquash` to address
each causal commit at its source, or a single cleanup commit at
branch tip. User chooses.
- **Commits already in trunk or a parent branch** — default to
leaving them alone. Do not raise them as cleanup candidates; act
only on explicit user instruction. If the user opts in, fold the
cleanup into a single commit at branch tip and do not rewrite trunk
or parent-branch history.
- **Scope guard** — if cleaning in-branch bleed would touch a
colleague's in-flight work or expand the branch beyond its stated
goal, default to staying in lane: protect the project's current
goal, leave prior bleed alone, and don't introduce new bleed in the
current change.