addy-documentation-and-adrs

An ADR (Architecture Decision Record) captures architectural decisions and rationale to guide future engineers. You need ADR documentation when making architectural choices, changing public APIs, shipping features, or recording context that future agents will need to understand the codebase.

Create ADRs under docs/decisions/ to capture decision rationale, then reference them from AGENTS.md. This enforces ADR documentation, inline guidelines, and project-level references to keep architectural decisions discoverable for future engineers.

Yes, it integrates with existing project guidelines by enforcing ADR documentation, inline documentation guidelines, and project-level references via AGENTS.md. It manages ADR lifecycle and structured addy-README and changelog requirements alongside your current conventions.

The best way to capture engineering context is combining ADRs for decision rationale with AGENTS.md for project-level references. Enforcing inline documentation guidelines and structured addy-README and changelog requirements provides future agents the necessary codebase context.

An AGENTS.md file is needed because it provides project-level references and inline documentation guidelines that make ADRs discoverable. It ensures future engineers and agents can locate and understand architectural decisions, API changes, and shipping rationale.