Architecture Drift Detection Prompt

This prompt is designed for architects, tech leads, and platform engineers who need to systematically detect when a codebase's implementation has diverged from its intended architecture. The core job-to-be-done is comparing a formal or semi-formal architecture specification—such as Architecture Decision Records (ADRs), dependency rule documents, or module boundary definitions—against the current state of the code, including its import graph, package structure, and module map. The ideal user has access to both the documented architecture and tooling that can extract a dependency graph from the codebase (e.g., madge, dependency-cruiser, or a build graph). The output is a structured drift report that doesn't just flag violations but distinguishes between unintentional erosion and intentional, accepted exceptions.

To use this prompt effectively, you must provide two concrete inputs: a machine-readable or clearly structured representation of the intended architecture rules, and a current dependency graph or module map from the codebase. The architecture rules should specify allowed and disallowed dependencies between modules, layers, or bounded contexts. For example, a rule might state 'domain layer must not import infrastructure layer' or 'feature modules must not depend on each other.' The dependency graph should be a list of source-to-target import relationships. Without both inputs, the model cannot perform a meaningful comparison and will either hallucinate a reference architecture or produce a generic, unactionable report. The prompt is not a substitute for a static analysis tool; it is a reasoning layer that interprets the delta between specification and reality.

Do not use this prompt when no architecture documentation exists. If your team operates without ADRs, dependency diagrams, or explicit module contracts, the model will fabricate a plausible but fictional reference architecture, leading to a drift report that is actively misleading. In such cases, start with a prompt for architecture discovery or module coupling audit to first document the as-is state. Similarly, avoid this prompt for small, single-module projects where the concept of architecture drift is not meaningful. The prompt is also unsuitable for runtime behavioral drift (e.g., performance degradation or API response changes) unless that drift is reflected in static code structure. Finally, the output of this prompt is a diagnostic report, not an automated refactoring script. Human review is required to validate each finding, confirm that flagged exceptions are truly intentional, and decide on remediation actions.

This prompt template is designed to be pasted directly into your AI coding agent or LLM workflow. It instructs the model to compare your documented architecture decisions against the actual codebase structure, import graphs, and module boundaries. The goal is to produce a structured drift report that distinguishes intentional exceptions from genuine erosion, giving you an actionable list of violations to investigate.

codeCopy
You are an architecture conformance auditor. Your task is to compare the documented architecture decisions for a software system against the current codebase structure and produce a drift report.

## INPUTS
- Architecture Decision Records (ADRs) or design docs: [ARCHITECTURE_DOCS]
- Current codebase structure (file tree, import graph, module boundaries): [CODEBASE_STRUCTURE]
- Known intentional exceptions (if any): [KNOWN_EXCEPTIONS]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "summary": "string summarizing overall drift severity and top findings",
  "findings": [
    {
      "id": "string (unique identifier)",
      "rule_violated": "string (reference to the specific architecture rule or ADR)",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "location": "string (file path, module, or import statement)",
      "evidence": "string (specific code or import that violates the rule)",
      "impact": "string (consequence of this drift)",
      "recommendation": "string (suggested remediation)",
      "is_intentional_exception": false
    }
  ],
  "intentional_exceptions_confirmed": ["list of exception IDs that match known exceptions"],
  "unexpected_dependencies": ["list of module pairs with unexpected coupling"],
  "missing_enforced_boundaries": ["list of boundaries that should exist but don't"]
}

## CONSTRAINTS
- Only flag violations where the code clearly contradicts a documented rule.
- If a violation matches a known intentional exception, mark `is_intentional_exception` as true and include it in `intentional_exceptions_confirmed`.
- Do not invent architecture rules. Only use rules explicitly stated in [ARCHITECTURE_DOCS].
- For each finding, provide specific file paths and import statements as evidence.
- If no drift is detected, return an empty findings array with a summary stating conformance.
- Distinguish between missing enforcement (a boundary that should exist but doesn't) and direct violations (code that crosses a boundary it shouldn't).

## RISK LEVEL: [RISK_LEVEL]
- If RISK_LEVEL is HIGH, flag even minor deviations and require explicit justification for any finding marked as intentional.
- If RISK_LEVEL is MEDIUM, focus on CRITICAL and HIGH severity findings.
- If RISK_LEVEL is LOW, only flag CRITICAL violations.

To adapt this template, replace the square-bracket placeholders with your specific inputs. [ARCHITECTURE_DOCS] should contain your ADRs, design docs, or a structured list of architecture rules. [CODEBASE_STRUCTURE] should include a file tree, module dependency graph, or import analysis output—tools like madge, dependency-cruiser, or eslint import rules can generate this. [KNOWN_EXCEPTIONS] is a list of violations your team has already accepted with rationale. Set [RISK_LEVEL] based on your tolerance: use HIGH for regulated systems or critical infrastructure, MEDIUM for most production systems, and LOW for early-stage projects where architecture is still evolving. After running the prompt, validate the output against your known exceptions list to ensure the model correctly identified them. For high-risk systems, always have a senior engineer review findings before filing remediation tickets.

This prompt is designed to be run as a scheduled job or a CI/CD gate, not as a one-off chat. The core workflow involves a three-stage pipeline: context assembly, model inference, and output validation. In the context assembly stage, you must gather the canonical architecture decision records (ADRs), the current dependency graph (from dep-tree or a similar tool), and a list of module boundary rules. The prompt's [ARCHITECTURE_SPEC] placeholder expects a structured markdown document, not a file path. The [CODEBASE_CONTEXT] placeholder should be populated with a pre-computed import graph and a list of public API surfaces, not raw source code, to stay within context limits.

For the inference stage, use a model with a large context window and strong reasoning capabilities, such as claude-sonnet-4-20250514 or gpt-4o. The output is a structured JSON report, so you must enforce the [OUTPUT_SCHEMA] strictly. Implement a retry loop with a maximum of 3 attempts. If the initial response fails JSON schema validation, feed the raw output and the validation error back into the model with a repair prompt: 'The previous output failed JSON schema validation with the following errors: [ERRORS]. Please correct the JSON output to match the schema.' If the repair fails twice, log the failure and escalate for human review. Do not silently accept a malformed drift report.

The most critical part of the harness is the post-inference validation layer. Beyond basic JSON schema checks, implement a finding grounding check. For every drift finding in the report, the validator must verify that the file_path and symbol referenced in the finding actually exist in the current codebase. A finding that points to a non-existent file is a hallucination and must be discarded. Additionally, implement a suppression file mechanism. Known and accepted drifts (intentional exceptions) should be stored in a .drift-suppressions.yaml file. The validator must filter out any finding that matches an active suppression rule before publishing the report. This prevents alert fatigue.

Finally, integrate the validated report into your observability stack. Publish the drift score and the count of new, unresolved findings as metrics to your monitoring system (e.g., Datadog, Prometheus). For each new finding, create a ticket in your issue tracker (Jira, Linear) with the rationale, evidence, and remediation fields from the report. The ticket should be assigned to the team that owns the violating module. To avoid noise, configure the harness to only create tickets for findings with a severity of high or critical. Run the full pipeline on a weekly schedule and on every merge to the main branch that modifies an ADR document or a module boundary configuration.