31. Note Exceptions
31. Note Exceptions
Section titled “31. Note Exceptions”Date: 2025-04-24
Status
Section titled “Status”Accepted
Context
Section titled “Context”While ADRs (Architecture Decision Records) and DDRs (Design Decision Records) establish standards and best practices, there are situations where specific parts of the codebase must intentionally deviate from these decisions. These exceptions are often necessary due to integration requirements, performance constraints, or legacy compatibility.
Decision
Section titled “Decision”To ensure intentional deviations from ADRs or DDRs are clearly documented and do not get “fixed” by well-meaning engineers or automated tools, we will adopt a standardized marker for these cases:
ADR Exception Marker: // ADR_EXCEPTION: [ADR-###] — reason
DDR Exception Marker: // DDR_EXCEPTION: [DDR-###] — reason
Where:
ADR-### or DDR-### references the corresponding decision record number.
The reason provides a short explanation for the exception (e.g., legacy integration, external API constraint, performance optimization).
Example:
// ADR_EXCEPTION: ADR-007 — This import uses ~ due to Plasmo compatibility even though @ is preferred.
import Something from ’~/core/utils’;
Consequences
Section titled “Consequences”These markers must be included wherever the code violates an ADR or DDR intentionally.
During code reviews or automated checks, violations without such exceptions should be flagged and remediated.
Exceptions with these tags are considered acceptable and intentional — they are not to be modified unless the associated ADR/DDR is updated or a new ADR/DDR is written to supersede it.
Next Steps:
Update linters or review bots to recognize these markers and allow exceptions only when properly tagged.
Educate the team on how to use this tagging system.
Consider tooling that can generate reports of all exceptions to aid in periodic review.