adr-compliance

ADR Compliance

This skill provides guidance on auditing code and system compliance with accepted Architectural Decision Records. Compliance checking ensures that architectural decisions are actually implemented and followed.

What is ADR Compliance?

ADR Compliance verifies that:

• Implementation matches documented decisions
• New code follows accepted patterns
• Deviations are intentional and documented
• Technical debt from violations is tracked

Compliance Workflow

1. Identify Enforceable ADRs

Not all ADRs require compliance checking:

ADR Type	Enforcement
Technology choice	Check for usage/imports
Pattern adoption	Check for structure/patterns
Constraint	Check for violations
Process decision	Manual review
Organizational	Manual audit

2. Define Compliance Criteria

For each enforceable ADR, define:

• What code patterns indicate compliance
• What patterns indicate violations
• Where to look (file patterns, modules)
• How to verify (automated vs manual)

3. Check Implementation

Methods for checking:

• Code analysis (grep, AST)
• Architecture tests (ArchUnit, etc.)
• Manual code review
• Runtime verification

4. Report and Remediate

Document findings:

• List violations found
• Assess severity
• Recommend remediation
• Track resolution

Compliance Checking Approaches

Code Pattern Analysis

Search for patterns that should/shouldn't exist:

# Check for prohibited imports (ADR says don't use library X)
grep -r "import libraryX" src/

# Check for required patterns (ADR says use factory pattern)
grep -r "Factory.create" src/

Architecture Testing

Use architecture test frameworks:

Java (ArchUnit):

@ArchTest
static final ArchRule servicesShouldNotAccessRepositories =
    noClasses().that().resideInAPackage("..service..")
    .should().accessClassesThat().resideInAPackage("..repository..");

TypeScript:

// Custom architecture rules
describe('Architecture compliance', () => {
  it('services should not import from UI layer', () => {
    // Check import patterns
  });
});