DEV Community

Cover image for Decision Records So AI Context Doesn't Rot
Muhammad Ali Mughal
Muhammad Ali Mughal

Posted on

Decision Records So AI Context Doesn't Rot

On one client project, an AI assistant helpfully "fixed" our queue setup three times in two months. Each time, a developer asked it to speed up a slow job, and each time it suggested moving the work from our dedicated Redis queue back to the database driver, because the database queue was simpler and the assistant saw a stray QUEUE_CONNECTION=database in an old .env.example. Nobody on the current team remembered why we had moved to Redis in the first place: a deadlock storm during a Black Friday import, two years earlier. That reason lived in a Slack thread and one engineer's memory. The code did not explain it, so neither the new developers nor the assistant could respect it.

I wrote this with help from AI tools and checked every example against Laravel 11, Node 22, GitHub Actions and the adr-tools and MADR conventions. I am a Principal Software Engineer in Karachi with 9+ years across PHP/Laravel, Vue, Node and .NET microservices, and through Loop Origin I maintain custom business applications where a lot of new code is now AI-assisted.

๐Ÿ“š Series Navigation โ€” Maintaining AI-Written Code in Production

Related earlier posts: Config & Feature Flags That Quietly Diverged Across Environments ยท Synthetic Checks & SLOs for the Paths Nobody Clicks

How do architecture decision records help with AI-assisted code?

Direct answer: An architecture decision record (ADR) is a short markdown file in the repo that explains one decision: context, choice, consequences and status. AI assistants and new developers only see what is in the codebase, so ADRs turn tribal knowledge into context they can read. Point your assistant's rules file at them and check in CI that big changes reference one.

Open engineering logbook with a pencil beside a laptop, AI-generated

Why context rots faster with AI in the loop

Before AI assistants, undocumented decisions decayed slowly. The person who made the choice usually reviewed the next change to that area. Now the volume of changes is higher, reviewers are stretched (Part 1), and the assistant generating the code has no memory of last year's incident. It optimises for what looks clean in the files it can see.

Typical decisions I have watched get silently reversed:

Decision Why it was made How it got undone Cost
Redis queues instead of database queues Deadlocks under bulk imports Assistant "simplified" the driver Repeat of the incident in staging
Money stored as integer cents Rounding errors in invoices New model used decimal(8,2) and floats in JS Penny mismatches in reconciliation
No ORM eager loading on the report endpoint; raw SQL instead N+1 timeouts on large tenants Refactor to Eloquent relationships 30s responses for the biggest client
Soft deletes disabled on audit tables Compliance: audit rows must never be hidden Trait added for "consistency" Audit gaps
Pinned PDF library version Newer version broke Urdu font shaping Dependency bump PR Garbled invoices

None of these were bad changes in isolation. They were bad because the reason was invisible.

Keep the format small enough that people actually write them

Long design documents do not get written for every decision, and nobody reads them. I use a trimmed MADR-style template that fits on one screen:

# 0007. Use Redis for queues, not the database driver

- Status: accepted
- Date: 2024-11-29
- Deciders: Ali, Hamza
- Supersedes: โ€”
- Related code: config/queue.php, app/Jobs/Import/*

## Context
Black Friday product import (โ‰ˆ400k rows) caused InnoDB deadlocks on the
`jobs` table and stalled checkout. Database queue polling also added load
to the primary DB.

## Decision
All queues run on Redis (`QUEUE_CONNECTION=redis`) with Horizon.
The database driver is allowed only in local tests.

## Consequences
+ Imports no longer contend with checkout queries.
+ Horizon gives per-queue metrics and retries.
- Redis is now a hard dependency; it is monitored and backed up.
- Do NOT switch back to the database driver to "simplify" setup.

## Revisit when
Job volume drops below 1k/day or Redis hosting cost becomes material.
Enter fullscreen mode Exit fullscreen mode

The "Revisit when" section is the one I added after years of maintenance work. It tells future readers, human or AI, under what conditions changing the decision is fine, so ADRs do not turn into permanent dogma.

Where ADRs live and how to number them

Put them next to the code, not in a wiki that drifts:

docs/
  decisions/
    0001-record-architecture-decisions.md
    0002-money-as-integer-cents.md
    0003-multi-tenant-by-tenant-id-column.md
    0007-redis-for-queues.md
    0012-pin-dompdf-for-urdu-shaping.md
    README.md   โ† index: number, title, status, one-line summary
Enter fullscreen mode Exit fullscreen mode

Never edit an accepted ADR to change the decision. Write a new one that supersedes it and update the old status to superseded by 0019. That history is exactly what explains why the code looks the way it does.

A tiny script keeps creation frictionless:

#!/usr/bin/env bash
# bin/adr "Use Redis for queues"
set -euo pipefail
dir=docs/decisions
n=$(printf "%04d" $(( $(ls $dir | grep -E '^[0-9]{4}' | wc -l) + 1 )))
slug=$(echo "$*" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/-$//')
file="$dir/$n-$slug.md"
sed -e "s/{{N}}/$n/" -e "s/{{TITLE}}/$*/" -e "s/{{DATE}}/$(date +%F)/" $dir/template.md > "$file"
echo "Created $file"
Enter fullscreen mode Exit fullscreen mode

Point AI assistants at the decisions

Most AI coding tools read a project rules file: AGENTS.md, .cursor/rules, CLAUDE.md, .github/copilot-instructions.md and similar. I keep one short rules file and link the ADRs rather than copying them, so there is one source of truth:

# AGENTS.md (excerpt)

## Architecture decisions
Before changing queues, money handling, tenancy, audit tables or pinned
dependencies, read the matching record in docs/decisions/ and follow it.
If a change would contradict an accepted decision, stop and say so in the
PR description instead of changing it.

Key decisions:
- Money is integer cents everywhere (0002). Never use float for amounts.
- Tenancy uses a tenant_id column with a global scope (0003).
- Queues run on Redis + Horizon (0007).
- dompdf is pinned for Urdu shaping (0012). Do not bump without the PDF snapshot tests.
Enter fullscreen mode Exit fullscreen mode

In practice this changed assistant behaviour more than I expected. When asked to speed up the import job, the assistant now proposes chunking and batch inserts instead of switching drivers, and it cites 0007 in its explanation. It is not magic; it is just context that used to be missing.

For decisions that can be checked mechanically, add a code comment pointing to the ADR at the exact spot people (and tools) will edit:

// config/queue.php
// See docs/decisions/0007-redis-for-queues.md โ€” do not switch to 'database'.
'default' => env('QUEUE_CONNECTION', 'redis'),
Enter fullscreen mode Exit fullscreen mode

Enforce it lightly in CI

I do not block every PR on documentation. I flag the risky ones. This GitHub Actions step fails when a PR touches protected paths without mentioning an ADR number in its description or adding a new ADR:

# .github/workflows/adr-check.yml
name: adr-check
on: pull_request
jobs:
  adr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Require ADR reference for protected paths
        env:
          BODY: ${{ github.event.pull_request.body }}
        run: |
          changed=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
          if echo "$changed" | grep -qE '^(config/queue.php|config/database.php|app/Models/Concerns/Tenant|composer.json)'; then
            if echo "$changed" | grep -q '^docs/decisions/' || echo "$BODY" | grep -qE 'ADR[- ]?[0-9]{4}'; then
              echo "ADR referenced"; else
              echo "::error::Protected path changed. Reference an ADR (e.g. ADR-0007) or add one."; exit 1
            fi
          fi
Enter fullscreen mode Exit fullscreen mode

Combine this with the static analysis gates from Part 4, for example a PHPStan rule or ESLint no-restricted-syntax that bans float casts on money fields, and the most important decisions are protected by both words and tooling.

What deserves an ADR (and what does not)

Write an ADR Skip it
Choice between two reasonable options that someone might reverse Formatting and naming conventions (use a linter)
Anything caused by a past incident One-off bug fixes with a good commit message
Pinned versions or unusual config Library choice with no real alternative
Data model rules (money, tenancy, deletes) Temporary experiments behind a flag
Security or compliance constraints Decisions fully expressed by a test

A practical rule: if you have explained the same decision twice in code review, write it down.

Backfilling decisions on an existing codebase

On inherited projects, I spend the first week writing five to ten ADRs from what I learn: incidents in the issue tracker, odd config values, pinned versions in composer.json and package.json, and comments like "don't touch this." Each one takes 15 minutes. This is often the most valuable part of a maintenance handover, and it is where Loop Origin's custom web application development engagements usually start. If you want a second pair of eyes on an inherited codebase, you can reach out here.

Diagnostic checklist

  • [ ] docs/decisions/ exists with a one-screen template and an index README
  • [ ] Top 5โ€“10 risky decisions backfilled (money, tenancy, queues, pinned deps, audit)
  • [ ] Each ADR has status, context, decision, consequences and "revisit when"
  • [ ] Superseded ADRs are kept and linked, never rewritten
  • [ ] AI rules file (AGENTS.md or equivalent) links key ADRs and says to stop on conflicts
  • [ ] Code comments point to ADRs at the exact config or class people edit
  • [ ] CI flags PRs touching protected paths without an ADR reference
  • [ ] Mechanical rules (no floats for money, etc.) enforced by static analysis too
  • [ ] New incident postmortems end with "ADR needed? yes/no"
  • [ ] ADR index reviewed quarterly for stale "revisit when" conditions

FAQs

Aren't ADRs just more documentation nobody reads?

Short ones get read, especially when code comments and the AI rules file point to them at the moment of change. The goal is one screen per decision, not a design document.

Should AI write the ADRs?

It is good at drafting from a Slack thread or PR discussion, and I often use it that way. A human who made the decision should still edit the context and consequences, because those are exactly the parts an assistant cannot know.

Do I need a tool like adr-tools or Log4brains?

No. A folder, a template and a ten-line script are enough. Tools help with rendering a site later, but they are not what makes ADRs useful.

How is this different from a README?

A README describes how the system works now. ADRs explain why it ended up that way and what was rejected. Both are useful; ADRs are what prevent well-meaning reversals.

Will the assistant really follow the rules file?

Usually, but not always. That is why the CI check and static analysis rules exist. Treat the rules file as guidance and the pipeline as enforcement.

How many ADRs is too many?

If the index has hundreds of entries nobody reviews, you are recording too much. Most business apps I maintain have 15โ€“40 meaningful decisions.

Next in this series, Part 6 covers measuring AI coding impact with DORA metrics instead of gut feeling.


Follow & Connect

Top comments (0)