---
id: 0
title: "Engineering Field Notes"
status: current
date: 2026-06-12
authors:
  - "Theo Zourzouvillys"
tags: [meta, process]
summary: "What Field Notes are, why I write them, and how they work — numbered, status-tracked notes on building software well, published openly and importable as JSON and raw markdown."
supersedes: null
superseded_by: null
aliases: []
---

## TL;DR

**Field Notes are numbered, dated, status-tracked notes on how to build software well.**
Each one takes a single practice I keep reaching for, and writes down three things: the
*context* that makes it matter, the *approach* I'd recommend, and the *trade-offs* it asks you
to accept. They're observations from the field — opinions formed over years of building and
breaking real systems — not commandments. I publish them openly so I can point people at a
durable, considered answer instead of retyping it, so the reasoning outlives the conversation
that produced it, and so anyone can read, argue with, or borrow from them.

If you only read this section: a Field Note is referenced as **ZFN-N** (e.g. `ZFN-7`),
carries a **status** (`current`, `proposed`, `deprecated`, `superseded`), and is published
straight to the site — there's no draft queue. The whole set is available as machine-readable
[`notes.json`](/zfn/notes.json) and as raw markdown per note, so another system can import or
cross-reference them.

## Why these exist

Most of what I know about building software doesn't live in any one codebase. It's the set of
positions I've arrived at the hard way — the thing I say in a design review, the reason I push
back on a tempting shortcut, the pattern I reach for without thinking. For years that knowledge
only existed in my head and in scattered chat threads, repeated slightly differently every
time someone asked.

That's a bad way to keep knowledge. It doesn't scale past the people who happen to be in the
room, it loses the *why* the moment the conversation ends, and it means the same debate gets
reopened from scratch every few months. Writing a position down once, carefully, and being able
to point at it is enormously more leveraged than explaining it again and again.

So Field Notes are my attempt to do three things at once:

- **Pass on what I've learned.** The most useful thing an experienced engineer can leave behind
  isn't code — it's judgment: the reasons behind the choices, especially the attractive
  alternatives that were deliberately *not* taken. That's the part code can't tell you.
- **Keep myself honest and current.** Writing a thing down forces me to actually defend it, and
  publishing it invites people to tell me where I'm wrong. A note I can no longer stand behind
  gets deprecated or superseded — in public, with the history intact.
- **Be useful to people I'll never meet.** If a note saves someone an outage, a bad migration,
  or a week of rediscovering a footgun, it has paid for itself.

This is not a record of decisions any one organization has made. It's a personal body of
engineering guidance — closer in spirit to a practitioner's notebook than to a standards
document.

A note on perspective: most of my career has been spent building and running **high-scale SaaS**
and the infrastructure under it, so some notes lean toward that world — distributed services,
security and identity, reliability under real production load. I try to keep the *reasoning*
general, but the examples and emphases will sometimes reflect where I've spent my time. Take what
transfers to your context; leave what doesn't.

## What a Field Note is

A Field Note is a short, focused markdown file that captures **one** practice. It is opinionated
on purpose. A good note:

- Takes a clear position and says plainly what I'd do and what I'd avoid.
- Spends most of its words on **why** — the forces and constraints that make the practice worth
  following — because the reasoning is what transfers to situations I didn't anticipate.
- Is honest about the **trade-offs**. Every real practice gives something up; a note that reads
  like marketing copy isn't useful. The value is in naming what you knowingly trade away.
- Is **falsifiable and revisable**. It reflects what I believe at its date. When I learn better,
  the note changes status rather than quietly disappearing.

A Field Note is **not** a tutorial, a standard everyone must follow, or a neutral survey of
options. It's a considered recommendation with my name on it.

## Beyond a plain note: open problems, signals, and convictions

Not every entry is a settled, even-handed answer. Three other kinds sit alongside the ordinary field
notes, each with its own badge, and you can filter the index by kind:

- **Open problems** — questions I'm still working out. Written in a different shape (the problem, why
  it's hard, what I've considered, where I'm stuck), because the honest state is "I don't have a good
  answer yet." A lot are about working in the LLM era.
- **Signals** — observations about where the craft or the industry seems to be heading: reading the
  weather, thinking out loud about a shift, not a settled position. I might be wrong, which is the
  point of writing it down.
- **Convictions** — calls I'm **putting my name on**. Stronger and more personal than a note: a firm,
  accountable position with real experience behind it, where the value is precisely that I'll stand
  behind it and answer for it. Reasonable people will disagree; I've decided anyway. Where a plain note
  is usually a *durable principle* (timeless, the reasoning is the point), a conviction is typically that
  principle **applied to a specific, current, contestable pick** — so it's more perishable: when the call
  flips, the conviction gets superseded while the principle underneath it doesn't move. (Worked example:
  [ZFN-32](/zfn/32-commit-to-one-cloud/) is the principle "commit to one cloud, go native";
  [ZFN-42](/zfn/42-my-one-cloud-is-aws/) is the conviction that applies it — "make it AWS." The practice
  itself — why this kind exists — is [ZFN-41](/zfn/41-choices-you-can-put-your-name-behind/).)

Open problems and signals keep their ZFN number and can **graduate into a full Field Note** as I work
them out or as they play out.

## How they work

**Numbering.** Each note gets a stable integer id, assigned in publication order and **never
reused**, written as `ZFN-N` (e.g. `ZFN-7`). `ZFN-0` is this meta note. The number is the durable
identifier and matches the URL and filename (`7-slug.md` → `/zfn/7-slug`); the slug part is for
humans and can change, the number can't.

**No draft queue.** Unlike a decision-record process built around pull-request review, Field
Notes are *published when they're ready*. There's no in-review lane and no waiting for consensus
— these are my notes, so I publish them and then keep them honest over time. The lifecycle lives
in the **status**, not in a review gate.

**Structure.** Notes loosely follow context → recommendation → trade-offs, the same bones as a
classic decision record, but the format is a guideline, not a straitjacket. Each note has
front-matter (`id`, `title`, `status`, `date`, `tags`, optional `summary`, and relation fields)
that the site build validates, so a malformed note fails the build rather than publishing broken.

**Referencing.** Cite a note as `ZFN-N` anywhere — in prose, in code comments, in a review.
The convention is deliberately easy to grep:

```sh
git grep -nE 'ZFN-[0-9]+'
```

Each note links to the next via `supersedes` / `superseded_by` in its front-matter, so the
lineage of a changed position is always traceable.

## Status

Every note carries one of four statuses. This is the lifecycle that replaces a review queue:

- **current** — In effect. This is what I'd recommend right now.
- **proposed** — Published to think in public. I'm leaning this way but haven't settled; comment
  and pushback are explicitly welcome.
- **deprecated** — I no longer recommend this, and there's no direct replacement. Kept on the
  record so old references still resolve and the reasoning isn't lost.
- **superseded** — Replaced by a newer note (see its `superseded_by`). The old note stays; it's
  history, not a dead link.

I amend small things (typos, clarifications) in place. When the *position itself* changes, I
write a new note that supersedes the old one — the old one stays exactly as it was, so the
record of what I used to think survives.

## A note on dates

Every note in the initial set shares a publication date of **12 June 2026** — the day I imported
this collection and first made it public. That date is the *making-public* date, not the
*written* date. The practices here aren't new: they were formed, argued over, and refined
privately across years of building real systems, and many have been "how I do it" for a long
time. This site is simply where they finally became public, all at once. Notes I publish from
here on will carry their real date, so the timeline becomes honest going forward.

## Using them elsewhere

Field Notes are built to be consumed by tools and by other people's systems, not just read in a
browser:

- **`notes.json`** — a machine-readable manifest of every note at
  [`/zfn/notes.json`](/zfn/notes.json): id, `ZFN-N` ref, title, status, dates, tags,
  summary, supersedes/superseded_by relations, and both the rendered URL and the raw-markdown
  URL. The field shape intentionally mirrors a decision-record manifest (the kind an ADR or RFD
  system publishes) so importing or cross-referencing is mechanical.
- **Raw markdown** — every note is published verbatim, front-matter included, at
  `/zfn/<slug>.md`. That's the canonical importable source.

So another decision-record system can pull `notes.json`, follow each `raw_url`, and ingest or
link these notes directly — citing `ZFN-N` the same way it cites its own records. If you adopt
a note as your own standard, the honest thing is to record *that* adoption on your side; the note
here is unchanged and keeps being maintained at its source.

## Engaging and disagreeing

These are opinions, and the best outcome is a better opinion. If you think a note is wrong,
incomplete, or out of date, tell me — a concrete counter-example or a "this breaks when…" is
worth far more than a vague disagreement. The point of writing them down isn't to be right
forever; it's to have something specific enough to be *proven* wrong, and to update it when that
happens.

## Reuse

Take what's useful. These notes are written to be shared, quoted, adapted, and argued with. If
one helps, use it; if one's wrong, tell me why and I'll fix it. Attribution is appreciated but
the goal is simpler than that — to leave the craft a little better documented than I found it.

## Changelog

- **2026-06-12**: First published. Established the Field Notes format, the `ZFN-N` numbering,
  the four-status lifecycle, and the `notes.json` + raw-markdown interface for external use.
- **2026-06-12**: Set the canonical URL prefix to `/zfn/` and the reference scheme to `ZFN-N`, so the
  path matches the ref (`zrz.io/zfn/42` reads as ZFN-42). Bare-number URLs (`/zfn/42`) and prior slugs
  redirect to the canonical slug; the short prior `/notes/...` form was a same-day pre-launch state and
  is not redirected.