The case for writing architecture decisions down in public, not just internally

Most engineering teams that document architecture decisions at all keep those documents internal — a wiki page, a design doc, a Slack thread that someone remembers to link later. That's better than not documenting the decision at all, but it optimizes for a narrower goal than the one that actually matters to someone evaluating the system from outside: internal documentation explains a decision to the team that made it. Public documentation lets someone who has no reason to trust you yet check whether the decision holds up.

An architecture decision record, done properly, isn't a design document — it's a specific, dated claim: here is the problem, here are the alternatives we considered, here is what we chose and why, here is what we expect to be true as a consequence, and here is the status, because a decision that was 'proposed' and never actually ratified or implemented is a meaningfully different claim than one that's live in production.

Why keeping this internal-only leaves value on the table

• A decision nobody outside the team can see is a decision nobody outside the team can hold you to — and the accountability that comes from a public, dated record is exactly what makes 'we thought this through' a checkable claim instead of an assertion.
• Public ADRs let a buyer or a security reviewer evaluate the reasoning, not just the conclusion — 'outbound-only agent' is a claim; the ADR explaining why inbound listening was rejected, and what tradeoff was accepted to get there, is the reasoning a technical evaluator actually wants to see.
• A visible decision log doubles as a visible roadmap in the sense that matters most — not a marketing timeline, but a record of what's actually been decided, what's actually been built, and what's still just a proposal, which is a very different and more useful thing than a features page.
• It creates a real cost to reversing a decision quietly — if changing course means updating a dated public record rather than just editing an internal wiki page, that friction is a small but real check against decisions drifting without anyone noticing or explaining why.

The honest tradeoff is that public ADRs also expose disagreement and false starts, and a team has to be comfortable with a reader seeing a decision that was proposed, debated, and rejected, or one that shipped and later got reversed. We'd argue that's a feature rather than a cost — a decision log with no rejected proposals and no reversals in it isn't evidence of good judgment, it's evidence that the messy part got edited out before anyone else could see it.

Nexus runs its own architecture decisions through exactly this discipline: a proposed ADR is a genuinely open, unratified claim — status 'proposed' — until it's formally reviewed and accepted, with the date of acceptance recorded rather than backdated to make the timeline look cleaner than it was. That governance process is real and it runs on every architectural decision behind the platform, including the ones referenced elsewhere on this blog, like the outbound-only agent design or the two-layer tenant isolation model. What's not yet true is a fully public-facing ADR archive external readers can browse directly — right now that record lives in our own build process and gets surfaced through posts like this one and the roadmap page, and turning the raw archive itself into a public, browsable one is on our list, not a claim we're making about today. Ask us for the ADR behind any specific architectural claim on this blog in the meantime, and the honest answer should be that one exists, dated, with the alternatives it rejected still visible in it.