Writing for an agent

A brief an agent runs is not documentation for a person. A person reads a narrative and forms intent; an agent reads links and decisions and acts. So the brief front-loads the exact sources first.

The orientation dives argued the brief deserves a layer and named its five parts. This module goes deeper than either, on the first idea: how to write for a machine reader at all. Links first, prose second, every reference exact — the llms.txt form the Portal's real f6.1.llms.md takes. Pick a reader mode on the right to see which section each reads first; three dives then teach the convention end to end.

A machine reader The shape it takes The three dives References

Reader mode · person doc vs agent brief

Agent brief — first section read: References (links). A machine brief opens with the exact sources, not a narrative.

A machine reader acts on links, not narrative

The chapter entered with the A4 spec — correct by definition — and the orientation dives framed the brief that wraps it: A5 · Why a brief layer argued a spec is not, on its own, runnable, and A5 · What the chapter covers named the brief's five parts, references first. This module takes up that first idea and goes deeper than either: how to write for a machine reader at all.

A person and an agent read a document differently, and the difference sets the form. A person reads a narrative top to bottom, builds a mental model, and infers what to do. An agent reads the links and the decisions and acts on them in order. Write a brief as a story and the agent must read a requirement before it has read the source that requirement depends on — and so reads it blind. Write it links-first and the agent reads every source first, then implements. The convention has a name: the llms.txt form — a links-first, machine-readable document an agent reads before any prose.

The reader-mode figure above performs the comparison on the Portal's real f6.1.llms.md: in agent mode the first section read is References (links); in person mode it is the narrative. The convention is not a stylistic preference. It is a consequence of who reads the document and how.

The shape it takes on the Portal

The Portal's web bootstrap is briefed in a real machine brief, f6.1.llms.md — the brief for the F6.1 Phoenix request lifecycle rung in the companion course. Its top-of-file blockquote states the reading order plainly:

> Read the references first, satisfy the requirements, build in
> task-topology order, and close each agent story on its gate.
> This brief is self-contained.

The file's structure follows that instruction. A ## References heading comes first, and its six entries are exact links — the Phoenix endpoint hexdocs, the router hexdocs, the controller hexdocs, the Plug docs, the F0 design system, and the upstream Portal facade contract — placed before any requirement prose. The agent reads all six sources, then acts on the numbered requirements. The content figure below counts how many of the six are front-loaded before any prose: select “moved” to strip the front-loading and watch the count fall to zero.

Links front-loaded · before any requirement prose

f6.1.llms.md — references front-loaded before any requirement: 6 of 6. The agent reads every source first, then acts.

the principle

A machine reader acts on links and decisions, not narrative; write the sources first, and keep only the prose that carries a decision.

on the Portal

f6.1.llms.md opens with a References block of exact hexdocs plus the Portal facade contract, then the requirements F6.1-R1–R8 that cite them.

Write the brief the way an agent reads it — exact links first, prose only where it carries a decision.

The three dives

Three dives teach the convention in order: links first → every reference exact → the shape of a machine brief. The first front-loads the sources; the second names each precisely enough that the agent reads the right thing; the third assembles the whole llms.txt skeleton. A5.1.1 starts.

A5.1.1dive 1/3

Links first

An agent reads the sources before any narrative; the brief front-loads exact links, so a reference is never a thing the agent has to hunt for or guess.

A5.1.2dive 2/3

Every reference exact

Every source is named precisely enough that the agent reads the right thing, not an approximation — an exact reference is a contract, a loose one an invitation to improvise.

A5.1.3dive 3/3

The shape of a machine brief

The llms.txt form: a links block, then the parts an agent acts on, narrative removed — the same skeleton every f6.N.llms.md follows.

The three dives carry the convention; the next module — A5.2 · References and requirements — fills the first two parts of the brief with the sources the agent reads and the numbered, testable requirements that cite them. Return to the A5 chapter landing to continue.

References

The convention this module teaches, the agent guidance behind it, and where the spec it wraps and the rung it briefs live in the courses.

Sources

llmstxt.org — The /llms.txt convention — a links-first, machine-readable document format an agent reads before prose; the convention the brief follows.
Anthropic — Building effective agents — how to brief and structure a coding agent over a well-specified task.
Hunt, A. & Thomas, D. — The Pragmatic Programmer — the tracer-bullet discipline of turning a fixed contract into a built increment.

Related in this course

A5 · The agent brief — the chapter this module opens.
A5 · Why a brief layer — why a spec is not, on its own, runnable by an agent.
A5 · What the chapter covers — the five parts of an .llms.md.
Companion · Phoenix request lifecycle (F6.1) — the real rung whose f6.1.llms.md this module grounds on.
Companion · Phoenix (F6) — the chapter of f6.N.llms.md briefs.