ADRs & Changelogs: Recording Why the Infrastructure Looks This Way

In this module, you'll learn to:

• Write an architecture decision record (ADR) whose rejected options would convince a sceptical reviewer
• Recognise the infrastructure changes that must come with an ADR
• Keep a changelog per environment that lines up with the code, the ADRs, and the release tags

Before you start: read Base, Composition & Environment. Each environment folder holds its own docs/ folder.

The code can't tell you why

Six months after a change, someone will look at a bucket with access logging switched off, or an environment with a resource the others lack, and ask whether it's a mistake. The Terraform shows what was built. Without a record of why, the safe-looking fix may undo a deliberate decision, and the risky-looking setting may be left alone when it really was a mistake.

An architecture decision record is a short Markdown file that captures one decision: the problem, the options weighed, the choice, and its consequences. It lives next to the code it explains, so it's reviewed in the same pull request.

One docs/ folder per environment

environments/nonprod/docs/
├── adr/
│   ├── 0001-record-architecture-decisions.md
│   ├── 0002-single-glue-crawler-per-bucket.md
│   └── 0003-nonprod-buckets-without-access-logging.md
└── CHANGELOG.md

• One file per decision, named NNNN-short-kebab-case-title.md, numbered in order.
• Never renumber or delete an ADR. When a decision changes, write a new ADR and mark the old one Superseded by 00NN. The history of why is the point.
• 0001 is always the same: it records that this project uses ADRs, in the format below.

Context, options, decision, consequences

This is the common Michael Nygard format, with one addition: an Options Considered section.

# NNNN. <Title>

Date: YYYY-MM-DD

Status

Proposed | Accepted | Deprecated | Superseded by 00NN

Context

What problem or constraint led to this decision.

Options Considered

1. Option A: <name>

• Description, pros, cons
• Why not chosen: ...

1. Option B: <name>

• Description, pros, cons
• Why not chosen: ...

1. Option C: <chosen option> (see Decision)

Decision

Which option was chosen, and why it beat the others.

Consequences

What becomes easier or harder; the trade-offs accepted. ```

Options Considered is the section reviewers check

A decision record without alternatives is just a statement. The rules for this section:

• At least two alternatives besides the chosen one, including "do nothing" where it's real. If there was genuinely only one viable approach, say so explicitly rather than leaving the section out.
• Every rejected option gets a concrete reason: cost, a security gap, operational load, a team skill gap, a service limit. "We preferred the other one" isn't a reason.

This matters most when an ADR justifies accepting a security finding (Module 11). The reviewer needs to see that safer options were genuinely weighed, not skipped for convenience.

An ADR for an accepted risk

# 0003. Nonprod data buckets without S3 access logging

Date: 2026-09-14

Status

Accepted

Context

Checkov check CKV_AWS_18 flags the nonprod Glue data bucket for having no server access logging. Nonprod holds only synthetic test data, and CloudTrail management events are already collected for the account.

Options Considered

1. Enable server access logging to a central log bucket

• Pros: matches production; satisfies the check.
• Cons: log storage and lifecycle cost for synthetic data.
• Why not chosen: no audit requirement covers synthetic data, so the cost buys no reduction in real risk.

1. Enable CloudTrail S3 data events instead

• Pros: richer, API-level records.
• Cons: billed per event; the ETL job makes millions of calls.
• Why not chosen: highest cost of the three for the same gap.

1. Accept the finding for nonprod only (chosen)

Decision

Accept CKV_AWS_18 on the nonprod data bucket only, with a scoped inline skip that references this ADR. Production keeps logging.

Consequences

No object-level access history in nonprod. If real data ever enters nonprod, this ADR is superseded and logging is enabled. ```

The last line is worth copying: a good accepted-risk ADR says what would make it wrong.

Changes that must come with an ADR

What changed, environment by environment

ADRs record decisions. The changelog records changes: every notable change to that environment's infrastructure, in the Keep a Changelog style:

# Changelog

All notable changes to the nonprod Glue and S3 infrastructure.

[Unreleased]

Added

Changed

Fixed

[1.1.0] - 2026-10-01

automatic catalog updates.

[1.0.0] - 2026-09-01

- **Update it in the same pull request** as the Terraform change, under `[Unreleased]`. Move the entries into a version section when the change is applied.
- **Line versions up with Git tags**, if the repository tags releases.
- **Reference ADR numbers** when a change carries out or supersedes a decision, as in `See ADR-0003`.

### Implementation notes

- **Write the ADR before or with the code, never after.** An ADR written after the fact describes what was built, not the choice that was made, and the Options Considered section shows it.
- **Keep ADRs short.** One decision, one to two pages. If it needs more, it's probably two decisions.
- **Put the ADR number in the code.** A comment like `# see ADR-0003` beside a skip or an unusual setting turns a puzzle into a link.

Key terms

• ADR (architecture decision record): a short, numbered file recording one decision, its alternatives, and its consequences.
• Options Considered: the ADR section listing the real alternatives and the concrete reason each was rejected.
• Superseded: the status of an ADR replaced by a later one; it's kept, never deleted.
• CHANGELOG.md: the per-environment record of notable changes, grouped by version.
• [Unreleased]: the changelog section where entries wait until the change is applied.

Pop quiz

Five questions: three on the ideas in this module, and two scenarios where you apply them. The order changes every time you take it, and 4 out of 5 passes.