AI Architecture Decision Record Writer

Every codebase has a layer of decisions that nobody can explain anymore. Why did we pick this database. Why is auth split between this service and that one. Why does the deploy pipeline have this odd staging step. The decisions had reasons at the time. The reasons were not written down, and the people who knew them have moved on, retired, or simply forgotten. The result is a codebase that future engineers treat as a museum: every odd choice is preserved because nobody knows whether removing it will break something. The cost of this loss is paid in over-cautious refactors, in the meetings where someone asks "why don't we just" and nobody can answer authoritatively, and in the technical debt that nobody is willing to pay down because the original constraint might still apply.

An Architecture Decision Record is the artifact that prevents this loss. Written at the moment of the decision, it captures what was decided, what alternatives were seriously considered, what tradeoffs were accepted, and what consequences the team expected. Future engineers who inherit the decision can read the ADR, evaluate whether the original reasoning still holds, and either preserve the decision or change it deliberately. The discipline is well-known and rarely practiced because writing an ADR takes an hour, and an hour after a meeting is the moment when everyone is moving on to the next thing. The /atlas-adr skill compresses that hour into minutes by capturing the decision while it is fresh and structuring it consistently with the rest of the team's records.

Why decisions get lost without ADRs

The standard failure mode is a meeting where the team chose between two options, picked one, and moved on. The reasoning lived in the meeting, not in the codebase. When the next engineer encounters the chosen option six months later, they see the artifact (the database schema, the auth service split, the staging step) without the context. They form a hypothesis about why the choice was made, and the hypothesis is usually wrong. Acting on the wrong hypothesis is how teams accidentally re-introduce the problem the original decision was solving.

Generalist AI tools do not produce ADRs because the prompt did not ask for one. The team is busy implementing the decision; the documentation feels like overhead. The discipline of writing the ADR before the implementation lands is what prevents the loss, and the discipline only sticks if the ADR is cheap to write. The structured template, the alternatives section, and the consequences section are the parts that take time, and those are exactly the parts /atlas-adr produces from the conversation rather than from a blank page.

What a useful ADR contains

The classic ADR template has six sections. First, the title and the date. Second, the status (proposed, accepted, deprecated, superseded). Third, the context: what problem the decision is solving, what constraints applied, what the team needed to choose between. Fourth, the decision itself, stated clearly: what was chosen and what the alternatives were that were seriously considered. Fifth, the consequences: what becomes easier with this choice, what becomes harder, what is now constrained for future decisions. Sixth, the references: links to the meeting notes, the spike work, the prior art, anything that future readers might want to follow.

The two sections that matter most are the alternatives and the consequences. The alternatives section is the proof that the team considered multiple options seriously rather than picking the first one that came up; without it, future engineers cannot tell whether a different option might be worth revisiting. The consequences section names the trade-offs explicitly, including the bad ones; without it, future engineers cannot tell whether a current pain is the original tradeoff (still worth it) or a new problem (worth fixing). Both sections require honesty that is uncomfortable to commit to in writing, which is why they are the sections most often skipped, and why the ADRs that omit them age the worst.

How /atlas-adr works

Step one: capture the context

When invoked, /atlas-adr asks for the decision, the alternatives that were considered, and the constraints that applied. The questions are surfaced together so the team answers them while the discussion is fresh. The skill is opinionated about not writing past missing context; if the alternatives section is empty ("we just went with what felt right"), the skill asks for the runners-up rather than producing an ADR that hides the decision-making.

Step two: structure the record

The output follows the project's existing ADR template. If the project does not have one, /atlas-adr proposes the standard Michael Nygard format and creates the docs/adr/ directory with a numbered ADR file. Existing ADRs are read first so the new ADR uses the same headings, the same numbering scheme, and the same level of detail. The consistency matters because ADRs are most useful when the team can scan a directory of them and find what they need.

Step three: name the consequences honestly

The consequences section is structured into three parts: what gets easier, what gets harder, and what is now constrained. The skill prompts for each part rather than letting the team default to listing only the benefits. "What gets harder" is the section that future engineers will most appreciate; it is the section that lets them tell whether a current pain was an accepted trade-off or a new problem. The skill is opinionated about including this section even when it is uncomfortable to write.

Step four: link to references

The ADR closes with a references section: links to the meeting notes, the spike PR, the prior ADRs that this one builds on or supersedes, and any external articles or talks that informed the decision. The references are the breadcrumb trail for future engineers who want to dig deeper. The skill produces the section automatically from any links the team provides during the capture step.

Tonone's /atlas-adr skill writes Architecture Decision Records that capture what was decided, what alternatives were considered, the tradeoffs, and the consequences.

When to use /atlas-adr, and when not to

/atlas-adr is the right call after any significant technical decision: choosing a database, selecting a framework, adopting an architectural pattern, deciding against a commonly expected approach. The signal is when the decision will affect work for months or years and when the reasoning would be hard to reconstruct later. Run the skill while the discussion is fresh; the cost of writing the ADR right after the decision is a fraction of the cost of reconstructing the reasoning a year later.

Skip the skill for trivial reversible decisions (the linter rule, the test directory layout, the variable naming convention). Those are not ADR-worthy. For broader system mapping, /atlas-map produces the architecture diagram. For onboarding documentation aimed at new engineers, /atlas-onboard is calibrated to that purpose.

A worked example: ADR for choosing Postgres over DynamoDB

Suppose the team chose Postgres over DynamoDB for the new billing service. Run /atlas-adr and the output is the structured record.

# ADR-0014: Use Postgres for the billing service

Date: 2026-03-24
Status: Accepted

## Context

We are building a new billing service that handles subscriptions,
invoices, and payment state. Strong consistency is required (no
double-charges), and the team needs ad-hoc reporting capability
for finance.

We considered two options:
- **Postgres**: relational, strong consistency, mature ecosystem,
  rich query capability for finance reports.
- **DynamoDB**: managed, scales horizontally without intervention,
  matches the rest of our backend stack.

## Decision

Use Postgres on AWS RDS for the billing service.

## Consequences

### Easier
- Strong consistency for payment state without application-level
  workarounds.
- Finance team can run ad-hoc SQL for reports without an analytics
  pipeline.
- Schema changes are versioned migrations, which our team is fluent in.

### Harder
- We now operate two database technologies (existing services use
  DynamoDB). On-call complexity increases.
- Horizontal scaling will require explicit work (read replicas first,
  sharding if growth justifies it). DynamoDB would scale automatically.
- Disaster recovery requires running PostgreSQL backups and tested
  restore procedure separately from existing DynamoDB DR.

### Constrained
- Future billing-related services should use the same Postgres
  instance for transactional consistency, or document why not.
- The team commits to maintaining Postgres operational expertise.

## References
- Spike: PR #4380 (DynamoDB modeling)
- Spike: PR #4391 (Postgres modeling)
- Meeting notes: 2026-03-22 (link)
- Prior ADR: ADR-0007 (DynamoDB as the default OLTP store)
  This ADR creates an exception to ADR-0007 for billing.

The ADR is one page. Every section is filled. The alternatives are named and not just "various options were considered." The consequences include the things that get harder, which is the section that future engineers will most appreciate when they encounter the dual-database operational burden in two years.

Related skills

/atlas-adr captures decisions. For the system architecture diagram that ADRs reference, /atlas-map produces the C4-style map. For onboarding documentation aimed at new engineers, /atlas-onboard is calibrated to that purpose.

Install

/atlas-adr ships with the Atlas agent in the Tonone for Claude Code package. Install Tonone, invoke /atlas-adr from any Claude Code session after a significant decision, and the skill produces the structured record while the reasoning is fresh.

Decisions captured at the time are decisions that survive the team turnover that loses them otherwise. The skill is built so capture is cheap enough to apply every time.