Engineering Field Notes

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 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 is the principle “commit to one cloud, go native”; ZFN-42 is the conviction that applies it — “make it AWS.” The practice itself — why this kind exists — is ZFN-41.)

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:

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: 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.