Count the actual readers of the last PRD you wrote. A couple of engineers, skimming. Your designer, the relevant sections. And then the readers nobody counts: the coding agent that turned it into a draft implementation, the answer engine that will decide whether a customer ever finds the resulting docs, and the three agents in your own fleet running off briefs you wrote last quarter.
Half your readers are machines now. And here is the part that took me too long to accept: writing for machines, writing that a machine executes faithfully, is a distinct craft from writing that persuades a human. The persuasion craft still matters, I made the case in storytelling is a PM core skill. But it does not transfer. Some of the best persuasive writers I have worked with produce specs that agents mangle, because the moves that charm a human reader are exactly the moves that scatter a model.
The short version
Three machine audiences read PM writing now, and each rewards something different: coding agents reward unambiguous acceptance criteria and labeled examples, answer engines reward extractable, entity-rich blocks, and your own agent fleet rewards stable schemas and brief files. The craft shift is from prose PRD to eval-set-plus-brief, because examples pin down what adjectives never could, a discipline the handbook covers in The Eval Is the Spec. Prompt hygiene means versioning prompts like code, per Prompt Ops. And the only eval of your writing that matters is the cold-read test: hand the artifact to a model with zero verbal context and measure the gap between what comes back and what you meant.
The three machine audiences
Coding agents. They read your spec and produce an implementation, and they are spectacularly literal. A human engineer resolves "handle errors gracefully" by asking what graceful means here, or by knowing your product. An agent resolves it statistically, and differently each run. What coding agents reward: numbered acceptance criteria that are individually checkable, labeled examples of correct and incorrect output, and explicit statements of what is out of scope. Every ambiguity you leave in is a coin flip you scheduled for execution time.
Answer engines. AI Overviews, Perplexity, ChatGPT with browsing. They decide whether customers find you, and they do not read pages the way Google's crawler ranked them. They extract blocks: a self-contained summary, a quotable Q&A pair, a sentence with named entities in it. If your product docs and marketing pages contain no extractable blocks, you are invisible to the channel that is replacing search. More on this below, without the cargo cult.
Your own fleet. The agents running your call triage, your competitive sweeps, your draft generation. They read your briefs every single run. What they reward is stability: a brief file with a consistent schema, named sections, examples that do not drift. Every time you rewrite the brief from memory in a chat window instead of maintaining the file, you are A/B testing your own infrastructure by accident.
The spec that executes: from prose PRD to eval-set-plus-brief
The deepest change in my own writing practice over the last two years: the prose PRD is now the cover letter, and the eval set is the spec.
An eval set is a table. Inputs in one column, expected outputs in the next, and for the interesting rows, a note on why. "Concise and professional summary" is an adjective pile; a model will give you a different reading of it every run. Three labeled examples (one great, one merely acceptable, one failure with the reason it fails) pin the target in a way no adjective can. Examples beat adjectives, every time, because examples are checkable and adjectives are vibes.
Edge cases get promoted from afterthought to first-class content. In a prose PRD, edge cases live in a sad bullet list near the end that nobody reads. In an eval set, the edge cases are rows, equal citizens with the happy path, and the agent (or the engineer, or the future you) gets graded on them. The five-row eval template is the smallest honest starting point: five rows is enough to expose whether you actually know what you want.
The brief sits on top: a half page of stable context. What the product is, who the user is, what the constraints are, what good looks like in one paragraph. Brief plus eval set replaces twelve pages of prose, executes more faithfully, and takes less time to write once the reflex forms. The full discipline is in The Eval Is the Spec.
Prompt hygiene is writing craft
The prompts and briefs running your fleet are published writing. They deserve the same hygiene as code, and at every company I have watched adopt agents, they get it last.
The pattern that works is the brief file. One named, versioned document per agent or workflow, holding the durable context: role, product, audience, output schema, examples. Every run references the file. The file lives in a repo or a shared folder with history, not in someone's chat scrollback.
Changes get dated. Meaningful changes get checked against a small eval set before they ship, exactly like a code change gets tested. When an agent's output drifts, the first question is "what changed in the brief and when," and with versioning that question takes thirty seconds instead of an archaeology session. The operational detail is in Prompt Ops; Anthropic's prompt engineering docs are the canonical reference for the prompt structure itself, and unlike most of the genre they are maintained against the actual models.
One writing-level note from that documentation worth internalizing: structure beats cleverness. Clear sections, explicit output formats, examples in labeled blocks. The model does not need to be charmed. It needs to be unambiguous.
GEO without the cargo cult
Generative engine optimization has already grown its own snake-oil industry, so here is the small honest core of it for PMs:
- An extractable summary block near the top. Three to six sentences that stand alone, carrying the page's main claim and its named entities. Answer engines lift whole blocks; give them one worth lifting.
- FAQ pairs that stand alone. Each answer should make sense quoted with no surrounding page. This is also just good docs writing, which is the tell that GEO done right is mostly writing done right.
- Named entities over vague references. "Our integration with Salesforce" is retrievable; "our CRM integration" is fog. Engines resolve entities, so name them.
Why a PM should care beyond the marketing site: product documentation gets read by the same engines, and an answer engine paraphrasing your docs badly becomes a support ticket, or a churned trial. Writing docs in extractable blocks is now a product quality decision, not a content team preference.
The cold-read test
Every craft above reduces to one eval, and it is the only one I trust: the cold read.
Take your spec, brief, or prompt. Hand it to a model with zero verbal context. No meeting memory, no Slack thread, no "you know what I mean." Compare what comes back to your intent. The gap is your score.
The test is brutal because it removes the shared context that makes ambiguous writing look fine inside a team. Your engineer parses "make it feel fast" because they sat in the meeting. The cold read has no meeting. Whatever survives the cold read will survive every reader, human or machine. I now run it before any handoff that matters, and it has the same relationship to my writing that the retelling test has to my memos: humbling, and the fastest teacher available.
The 4-week practice plan
Week 1: cold-read your last PRD. Paste it into a model with no context and ask it to implement or summarize the requirement. Catalog the gaps. Each gap is an ambiguity you would have paid for at execution time.
Week 2: convert one spec to eval-set-plus-brief. Take a live, small feature. Write the half-page brief and a ten-row eval set including three edge cases. Hand both to whoever (or whatever) is building it, and notice what questions stop arriving.
Week 3: put your fleet's briefs under version control. Collect the prompts running your agents into named files in one place with history. Date the current versions. Pick your most-used agent and write a five-row eval for its output.
Week 4: GEO one page. Take one product doc or blog post you own. Add the extractable summary block, three standalone FAQ pairs, and named entities. Then cold-read it: ask a model, given only that page, to answer a customer question. Score the answer.
The resource review, opinionated
Anthropic's prompt engineering documentation and the evaluation guide. The canonical pair. The prompt docs for structure, the eval guide for the grading mindset. Read both in an afternoon; they are short and free, and they obsolete most paid prompt courses.
Simon Willison's blog. The running practitioner log of this whole field. Not a course, a diary of someone testing everything in public. Skim weekly; his write-ups on what models actually do with instructions are the field notes the textbooks do not have yet.
Hamel Husain and Shreya Shankar's AI Evals course. Worth it if evals become a core part of your job rather than a writing technique. For most PMs, the handbook chapter plus the Anthropic guide is enough to start.
What to skip: prompt marketplaces and "200 magic prompts" packs. They sell incantations, and the entire lesson of this post is that there are no incantations, only unambiguous context, examples, and a test loop. A magic prompt without your brief and your eval set is someone else's context wearing a costume.
Pick one thing this week
Run the cold read tonight. One artifact, the spec or prompt you most recently shipped, into a model with zero context. Read what comes back next to what you meant. The gap you find is your curriculum for the next month.
Sources: Anthropic prompt engineering documentation, Anthropic evaluation guide, Simon Willison, Hamel Husain & Shreya Shankar, AI Evals.
Further reading
- The Eval Is the Spec, the full discipline behind eval-set-plus-brief
- Prompt Ops, running prompts like infrastructure
- Storytelling Is a PM Core Skill, the human-audience half of the writing stack
- Simon Willison's weblog, the practitioner log worth a weekly skim
Frequently asked
What does writing for machines mean for PMs?+
Three machine audiences now read PM writing: coding agents that turn specs into implementations, AI answer engines that decide whether customers find your product, and the PM's own agent fleet running off briefs and prompts. Each rewards different writing. Writing that a machine executes faithfully is a distinct craft from writing that persuades a human, with its own failure modes, mostly around ambiguity.
Why do examples beat adjectives in specs for AI?+
Because a human reader resolves 'the summary should be concise and professional' by asking or guessing from context, while a model resolves it statistically, differently each run. Three labeled examples (one great output, one acceptable, one failure with the reason it fails) pin down what the adjectives never could. The eval set, a table of inputs with expected outputs, is the spec format that survives machine readership.
What is the cold-read test?+
Hand your spec, brief, or prompt to a model with zero verbal context, no meeting memory, no Slack thread, and compare what comes back to your intent. The gap is your score. It is the only honest eval of machine-facing writing, because it removes the shared context that makes ambiguous writing look fine to your teammates. Run it before every handoff that matters.
What is GEO and why should PMs care?+
Generative engine optimization: writing so AI answer engines (AI Overviews, Perplexity, ChatGPT browsing) can extract and cite your content. The mechanics are simple: a short extractable summary block near the top, FAQ pairs that stand alone as quotable answers, and named entities instead of vague references. It matters beyond marketing because product docs get read by the same engines, and an answer engine misquoting your docs becomes a support ticket.
How should PMs version their prompts?+
Like code. Prompts and briefs live in files, in a repo or shared folder, not in chat history. Changes get dated and noted, and meaningful changes get checked against a small eval set before they ship. The pattern that works is the brief file: a stable, named document holding the context an agent needs (product, audience, constraints, examples), referenced by every run instead of re-typed.
Does writing for machines replace writing for humans?+
No, it sits beside it. Persuasion, narrative, and the answer-first memo still decide what gets funded; that craft is covered by storytelling. Writing for machines decides whether what got funded gets built as intended, found by customers, and run reliably by agents. Strong PMs now need both, and the failure mode is excelling at one while the other quietly leaks value.
Comments (0)
Sign in with LinkedIn to leave a comment.
Sign in with LinkedIn