| name | agent-adrs |
| description | Consult the agent-adrs catalog of engineering decision records before writing code involving time, money, numerics, text encoding, identifiers, validation, errors, observability, concurrency, data storage, caching, networking, APIs, security, configuration, dependencies, testing, files, or i18n. Apply rules per their consensus tier and cite them by id. |
agent-adrs: applying shared decision records
This project follows agent-adrs:
generalized, evidence-backed engineering rules in ADR format.
When to consult
Before writing or reviewing code that touches any covered category (see the
description above). Signals include: datetime construction, currency amounts,
float comparisons, string encoding/length, ID generation, input parsing,
error handling, log statements, shared state, schema/migration changes,
cache logic, outbound network calls, API handlers, secrets, config loading,
dependency additions, test code, file writes, locale-dependent formatting.
How to consult (two layers)
- Index first (cheap): read
index/INDEX.md (or just the relevant
index/<category>.md) from the local clone/submodule, or from
https://raw.githubusercontent.com/gmoigneu/agent-adrs/main/index/INDEX.md.
Each line is id [consensus-tier] rule.
- Full ADR on demand: when a rule is relevant to the change at hand,
fetch
adrs/<category>/<NNNN>-<slug>.md for the Context, Decision,
boundaries, Enforcement pointers, and Exceptions before applying it.
Skip rules whose status is deprecated or superseded. Follow the
superseded_by pointer instead.
Consensus tiers: behavior contract
established: apply by default. Deviate only on explicit project
instruction, and say that you are deviating and why.recommended: apply unless the project signals otherwise (an existing
contrary convention, configuration, or instruction). When not applying,
note the deviation in your response.contested: NEVER auto-apply. Surface the trade-off from the ADR's
Context and ask the user, or follow the project's existing choice.
Citing and excepting
- Cite applied rules by id in explanations and review comments:
agent-adrs/time-0001.
- When code must legitimately violate a rule, add the inline suppression
comment so the exception is visible and greppable:
adr-exception: <id> -- <reason>
- When reviewing diffs, flag violations of
established and recommended
rules that lack a suppression comment.
