learning-it by example

#242 Enterprise architecture and AI agents 6 min

Architecture Decision Records for AI Choices, With a Lint

I planted seven problems in seven decision records for an AI assistant, and a small lint found all seven.

1. When a decision in an architecture decision record (ADR) changes, what does the append-only approach say to do?
2. In the Python ADR lint example, which three extra lines does the author add to a decision record for an AI choice?
3. In the decision records lint run, how many records and how many problems were found before the fixes, and how many after?
4. Why was the record that moves triage to a bigger local model flagged, even though it was written correctly?
5. What is the main limit of the Python lint for architecture decision records?

Practice only: nothing is saved and no score counts towards anything. Each answer comes with the reason.

  1. Match each problem to its record

    Copy the code folder first. Run python compare.py and read the seven problems. Open adrs.py and, for each problem, find the line in the record that causes it. For example, find the Status line that makes 0006 report an allowed-status problem.

    A hint

    The lint rules are in lint.py, one if statement for each kind of problem.

  2. Move the date forward

    In lint.py, change TODAY = "2026-11-06" to TODAY = "2027-03-15". Predict which records now have a review date that has passed, then run python compare.py. When I ran it there were 9 problems, and records 0001 and 0003 also reported a passed review date. The line after the fixes said 2 problems. Then change TODAY back to "2026-11-06" before the next task.

    A hint

    The review dates in the records are 2027-02-01, 2027-03-01 and 2027-04-01 for the models.

  3. Allow one more status

    In lint.py, add "Decided" to the STATUSES set. Predict how the problem count changes, then run python compare.py. When I ran it the count fell from 7 to 6 and the status problem for record 0006 disappeared. Write one sentence on whether you think allowing it is a good idea. Then remove "Decided" again before the next task.

    A hint

    The status problem was one of three that record 0006 had.

  4. Remove an evaluation

    In adrs.py, in record 0001, change the line Evaluation: 19 of 20 labels right on our test set to Evaluation: none yet. Predict the new problem, then run python compare.py. When I ran it there were 8 problems and record 0001 reported that it uses a model but gives no evaluation numbers.

    A hint

    The check looks for a digit in the Evaluation line.

These tasks are for you to try on your own machine. Nothing is checked or saved.

What this does not show

Seven records I wrote with seven planted problems; the lint checks form only, not whether a decision or its evaluation is right; today's date is fixed in the code; the script prints and exits 0; the fixes edit records in place; the rules are mine.

Up next in Enterprise architecture and AI agents

More in Enterprise architecture and AI agents

All Enterprise architecture and AI agents videos

Related videos