ArchPilotExecutable architecture guardrails

Search docs

Docs search

Validation rule

Back to Rule Catalog
AP-SAFE-001Safety Controls

Missing ADR coverage for risky architecture change

Flags risky architecture changes that lack ADR evidence.

warningviolationNo auto-fix

How to fix

  1. Write or update an ADR.
  2. Include context, decision, consequences, and rollback notes if relevant.
  3. Link the ADR from the architecture overview or related docs.

What the rule validates

ArchPilot found a change pattern that should have an architecture decision record.

Why it matters

Risky architecture changes need review context that survives beyond a pull request.

Common causes

  • A boundary, tenant, API, or persistence decision changed without an ADR.
  • The ADR exists but is not linked or keyword-discoverable.
  • A generated report found risk before documentation caught up.

Typical violation example

A module boundary is changed with only an inline PR comment.

Typical compliant example

An accepted ADR records why the boundary changed and what teams should expect.

Related rules

AP-SAFE-002 - Missing rollback plan for risky architecture changeAP-SAFE-003 - Missing feature-flag or staged rollout evidence for risky architecture change

Adjacent categories

Safety Controls

Related files/config

  • docs/adrs
  • docs/architecture/overview.md

Related CLI commands

  • archpilot validate
  • archpilot validate --ci

Related docs

Rule CatalogPolicy & ADR Workflows
AP-SAFE-001 - Missing ADR coverage for risky architecture change | ArchPilot Docs