Quiz - Docs that live next to the truth

A teammate proposes scaffolding /tutorials, /how-to, /reference, and /explanation folders on day one “so the repo is Diataxis-compliant.” What’s the senior objection?

Diataxis is a vocabulary for deciding what a doc is for, not a folder mandate — most SaaS repos need only a README, an AGENTS.md, and /docs/adr/; the four types live across those files and the source code.

The folders are right, but they should be created lazily — add each one the first time a doc of that type is written.

Reference shouldn’t get its own folder because it belongs in the README; the other three folders are correct.

Diataxis sorts docs by the reader’s job; it does not require four directories. A repo that scaffolds empty type-folders has cargo-culted the framework. The four types are carried by a handful of files plus the source itself — the schema, env.ts, and TSDoc are all reference, with no /reference folder in sight.

A README feels bloated and unfocused and you can’t say why. According to the lesson’s 2x2, what’s the usual underlying cause?

The document straddles two quadrants — it’s trying to serve two different readers (e.g. teach a newcomer and answer a fact-lookup) in the same breath.

It’s simply too long; cutting it below 50 lines fixes the focus problem on its own.

It’s missing the explanation quadrant, so readers sense an incomplete picture.

You’re writing the README and want a “Data model” section listing the invoices table’s columns. What’s the source-as-doc call?

Don’t write it — link to src/db/schema.ts. A paraphrased column list has nothing keeping it in sync, so it goes silently wrong the moment a column changes; the schema file is the data-model doc.

Write it, but add a comment reminding contributors to update it whenever the schema changes.

Write a short version with just the key columns, since a recruiter skimming the README benefits from seeing the data shape.

Which belong in the thin README’s five-section template? Select all that apply.

The copy-paste commands to get a dev server running locally

A “Where the docs live” section of links to AGENTS.md, /docs/adr/, the schema, and env.ts

An “Architecture” section explaining why Postgres was chosen

The full environment-variable list with a description of each one

The README’s one job is first contact: title/description, getting started, common tasks, where the docs live, and license. The “Architecture” section is explanation that belongs in an ADR — it’s the mixing trap wearing a respectable heading. The full env-var list belongs in env.ts plus .env.example; the README just links to it.

In 2026, does every major coding tool read AGENTS.md natively?

No — most do (Codex, Cursor, Copilot, Aider, and others), but Claude Code reads CLAUDE.md; the senior move is one canonical AGENTS.md with a one-line bridge or symlink for the holdouts.

Yes — AGENTS.md is now a universal standard every agent reads directly, which is the whole reason it replaced .cursorrules and the others.

No — you still maintain a separate full instruction file per tool, because no single format has won yet.

The honest 2026 story is “one canonical file, with a one-line bridge for the tools that haven’t caught up.” Claude Code is the notable holdout (it reads CLAUDE.md), and you bridge it with a single @AGENTS.md import or a symlink rather than maintaining a second full file — two full files would drift, a bridge can’t.

Your AGENTS.md says “Drizzle for all database access,” and you’re tempted to add the paragraph explaining why you picked Drizzle over Prisma. Where does that reasoning belong?

In an ADR under /docs/adr/ — AGENTS.md states what the convention is and links the why; folding the rationale in bloats the conventions file with content that has a proper home.

In AGENTS.md right there — keeping the convention and its justification together is what makes the file useful to an agent.

In the README’s “Where the docs live” section, so first-contact readers see the reasoning immediately.

Drag-sort aside — which one of these decisions earns its own ADR?

Choosing Server Actions as the API surface instead of REST route handlers

Renaming a variable from uid to userId

Bumping zod from 4.0.1 to 4.0.2

Two years on, the team replaces Drizzle. What happens to the original 0001-use-drizzle-not-prisma.md?

It stays in the repo, body untouched; its Status flips to “Superseded by ADR NNNN,” and a new ADR records the replacement. The historical chain is the value.

It’s deleted, since it no longer describes the current architecture and would mislead a new maintainer.

Its Decision and Consequences are rewritten in place to describe the new ORM, keeping the stable 0001 number.

What’s the single most important quality bar for an ADR’s Consequences section?

It names the real costs, not just the upsides — a Consequences list that’s all wins is a sales pitch, not a record.

It’s exhaustive — every downstream effect across the codebase is enumerated so nothing surprises a future reader.

It quantifies each consequence with a metric so the trade-off can be re-measured later.

Quiz - Docs that live next to the truth

Quiz complete