Chapter 28Lesson 3

AGENTS.md as the next contributor's briefing

The lockfile you just read sits beside one more file you have not opened: a plain Markdown file at the repo root called AGENTS.md. It answers a different question, and it is the question that decides whether the next person to touch this codebase is productive in an hour or lost for a day. When someone clones this repo cold — a teammate on their first morning, or a coding agent you point at the project — what is the one file they should read before anything else, and what has earned a place in it?

In 2026 that file is AGENTS.md. It is an open spec, not a vendor format: the Linux Foundation took it on as a founding project of its Agentic AI Foundation in late 2025, and the major coding agents — Codex, Cursor, Claude Code, Factory — read it natively, with no configuration. A human opens it because it is the first file in the tree alphabetically and it announces itself; an agent opens it because reading AGENTS.md is wired into how it starts work. Either way it is the front door.

Here is the framing this course holds, and it is the whole discipline in one sentence: AGENTS.md is operational onboarding, not architectural prose. It carries the durable facts the next contributor needs to be productive in their first session — what the project is, what it runs on, where things live, the commands they will type — and nothing else. It is not a design document, not a tour, not a sales pitch. The moment it tries to be any of those, it starts to rot, and you will see exactly why by the end of this lesson.

This is the from-scratch project, so this is where AGENTS.md gets written for the course. Every later project chapter carries the pattern forward unchanged. Read it well once here and you will recognize a good one — and smell a bad one — for the rest of the course.

The whole file at a glance

Before we dissect it, look at the entire thing. This is not an excerpt. This is the complete onboarding document for the project, every line of it, and it fits on a single screen:

# AGENTS.md

A static, themed marketing surface — the from-scratch toolchain project that every later project carries forward.

## Stack core (May 2026)

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 (CSS-first) · shadcn/ui · next-themes.

## Repo layout

- `src/app/` — App Router: `layout.tsx`, `page.tsx`, `globals.css`, `_components/providers.tsx`.
- `src/components/` — section components; `src/components/ui/` holds shadcn primitives.
- `src/hooks/` — custom hooks.
- `src/lib/` — `data.ts` fixtures and `utils.ts` (`cn()`).
- `tests/lessons/` — one `Lesson <n>.test.ts` per implementation lesson; `scripts/test-lesson.mjs` runs one file.
- `public/` — static assets.

## Daily commands

- `pnpm dev` — run the dev server.
- `pnpm build` — production build.
- `pnpm check` — Biome format + lint + organize imports (writes).
- `tsc --noEmit` — typecheck.
- `pnpm verify` — Biome CI + typecheck + build (the gate).
- `pnpm test:lesson <n>` — run a single lesson test.

## Conventions

Code style is enforced by `biome.json`; TypeScript strictness by `tsconfig.json`; editor settings by `.editorconfig`.

That length is the lesson. Everything that follows is an explanation of why it is this short — not a list of sections you ought to add. A junior who is handed this file tends to read its brevity as incompleteness and starts padding it out. The opposite instinct is the correct one. Each of the five sections below survives a hard test, and most things you might reach to add do not.

What earns a place

Five sections, and not one wasted. Walk them one at a time. The question for each is the same: would the agent or the new teammate be slower without this line, and is this the most authoritative place for it to live?

A static, themed marketing surface — the from-scratch toolchain project that every later project carries forward.

## Stack core (May 2026)

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 (CSS-first) · shadcn/ui · next-themes.

## Repo layout

- `src/app/` — App Router: `layout.tsx`, `page.tsx`, `globals.css`, `_components/providers.tsx`.
- `src/components/` — section components; `src/components/ui/` holds shadcn primitives.
- `src/hooks/` — custom hooks.
- `src/lib/` — `data.ts` fixtures and `utils.ts` (`cn()`).
- `tests/lessons/` — one `Lesson <n>.test.ts` per implementation lesson; `scripts/test-lesson.mjs` runs one file.
- `public/` — static assets.

## Daily commands

- `pnpm dev` — run the dev server.
- `pnpm build` — production build.
- `pnpm check` — Biome format + lint + organize imports (writes).
- `tsc --noEmit` — typecheck.
- `pnpm verify` — Biome CI + typecheck + build (the gate).
- `pnpm test:lesson <n>` — run a single lesson test.

## Conventions

Code style is enforced by `biome.json`; TypeScript strictness by `tsconfig.json`; editor settings by `.editorconfig`.

The thesis line. One sentence naming what this project is. Without it, a contributor has to infer the domain from filenames — and an agent that guesses wrong wires its first change against the wrong mental model. One sentence is the entire budget here; this is a marketing surface, not a novel.

A static, themed marketing surface — the from-scratch toolchain project that every later project carries forward.

## Stack core (May 2026)

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 (CSS-first) · shadcn/ui · next-themes.

## Repo layout

- `src/app/` — App Router: `layout.tsx`, `page.tsx`, `globals.css`, `_components/providers.tsx`.
- `src/components/` — section components; `src/components/ui/` holds shadcn primitives.
- `src/hooks/` — custom hooks.
- `src/lib/` — `data.ts` fixtures and `utils.ts` (`cn()`).
- `tests/lessons/` — one `Lesson <n>.test.ts` per implementation lesson; `scripts/test-lesson.mjs` runs one file.
- `public/` — static assets.

## Daily commands

- `pnpm dev` — run the dev server.
- `pnpm build` — production build.
- `pnpm check` — Biome format + lint + organize imports (writes).
- `tsc --noEmit` — typecheck.
- `pnpm verify` — Biome CI + typecheck + build (the gate).
- `pnpm test:lesson <n>` — run a single lesson test.

## Conventions

Code style is enforced by `biome.json`; TypeScript strictness by `tsconfig.json`; editor settings by `.editorconfig`.

Stack core, pinned. The load-bearing libraries with versions where the version changes the answer. This is the line that earns its keep most concretely: an agent that does not know it is Next.js 16 will happily hallucinate a pages-router API or a Tailwind v3 config file, and confidently write code that does not belong in this repo. For the later database-backed projects, this is where the Drizzle version would sit.

A static, themed marketing surface — the from-scratch toolchain project that every later project carries forward.

## Stack core (May 2026)

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 (CSS-first) · shadcn/ui · next-themes.

## Repo layout

- `src/app/` — App Router: `layout.tsx`, `page.tsx`, `globals.css`, `_components/providers.tsx`.
- `src/components/` — section components; `src/components/ui/` holds shadcn primitives.
- `src/hooks/` — custom hooks.
- `src/lib/` — `data.ts` fixtures and `utils.ts` (`cn()`).
- `tests/lessons/` — one `Lesson <n>.test.ts` per implementation lesson; `scripts/test-lesson.mjs` runs one file.
- `public/` — static assets.

## Daily commands

- `pnpm dev` — run the dev server.
- `pnpm build` — production build.
- `pnpm check` — Biome format + lint + organize imports (writes).
- `tsc --noEmit` — typecheck.
- `pnpm verify` — Biome CI + typecheck + build (the gate).
- `pnpm test:lesson <n>` — run a single lesson test.

## Conventions

Code style is enforced by `biome.json`; TypeScript strictness by `tsconfig.json`; editor settings by `.editorconfig`.

Repo layout — by directory. One line per directory on what lives there, so the reader skips the discovery step of clicking through the tree to find where components versus hooks versus fixtures live. Notice what it lists: directories, not files. That cut is deliberate, and the next section is where it pays off.

A static, themed marketing surface — the from-scratch toolchain project that every later project carries forward.

## Stack core (May 2026)

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 (CSS-first) · shadcn/ui · next-themes.

## Repo layout

- `src/app/` — App Router: `layout.tsx`, `page.tsx`, `globals.css`, `_components/providers.tsx`.
- `src/components/` — section components; `src/components/ui/` holds shadcn primitives.
- `src/hooks/` — custom hooks.
- `src/lib/` — `data.ts` fixtures and `utils.ts` (`cn()`).
- `tests/lessons/` — one `Lesson <n>.test.ts` per implementation lesson; `scripts/test-lesson.mjs` runs one file.
- `public/` — static assets.

## Daily commands

- `pnpm dev` — run the dev server.
- `pnpm build` — production build.
- `pnpm check` — Biome format + lint + organize imports (writes).
- `tsc --noEmit` — typecheck.
- `pnpm verify` — Biome CI + typecheck + build (the gate).
- `pnpm test:lesson <n>` — run a single lesson test.

## Conventions

Code style is enforced by `biome.json`; TypeScript strictness by `tsconfig.json`; editor settings by `.editorconfig`.

Daily commands. The exact commands a contributor types, so an agent does not default to npm run … and quietly break the pnpm discipline from the previous lesson. pnpm verify is named as the gate — Biome CI plus typecheck plus build, the single “is this shippable?” command. Anyone landing a change runs that one before they are done.

A static, themed marketing surface — the from-scratch toolchain project that every later project carries forward.

## Stack core (May 2026)

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 (CSS-first) · shadcn/ui · next-themes.

## Repo layout

- `src/app/` — App Router: `layout.tsx`, `page.tsx`, `globals.css`, `_components/providers.tsx`.
- `src/components/` — section components; `src/components/ui/` holds shadcn primitives.
- `src/hooks/` — custom hooks.
- `src/lib/` — `data.ts` fixtures and `utils.ts` (`cn()`).
- `tests/lessons/` — one `Lesson <n>.test.ts` per implementation lesson; `scripts/test-lesson.mjs` runs one file.
- `public/` — static assets.

## Daily commands

- `pnpm dev` — run the dev server.
- `pnpm build` — production build.
- `pnpm check` — Biome format + lint + organize imports (writes).
- `tsc --noEmit` — typecheck.
- `pnpm verify` — Biome CI + typecheck + build (the gate).
- `pnpm test:lesson <n>` — run a single lesson test.

## Conventions

Code style is enforced by `biome.json`; TypeScript strictness by `tsconfig.json`; editor settings by `.editorconfig`.

Conventions — pointers, not prose. One sentence, and it restates no rule. It says where the rules live: biome.json for code style, tsconfig.json for strictness, .editorconfig for editor settings. The reader is told where to look, never told the rule itself. This single line is the entire bloat-prevention discipline in miniature — hold that thought for the next section.

1 / 1

Two of those convention files you will meet shortly: tsconfig.json gets its own walkthrough in the next lesson, and biome.json the one after. The .editorconfig is the one you carried in from the editor setup earlier in the course. The point of the Conventions section is that AGENTS.md mentions all three and explains none of them — and that restraint is exactly what we turn to now.

What does not earn a place

The earns-a-place bar matters because AGENTS.md has exactly one failure mode, and it is bloat. This is not a stylistic worry. A 2026 study by Gloaguen and colleagues measured agent task success across real-world repositories and found that LLM-generated context files actively reduced it — the model did worse with the auto-written file than with nothing — and that even hand-written files only helped when they were minimal and precise. A padded AGENTS.md is worse than no AGENTS.md. Every line you add that does not earn its place is dead weight the next reader, human or machine, has to wade through to reach the lines that matter.

So the discipline is as much about what you keep out. Here is the list, and treat it as hard:

Aspirational architecture statements. “This codebase strives to be clean and maintainable.” It tells the reader nothing they can act on and nothing they could verify. Cut it.
Marketing copy. What the product does for customers is the README’s job, or the landing page’s. It is not this file’s.
Tutorials. The agent does not need to be taught Next.js. It needs to know which Next.js this repo runs — which is the one line the Stack core already gives it. A primer in here is pure noise.
Anything that duplicates a more authoritative source. biome.json is the source of truth for formatting rules. The moment AGENTS.md restates a rule from it, you have two copies that will disagree the first time one changes, and the reader cannot tell which one is real. This is precisely why the Conventions section is a single pointer sentence.
Hand-maintained file trees. A tree listing every file ages out the instant someone adds one — and nobody remembers to update prose when they add a file. List directories, which capture the architectural shape and barely change, never individual files, which drift. This is the exact reason the Repo layout section stops at the directory level.
Decisions that belong in an ADR. A meaningful architectural decision — why this database, why this boundary — wants its own Architectural Decision Record, with the context and trade-offs that justified it. AGENTS.md points at the ADR directory if one exists; it never inlines the decision.

To make the smell concrete, here is a fragment of an AGENTS.md that breaks several of these at once. None of it is wrong, exactly — it is all just dead weight, and you can feel the difference against the tight file above:

# AGENTS.md

Welcome! This codebase strives to be clean, maintainable, and a joy to work in.
We believe in best practices and writing code we can be proud of. Our mission is
to delight users with a beautiful, blazing-fast marketing experience.

## Formatting

Always use 2-space indentation and single quotes. Keep lines under 80 characters.
Sort your imports alphabetically and remove unused ones before committing.

## Every file

- src/components/site-header.tsx
- src/components/hero.tsx
- src/components/feature-card.tsx
- src/components/feature-grid.tsx
- src/components/pricing-card.tsx
  (… and so on for every file in the project)

The aspirational opening tells the reader nothing actionable. The Formatting section restates rules that biome.json already owns and will silently diverge from it. The file list was stale the moment Lesson 7 added a component, and no one will keep it current. Three sections, all dead weight, and the file is already harder to use than the thirty-line original.

The discipline

So how do you decide, for any line you are tempted to add? There is a single test, and it is reusable on every doc you write after this one:

Run the test against the file you just read. The thesis line survives a year of feature work untouched. The pinned stack changes only on a deliberate major upgrade, which is exactly the kind of change you want surfaced. The directory layout is stable because directories are stable. The commands are the commands. The conventions pointer never goes stale because it points at the files that own the rules rather than copying them. Five sections, each one durable by construction.

The watch-out follows directly from the test. The file should stay under one screen. If it grows past two screens while you are writing it, that is the signal — not that the project got more complex, but that sections are creeping in that the six-month test would reject. When that happens, the fix is never to keep the file and trim it later. The fix is to ask of each new section whether it would survive five PRs, and cut the ones that would not, on the spot.

A note on naming

You will run into other names for this idea. Some teams keep a CLAUDE.md, some a .cursorrules, some a tool-specific file of their own. The 2026 consensus has settled on AGENTS.md as the open spec, and the course commits to it without hedging. Tool-specific files can sit alongside it, but the rule is that they should reference or re-export AGENTS.md, never carry their own copy — the same duplication discipline you just applied to the Conventions section, one level up. This very course repo does exactly that: its CLAUDE.md is a single line, @../AGENTS.md, that imports the real file rather than forking it. One source of truth, however many front doors point at it.

That is the operational slice of documentation, and it is the slice you need to be productive in this codebase today. The wider doctrine — how a README, an ADR, and a docs site divide the labor, and the discipline for writing each — gets a dedicated chapter later in the course. For now you can read this project’s AGENTS.md, justify every line in it, and judge any other one you are handed against a single test. Next you will open the first of the files it points at — tsconfig.json, and the two owners that share it.

External resources

AGENTS.md — the open format

agents.md

The spec's home page: what the file is for, a worked example, and the FAQ on nested files and precedence.

Codex — custom instructions with AGENTS.md

developers.openai.com

How one agent actually reads the file — the discovery order across global and project scopes, and the byte limit.

Evaluating AGENTS.md (arXiv)

arxiv.org

The paper behind the bloat warning: context files measurably cut agent success and raised cost across a suite of real-world software-engineering tasks.