Agent-readable product specs

An AI agent can only work with the context it receives.

If the product spec hides the real constraint in a meeting, a Slack thread, a Figma comment, or one person's memory, the implementation step becomes guesswork. The agent may still produce code. The problem is that the code can be confidently aimed at the wrong target.

An agent-readable spec does not mean writing for machines instead of people. It means writing the product context clearly enough that a human reviewer, a designer, an engineer, and an AI coding agent can all understand the same scope, states, risks, and proof.

The best spec is not longer. It is more inspectable.

PromiseWhat should be true

The user outcome, product behavior, and trust boundary the change must preserve.

ScopeWhat can change

Routes, components, data sources, files, integrations, and non-goals.

ProofWhat must pass

Acceptance checks, states, fixtures, commands, screenshots, and review focus.

Write the product promise in plain language

The first line should explain what must become true for the user or team.

The questions I would use are:

• What is the promise?
• Who depends on it?
• What breaks trust?
• How will we know it works?

The mistake is opening with implementation detail before naming the outcome. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a one-sentence product promise at the top of the spec. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

For product specifications that need to help humans and AI agents understand goals, constraints, states, data sources, acceptance criteria, and verification without hidden context, I want the artifact to be useful before it becomes presentable. It should help someone make a decision, review the risk, or explain the tradeoff without needing a private meeting.

The proof is a change that stays connected to user value. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

Make non-goals visible

AI tools are good at expanding scope unless the boundary is explicit.

The questions I would use are:

• Which refactor is out of scope?
• Which behavior must stay stable?
• Which files should not move?
• Which cleanup can wait?

The mistake is letting a small bug become a broad rewrite. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a non-goals list beside the task. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

This is where AI-ready product specification matters. The work should not depend on taste alone; it should leave a small operating model that another designer, engineer, or reviewer can reuse.

The proof is a PR reviewers can understand quickly. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

WhyDecision pressure

The user problem, business reason, support issue, or system risk.

WhatBehavior

The states, copy, data, permissions, analytics, and edge cases.

HowConstraints

Known patterns, libraries, files, migration rules, and QA expectations.

Name data ownership

A spec should say where truth comes from and what freshness means.

The questions I would use are:

• Which system owns the data?
• Can values be stale?
• What happens if data is missing?
• Who can change it?

The mistake is asking the implementation to infer data rules from UI copy. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a source-of-truth table. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

For product specifications that need to help humans and AI agents understand goals, constraints, states, data sources, acceptance criteria, and verification without hidden context, I want the artifact to be useful before it becomes presentable. It should help someone make a decision, review the risk, or explain the tradeoff without needing a private meeting.

The proof is fewer wrong assumptions in generated code. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

List states before screens

Screens are easier to generate than complete states. The spec should force the hard cases into view.

The questions I would use are:

• What is loading?
• What is empty?
• What can fail?
• What is restricted?

The mistake is only describing the happy path. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a state checklist with expected copy and actions. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

This is where AI-ready product specification matters. The work should not depend on taste alone; it should leave a small operating model that another designer, engineer, or reviewer can reuse.

The proof is a product surface that survives real conditions. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

DoExpected work

Implement the narrow behavior, preserve existing patterns, and verify the route.

Do notNon-goals

Avoid unrelated refactors, dependency churn, schema changes, or redesigns.

AskEscalation

Flag missing credentials, ambiguous data ownership, or conflicting acceptance criteria.

Give the agent local conventions

The best spec points to existing patterns instead of asking the agent to invent a new style.

The questions I would use are:

• Which component is similar?
• Which helper should be reused?
• Which styling convention matters?
• Which route proves the pattern?

The mistake is allowing generated code to introduce a new private style. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a local-pattern reference list. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

For product specifications that need to help humans and AI agents understand goals, constraints, states, data sources, acceptance criteria, and verification without hidden context, I want the artifact to be useful before it becomes presentable. It should help someone make a decision, review the risk, or explain the tradeoff without needing a private meeting.

The proof is implementation that feels native to the repo. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

Turn acceptance criteria into checks

Acceptance criteria should be written so they can be verified.

The questions I would use are:

• What command should run?
• Which route should load?
• Which state should be inspected?
• Which artifact should exist?

The mistake is writing acceptance criteria as vague intentions. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a verification checklist with commands and browser paths. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

This is where AI-ready product specification matters. The work should not depend on taste alone; it should leave a small operating model that another designer, engineer, or reviewer can reuse.

The proof is a reliable review receipt. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

Include review focus

A good spec tells reviewers where to spend attention.

The questions I would use are:

• What is risky?
• What should not regress?
• What changed in data or routing?
• Which screenshot or fixture matters?

The mistake is making reviewers rediscover risk from the diff. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a reviewer-focus note. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

For product specifications that need to help humans and AI agents understand goals, constraints, states, data sources, acceptance criteria, and verification without hidden context, I want the artifact to be useful before it becomes presentable. It should help someone make a decision, review the risk, or explain the tradeoff without needing a private meeting.

The proof is faster and better code review. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

Keep screenshots tied to decisions

Visual references are useful when they explain hierarchy, state, or behavior.

The questions I would use are:

• What should the screenshot prove?
• Which part is flexible?
• Which part is exact?
• Which responsive state matters?

The mistake is using images as decoration without implementation meaning. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is an annotated screenshot brief. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

This is where AI-ready product specification matters. The work should not depend on taste alone; it should leave a small operating model that another designer, engineer, or reviewer can reuse.

The proof is less ambiguity between design and code. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

Ask for a receipt in the prompt

The implementation prompt should request a summary that maps back to the spec.

The questions I would use are:

• What changed?
• What was checked?
• What was skipped?
• What needs a human decision?

The mistake is accepting confident generated summaries without evidence. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a required PR receipt format. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

For product specifications that need to help humans and AI agents understand goals, constraints, states, data sources, acceptance criteria, and verification without hidden context, I want the artifact to be useful before it becomes presentable. It should help someone make a decision, review the risk, or explain the tradeoff without needing a private meeting.

The proof is a clearer handoff from agent to reviewer. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

Make the spec reusable

The spec format should improve each time it catches a missing detail.

The questions I would use are:

• Which field prevented rework?
• Which field was ignored?
• What was missing?
• Should the template change?

The mistake is treating every AI task as a one-off prompt. That mistake makes the work look finished while hiding the decision that actually matters. It can make a portfolio page louder, a PR harder to review, or a product surface more fragile than it needs to be.

The artifact I want is a spec retrospective note. It should be plain enough to inspect and specific enough to be useful. If the artifact cannot show the constraint, the decision, and the proof, the story is probably still too vague.

This is where AI-ready product specification matters. The work should not depend on taste alone; it should leave a small operating model that another designer, engineer, or reviewer can reuse.

The proof is a workflow that compounds instead of repeating mistakes. I would rather show a narrow proof that survives questions than a broad claim that only sounds impressive. A hiring manager should be able to ask how I know, what I owned, what changed, and what I would do differently next time.

What I would show in the work

The public version should show the working artifacts, not only the final opinion. For product specifications that need to help humans and AI agents understand goals, constraints, states, data sources, acceptance criteria, and verification without hidden context, I would include the matrix, the state map, the review checklist, and the before-and-after decision path. Those artifacts make the work feel authored because they reveal how the decision was made.

I would also include what I did not do. That is often where judgment is clearest. Not every useful idea belongs in the first version. Not every dashboard needs live sync. Not every component needs a new prop. Not every AI suggestion belongs in the PR. Naming the boundary helps the reader trust the result.

The page should make the work inspectable without turning into internal documentation. I want enough specificity for an engineering manager to ask serious follow-up questions, and enough restraint that the story still reads like product judgment instead of a dump of process artifacts. The best version makes the artifacts feel inevitable: this was the pressure, this was the decision, this was the receipt, and this is why the outcome is believable.

ChangedFiles and behavior

The implementation summary tied back to the original scope.

CheckedVerification

Build, tests, browser, migration, assets, accessibility, or live QA.

LeftFollow-up

Known caveats, deferred states, owner, and trigger for the next pass.

Downloadable companion

This topic deserves a companion resource: an agent-readable product spec template with product promise, scope, non-goals, data sources, states, acceptance checks, QA receipts, and review instructions. It should be useful as a working file, not a decorative download. The resource should help someone repeat the review, pressure-test the decision, and carry the same quality bar into their own product work.

I would keep it concise: one page if possible, with fields for context, constraint, decision, evidence, owner, and follow-up. The value is not the file format. The value is that the artifact turns the article into something someone can use.

Review checklist

Before publishing this work, I would run a short review against the same standard I use for product changes:

• Is the product pressure concrete?
• Is my ownership clear?
• Is the system constraint named?
• Is there at least one artifact that proves the decision?
• Does the artifact show a real tradeoff?
• Is the metric or signal honest about its limits?
• Are support, operations, accessibility, or release risks named when relevant?
• Does the writing explain what I intentionally left out?
• Can a recruiter skim the point quickly?
• Can an engineer ask a deeper technical question?
• Does the downloadable resource make the idea reusable?
• Would I be comfortable defending the claim live?

That checklist keeps the work from becoming a polished but vague page. It also protects the voice. The goal is not to sound like a process manual. The goal is to make the product judgment visible enough that a hiring team can trust the story.

Implementation notes

The implementation version of this idea should be small enough to ship and specific enough to prove. I would start by naming the route, artifact, owner, and verification path before adding polish. If the work touches content, I would check the source body, generated route, metadata, sitemap, and social image. If it touches UI, I would check desktop, mobile, long content, empty state, keyboard path, and the most likely failure state. If it touches data, I would name the source of truth, freshness, migration path, and what support or product should see after launch.

That implementation note matters because AI-ready product specification can drift when the work moves from idea to code. A good article can describe the principle, but a good product change needs the boring details: filenames, states, commands, rollback, ownership, and the reason the first version is intentionally narrow.

I would also write the follow-up before shipping. Follow-up is not a sign that the work is incomplete; it is a sign that the boundary is known. The first version should solve the risky problem, prove the pattern, and leave the next step visible. That is how small teams move quickly without pretending every release is final.

For portfolio proof, these implementation notes are useful because they make the story harder to fake. They show that I understand the difference between a good idea, a shippable version, and a maintainable system. They also give an interviewer concrete places to dig: why this scope, why this artifact, why this verification path, and what changed after the first release.

Case-study packaging

If this became a Work section detail, I would package it as a small evidence stack. The top should explain the product pressure in plain language. The middle should show the artifact and the operating decision it supported. The bottom should show the verification and the follow-up. That structure keeps the story from becoming either a pretty screenshot or a private engineering note.

The captions matter here. A caption should not say "dashboard view" or "component states" and stop there. It should explain what the reader is supposed to learn: this matrix shows why the first version stayed narrow, this state map shows where recovery mattered, this QA note shows how the release was proved, or this event taxonomy shows how product language became measurable.

I would keep the packaging honest by including one caveat. The caveat might be a metric limitation, a data freshness issue, a rollout boundary, a support dependency, or a follow-up that intentionally stayed out of scope. That caveat does not weaken the case study. It makes the judgment feel real.

The final test is whether the page creates a better conversation. If the artifact helps someone ask a sharper question about product judgment, implementation detail, or release proof in real live interviews together, it belongs in the story.

Interview angle

In an interview, I would explain this through agent-readable specs as a shared operating contract between product judgment and AI-assisted implementation. The story should start with the product pressure, then move into the system constraint, the artifact, and the proof. That order keeps the answer grounded. It also gives the interviewer several places to go deeper: data, frontend architecture, design systems, support, migration, accessibility, or release process.

The strongest version of the answer includes a tradeoff. I want to be able to say what I chose, what I left alone, and how I knew the work helped. That is more credible than presenting every project as a clean win.

The hiring signal

Agent-readable specs are a hiring signal because they show I can turn ambiguity into buildable context for both teammates and AI tools.

That is the level I want this site to communicate. The work should show taste, but it should also show operating judgment. It should make me look like someone who can enter a real product system, understand the messy middle, ship the useful version, and leave enough proof for the next person to trust it.