Writing a technical analysis before coding: compared options, lightweight ADR and AI assistants
Problem statement, current state, options table, decision and reasons, open points, and what AI helps with or gets wrong.
The urge to start coding straight away is expensive: you find the constraint that kills the solution after three days. So I write a short analysis note before the code: a Markdown file next to the project, which serves first as a thinking draft and then as the record of the decision.
The outline of the note
- Problem statement: two or three sentences. What is the need, for whom, which symptom or limit triggered it?
- Current state: how it works today, with verified facts only (rereading the code, a read-only query, official documentation). Assumptions are marked as such.
- Options compared in a table.
- Decision and its reasons.
- Open points: what remains to confirm, and by whom.
Comparing options in a table
A table forces the same criteria on every option:
| Criterion | A: backup exported to a file | B: geo-replicated copy | C: do nothing |
|---|---|---|---|
| Setup effort | Medium | Low | None |
| Running cost | Storage | Secondary database | None |
| Restore time | Long | Short | Unchanged |
| Main risk | Incomplete file | Failover poorly tested | Limit reached |
| Reversible? | Yes | Yes | Yes |
The options above are a generic example. I always keep "do nothing" as a baseline, and a "reversible?" row: a reversible decision can be taken faster.
A lightweight ADR
An ADR (Architecture Decision Record) is the "decision" part of the note, reduced to the essentials:
## Decision: copy the database through a request queue
- Status: accepted
- Context: manual copies are slow and untracked.
- Decision: requests are processed through a queue, with approval.
- Reasons: traceability, recovery after failure, no direct rights.
- Consequences: one component to maintain; the queue must be monitored.
- Alternatives rejected: manual script (untracked), third-party service (cost).
The key is the "Reasons" section. Six months from now nobody will remember why this was chosen over that: the file says so. If the decision changes, nothing is erased: a new ADR supersedes the old one (status "superseded").
AI assistants: help and traps
What works well:
- Rephrasing the problem and asking questions I had not thought of.
- Proposing options and comparison criteria.
- Rereading the note to spot a contradiction or a gap.
- Reading the code to describe the current state, with file references.
Where it misleads:
- Invented features: an option, a parameter or a service limit that does not exist. I check official documentation before writing it down.
- Uniform confidence: an assumption is stated with the same assurance as a fact. I ask for the source of each fact.
- Confirmation bias: if I present my favourite solution, it validates it. I ask for the arguments against instead.
- Deciding for me: the assistant informs; the decision and its reasons stay mine.
Lessons learned
- Write the current state before the solutions. Half of the bad ideas disappear once the fact is established.
- Stay short. A one-page note gets reread; ten pages do not.
- Date the note and give its status (draft, decided, superseded).
- Keep open points visible. A written unresolved question beats a false certainty.
- Link to the architecture models: a structural decision triggers an update of the views.