DEV Community: BrainGrid

The Best Spec-Driven Development Tools in 2026 (Tested & Compared)

Nico Acosta — Wed, 12 Aug 2026 11:23:45 +0000

Adding a spec-driven development tool does not make your development spec-driven. Most of them just generate a folder of markdown, hand it to the same agent that was already guessing, and call the ceremony a method.

That gap is exactly what a builder in r/AI_Agents was circling this week when the whole "loop engineering" idea got picked apart. His verdict on the wave of new agent-workflow tooling was blunt: Cron jobs with a shiny new UI are still cron jobs. He is right about most of them, and the same critique lands on half the "spec-driven" category. A markdown template with a shiny new UI is still a markdown template.

So which of these tools actually change the outcome, and which just add paperwork? We use spec-driven development to ship our own product every day, so this is the field guide we wish existed: what each tool really does, who it fits, and the one axis that separates the ones that work from the ones that generate homework.

The hypothesis: the spec is the easy half

Here is the claim this guide is built to test. The value of a spec-driven development tool is not in writing the spec. It is in what happens after.

Writing a spec has never been the hard part. In an r/LLMDevs thread this week on where the real bottleneck sits, one builder described his workflow, having the AI write explicit input/output/behavior contracts for every function before implementing anything, and added the line that says everything: 90% of vibe coders still don't do it. Someone asked what prompt would backfill that discipline into an existing codebase. The reply was two words: it's called spec-driven development.

That is the tell. People reinvent this practice from scratch, hit the wall, and only then learn it already has a name and a category of tools. The category is real. But most of the tools stop at the easy half. They help you produce a beautiful spec, then hand the spec to the same coding agent that will report "done" the moment it stops running, whether or not the build matches a single line you wrote.

The tools worth your time are the ones that close the loop: spec, build, and then verify the build against the spec before anyone calls it done. Keep that axis in mind as we go through them.

GitHub Spec Kit

Spec Kit is the reference implementation of the category, an open-source CLI toolkit from GitHub that walks your coding agent through a structured pipeline: Constitution, Specify, Clarify, Plan, Tasks, Implement. It writes markdown templates that plug into Claude Code, Copilot, Gemini CLI, and most other agents, so it is agent-agnostic by design.

Its strength is also its ceiling. Spec Kit is a scaffolding for the workflow, not a product that runs it for you. You get discipline and a shared vocabulary, which is genuinely valuable, but you are still driving the whole thing from a terminal, and the verification step is whatever your agent decides to do on its own. It fits engineers who want structure without a new IDE. If you have a repo and you are comfortable in the CLI, start here. We wrote a full Spec Kit walkthrough for an existing project if you want the hands-on version.

OpenSpec

OpenSpec is the lightweight answer to Spec Kit's ceremony. It breaks a high-level prompt into granular, ordered task lists and keeps a set of markdown files in sync as the agent works, so it stays out of your way. If Spec Kit felt like too much process for a solo project, OpenSpec is the trimmed-down version that still gives the agent a plan to follow instead of a vibe.

The trade-off is that lighter also means less opinionated about what "done" means. You get a cleaner task breakdown and less overhead, and you give up the fuller lifecycle framing. It fits solo builders and small teams who want just enough structure to stop the agent from wandering. We put it head to head with Spec Kit in OpenSpec vs Spec Kit vs BrainGrid if you want the direct comparison.

Kiro (and the spec-driven IDE camp)

Kiro, Amazon's spec-driven IDE, represents the other end of the spectrum: a full VS Code-style environment built around specs. You describe requirements in natural language, Kiro generates user stories, design docs, and steering files, and you check off implementation against them inside the editor. It is the most "product" of the open toolkits, with interactive UI to track features from requirement to code.

The cost is lock-in and weight. You are adopting an IDE, not a workflow you can bolt onto the tools you already use. For a developer who wants a native, self-contained spec-driven environment, that is a fair trade. For a non-technical founder, an IDE is still an IDE, with all the friction that implies. We compared its philosophy to ours in Kiro vs BrainGrid.

BMAD and the framework crowd

BMAD-METHOD and the growing shelf of SDD frameworks (Spec Kitty, Agent OS, Tessl, and more) are for people who want to assemble their own pipeline from parts. They give you agent personas, planning phases, and templates you wire together yourself. Powerful in the right hands, and a rabbit hole in the wrong ones.

This is where a warning belongs. The moment picking a framework becomes its own project, the tool has failed at its job. If you have spent a weekend comparing steering-doc syntaxes instead of shipping a feature, you are shopping for tools instead of building. The framework crowd fits engineers who genuinely enjoy building their own harness. Most builders do not, and should not have to.

The contract-and-API-spec category

There is a second, older meaning of "spec-driven" that shows up in the same searches: API-first tools like SwaggerHub, Specmatic, and TypeSpec. These treat an OpenAPI or contract file as the source of truth and enforce it in CI before code ships. They are excellent, and they solve a different problem: the contract between services, not the requirement behind a feature. If your pain is "my agent keeps breaking the API between the frontend and backend," this is your aisle. If your pain is "my agent built the wrong thing confidently," it is not.

Where BrainGrid fits

Everything above is strong at producing a spec. The question our own hypothesis forces is what happens next, and that is where we built BrainGrid to be different.

You describe an idea in plain English, and the Planning Agent turns it into a structured requirement with acceptance criteria, data models, and designs, asking clarifying questions and pushing back when the intent is vague. That is the part most tools stop at. Then the Builder Agent takes over: it runs the build against that spec, either in a managed cloud sandbox with a live preview or in your own GitHub repo through Claude Code, Cursor, or Codex over MCP. And then the part almost nobody automates happens. Verification checks the build against every acceptance criterion, and the feature is not done until the evidence says it matches what you asked for.

That closes the loop the r/codex thread was worried about this week, where builders debated whether smarter agents still need review and landed on a hard truth: they do not own mistakes, so someone still has to prove the work is right. A spec you can verify against is how you prove it without reading every line of code yourself. The spec is not paperwork. It is the standard the build gets checked against.

Old way vs new way

The difference between using a spec-driven tool and actually doing spec-driven development comes down to one habit.

Old way: "Build me a CRM with React." The agent generates something, reports success, and you find out at feature four that the auth logic conflicts with the state management it wrote in feature two.

New way: a requirement that says a contact-management view displays contacts in a sortable table with name, company, and last-contacted date; clicking a row opens a detail panel; only authenticated users can access it; unauthenticated users redirect to /login. Every one of those lines is a criterion the build can be checked against. The agent still moves fast. It just cannot quietly ship the wrong thing.

The tool that generates the second version for you is doing useful work. The tool that also verifies the build against it is doing the whole job.

What changes for you

If you are building a SaaS product with an AI coding agent right now, here is the concrete implication. Adopting any tool on this list will make your third and fourth features less likely to break, because the agent finally has a plan and a shared definition of the feature. That alone is worth it.

But do not stop at the spec. The failure mode this whole category exists to fix is not "the agent had no plan." It is "the agent said done and it wasn't." Pick your tool on the verification axis. If two tools produce equally good specs, the one that checks the build against the spec is the one that saves you the afternoon you would have spent discovering the gap in production.

And the honest trade-off: spec-driven development is slower on feature one. You are front-loading the thinking. The payback comes at feature five, when your codebase is still coherent and your agent is still building the thing you asked for instead of the thing it guessed. If you are shipping a one-day throwaway, skip all of it and vibe. If you are building something real, the spec is the cheapest insurance you will buy.

FAQ

What is spec-driven development?

Spec-driven development is a workflow where you write a structured specification, requirements, constraints, and acceptance criteria, before an AI agent writes code, and the spec becomes the source of truth the build is measured against. It replaces "prompt, hope, and patch" with "specify, build, and verify." The point is not the document. It is that a clear spec gives the agent something concrete to build toward and something concrete to be checked against. We cover the full method in Spec-Driven Development: Ship Reliable Software Faster with AI.

What are the best spec-driven development tools?

For agent-agnostic structure from the CLI, GitHub Spec Kit is the reference tool. For a lighter task-focused workflow, OpenSpec. For a full spec-driven IDE, Kiro. For assembling your own pipeline, frameworks like BMAD. For API contracts specifically, SwaggerHub or TypeSpec. And for a workflow that plans, builds, and then verifies the build against acceptance criteria in one loop, BrainGrid. The right pick depends on whether you want scaffolding you drive yourself or a system that closes the loop for you.

What is the difference between spec-driven development tools?

They differ mainly on two axes: how much they do for you, and whether they verify the result. Spec Kit and OpenSpec are scaffolding you drive from a terminal. Kiro is a full IDE. Framework kits like BMAD are parts you assemble. Most of them stop after generating the spec and planning the work. The meaningful divide is verification: does the tool check the finished build against the spec, or does it trust the agent's own "done"?

What is the difference between BDD and spec-driven development?

Behavior-driven development (BDD) focuses on describing expected behavior as executable scenarios ("given, when, then") that become automated tests. Spec-driven development is broader: the spec covers requirements, constraints, data models, and acceptance criteria, and drives both the build and its verification, not only the test suite. BDD scenarios can live inside a spec-driven workflow as one form of acceptance criteria. SDD is the wider frame; BDD is one technique for expressing part of it.

Do I need a spec-driven tool, or can I just write a good prompt?

A single good prompt works for a single small feature. It stops working once a project has many moving parts, because nothing carries your intent from one session to the next and nothing checks the result. A spec-driven tool exists to make that intent durable and verifiable. If you keep re-explaining your app to the agent every session, or keep discovering broken features you thought were done, you have outgrown prompting and the category is for you.

BrainGrid is the AI Product Planner that turns your idea into a spec your coding agent can build against, then verifies the build matches it before you call it done. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

How to Verify AI-Generated Code (Before It Breaks Production)

Nico Acosta — Tue, 11 Aug 2026 11:17:15 +0000

The agent said it was done. It ran the app, showed you a green result, and wrote a tidy summary of what it built. None of that tells you whether the code does what you asked. Those are two different questions, and the gap between them is where production breaks.

Here is the hypothesis this guide rests on: verifying AI-generated code is not reading it line by line, it is checking it against a target you defined before the build. The more of your building an agent does, the less "I read it and it looked fine" scales, and the more you need a repeatable way to prove the change matches intent. The good news is that this is a learnable process, not a talent. The bad news is that almost nobody is taught it, so most builders default to eyeballing a demo and hoping.

"It runs" is not "it works"

An AI coding agent optimizes for the shortest path to something that looks complete. Ask for a login flow and it will build the happy path, run it once, watch a user log in, and call that done. It is not lying. It genuinely did produce a thing that works, for the one case it tried. What it did not do is check the wrong password, the expired session, the empty email field, or the second user whose data must not leak into the first user's account. Those are the cases that surface in production, at the worst possible time, in front of a real person.

This is the distinction Stanislav Sorokin named cleanly, writing about agent runs on X:

Completion is a runtime event. Success is a verified state.

That is the whole problem in nine words. The agent stopping is a fact about the loop. Whether it succeeded is a separate fact that has to be established on purpose, and the agent will not establish it for you unless you told it what success means. Verification is how you turn "it stopped" into "it works," and it is the step the demo quietly skips.

The five checks that actually catch things

When developers on r/ExperiencedDevs compared notes on verifying AI code, the useful answers were not "read every line." They were specific, repeatable checks. Here is the shortlist that catches the most, in the order that catches it fastest.

Start with intent, not code. Before you look at a single function, restate what the change was supposed to do and confirm the code is even solving that problem. Agents drift: you asked for a filter and got a sort, or the feature works but silently changed an unrelated screen. Catching a wrong-problem build here saves you from carefully reviewing code that was never going to be right.

Run the tests, and then read them. A passing suite feels like proof until you notice the agent wrote tests that assert the happy path and nothing else. The test that matters is the one for the case you are worried about, and if it is missing, the green checkmark is meaningless. Read what the tests actually assert before you trust that they passed.

Exercise the edge cases by hand. Wrong password. Empty input. The second concurrent user. The thing that was working yesterday. Agents are strong on the path they were shown and weak on the paths they were not, so five minutes of deliberately trying to break it finds more than an hour of reading finds.

Check it in a real environment, not the demo. Addy Osmani put the rule plainly:

Always test AI-generated code in a sandbox before merging.

A demo runs on the machine that just built it, with the data that happens to be loaded. A sandbox that looks like production surfaces the hardcoded path, the missing environment variable, and the assumption that only holds on the developer's laptop. This is exactly where the "it works on my machine" class of bug lives.

Diff for collateral damage. AI agents edit more than you asked. Look at the full change, not just the new feature, and ask what else moved. A refactor that "cleaned up" a shared function may have broken three callers you did not think to test.

Notice what these have in common: not one of them is "understand every line the agent wrote." You verify against behavior and intent, not against a code-reading marathon you do not have time for. That is the shift. You are not auditing the agent's homework, you are proving the result.

Verification needs a target, and the target is the receipt

Here is the reframe. Every one of those checks assumes you already know what "correct" looks like. The edge cases you test, the behavior you confirm, the intent you check against, all of it depends on a definition of done that existed before the build started. If that definition lives only in your head, verification becomes a vibe, and a vibe does not scale past the third feature.

A builder in r/ClaudeCode described the fix without naming a product:

You need a receipt for each agent. That receipt, verified, becomes the record.

That is the missing piece. A receipt is a checkable claim: "this feature is done because these specific conditions were confirmed." Written before the build, it is the acceptance criteria the agent builds toward. Verified after, it is the evidence that the build matches intent. Without receipts, you are left staring at a diff trying to reconstruct what the change was supposed to prove. With them, verification is mechanical: check the change against each criterion, and a criterion either passed or it did not.

Compare the two ways of asking an agent to be done.

Vague: "Add login and make sure it works."

With a receipt: "Add email and password login. A valid pair signs the user in and redirects to /dashboard. A wrong password shows an inline error and does not redirect. An empty field is rejected before submit. A logged-in user hitting /login is redirected to /dashboard. Only the authenticated user's own records are returned."

The first gives the agent nothing to verify against, so it invents its own bar and clears it. The second is five checkable statements. The agent builds toward them, and you (or a verifier) confirm each one with evidence instead of opinion.

Where BrainGrid fits

This is the layer BrainGrid works in. You describe a feature in plain language and the Planning Agent turns it into structured requirements with acceptance criteria written to be checkable, the "when this, the system shall that" statements that double as the receipt. Then the Builder Agent builds against those criteria, in a BrainGrid-managed cloud sandbox with a live preview, or in your own GitHub repo through Claude Code, Cursor, or Codex over MCP. A feature is not marked done until verification checks the build against every criterion and the evidence says it matches intent.

That closes the loop the five checks are reaching for. Plan the receipt, build against it, verify with evidence, repeat. The intent is captured as a durable record instead of a sentence in a chat window that scrolls away, so the thing you verify against outlives the session that created it. Everyone else sells speed of generation. The point of a receipt is certainty of outcome.

flowchart LR
  A["Agent says<br/>'done'"] --> B{"Verify against<br/>what?"}
  B -->|"No receipt"| C["Eyeball the demo,<br/>hope"]
  C --> D["Bug surfaces<br/>in production"]
  B -->|"Receipt exists"| E["Check each<br/>acceptance criterion"]
  E --> F["Evidence per<br/>criterion"]
  F --> G["Done means<br/>verified"]

The trade-off worth naming

Verification is not free. Writing acceptance criteria before the build and checking them after is real work, and for a throwaway script or a weekend experiment it is overkill. If you are prototyping to learn whether an idea is worth pursuing, skip the receipts and move fast. The cost is justified the moment the code is going to be used by someone other than you, or is going to be built on top of next week. That is the line: verify what has to be trusted, not what you are about to throw away. Applying the full process to a one-off is how you make AI building feel slower than it should.

What this changes for you

If you are building a SaaS product with Claude Code or Cursor right now, this means your verification bottleneck is not the reading, it is the missing target. The reason reviewing AI code feels endless is that you are reconstructing intent at review time instead of defining it at plan time. Move that definition earlier. Write down what done means as checkable statements before the agent starts, and the after-the-fact review collapses from "read everything and hope I catch it" into "confirm these specific things passed." You pay the clarity cost once, up front, instead of paying the review tax on every feature forever.

Action steps

For your next AI-built feature, run this sequence:

Before the build, write 3 to 6 checkable statements of what "done" means, including the edge cases you are worried about.
Have the agent build against those statements, not a one-line prompt.
Run the tests, then read what they assert, and add the missing edge-case test.
Exercise the failure paths by hand: wrong input, empty input, second user, the thing that worked yesterday.
Test in a production-like environment, never just the demo that built it.
Diff the full change and confirm nothing outside the feature moved.
Check the result against each statement from step one. Anything not confirmed is not done.

FAQ

How do you validate AI-generated code?

Validate it against a definition of "done" you wrote before the build, not by reading every line after. Confirm the code solves the intended problem, run and read the tests, exercise the edge and failure cases by hand, test it in a production-like sandbox rather than the demo environment, and diff the full change for edits outside the feature. Each check confirms behavior against intent instead of auditing the agent's code line by line.

Is there a way to identify what an AI agent actually changed?

Yes, and you should always look. Review the complete diff, not just the new feature the agent describes. AI coding agents frequently edit shared functions, refactor unrelated code, or adjust configuration as a side effect. Reading the full set of changes is how you catch collateral damage in code the agent did not mention in its summary.

Why does AI-generated code pass tests but still break in production?

Because the agent often writes tests that assert only the happy path it already built, so the suite passes without covering the cases that fail. A green checkmark proves the tests that exist passed, not that the right tests exist. Read what the tests actually assert, and add coverage for the edge cases and failure paths you care about before trusting the result.

Do I need to read AI-generated code to verify it?

Not line by line. Effective verification checks behavior against a defined target: does it do what you asked, does it handle the cases you specified, does it work in a real environment. You will read specific code when a check fails and you need to find out why, but the goal is proving the result against acceptance criteria, not understanding every function the agent wrote.

What is the fastest way to verify AI code before merging?

Test it in a sandbox that resembles production, then check the change against the acceptance criteria you defined before the build. If those criteria exist, verification is mechanical: each one either passed with evidence or it did not. If they do not exist, you are reconstructing intent at review time, which is exactly why reviewing AI code so often takes longer than writing it.

The shift is simple to state and hard to skip: define what done means before the agent builds, and verification stops being a guess. It works because it gets more necessary as models get better, not less. More autonomy means more decisions nobody wrote down, and evidence is how you trust what you did not read.

BrainGrid is the plan-first app-building platform that turns your idea into checkable requirements, builds against them, and verifies every one with evidence. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

EARS Notation, Explained: The Requirements Syntax Behind Every AI Spec

Nico Acosta — Mon, 10 Aug 2026 11:14:29 +0000

A requirements syntax invented in 2009 for jet engine software is quietly becoming the house style for AI coding tools. It was designed for a room full of engineers arguing over a spec. Its best audience turned out to be a machine that never argues.

EARS notation, short for the Easy Approach to Requirements Syntax, came out of Rolls-Royce when Alistair Mavin and colleagues got tired of aerospace requirements that read like legal fog. The 2009 IEEE paper has been cited over 500 times. For fifteen years it lived in systems engineering, the discipline that writes requirements for things that kill people when they fail. Then the AI tools arrived, and EARS started showing up where nobody in 2009 would have predicted: in the specs that coding agents read before they build.

What EARS notation actually is

EARS is a constraint on how you write a requirement, not a new document format or a tool you install. The idea is that most bad requirements are bad in the same few ways, so you give authors a small set of sentence templates that make the common mistakes impossible. Every EARS requirement follows the same clause order:

While <precondition>, when <trigger>, the <system> shall <response>.

That is the whole grammar. The clauses always appear in that order, most are optional, and the word "shall" carries the actual behavior. From that one skeleton, five patterns cover almost everything you need to say.

A ubiquitous requirement is always true, no condition attached: "The system shall encrypt all stored passwords." An event-driven requirement fires on a trigger: "When a user submits the signup form, the system shall send a verification email." A state-driven requirement holds while something is true: "While a payment is processing, the system shall disable the submit button." An unwanted-behavior requirement handles the sad path, the one everyone forgets: "If the payment provider returns an error, then the system shall display the failure reason and preserve the cart." And an optional-feature requirement scopes to a configuration: "Where two-factor authentication is enabled, the system shall require a code on login."

Read those back. Notice what the template forced you to do. You named the exact trigger, the exact state, the exact system, and the exact response. There is no room for "the app should probably handle errors gracefully," because the grammar has no slot for "probably" or "gracefully." That constraint is the entire point.

The reframe: it was built for humans, it pays off with agents

Here is the hypothesis this post rests on. EARS was designed to make requirements unambiguous for a human reader, and it did that job for fifteen years. But its value goes up, not down, the moment the reader is an AI agent, because an agent takes the sentence literally in a way a human colleague never quite does.

When a human reads "the system should handle invalid input," they fill the gap with judgment. They have seen a hundred forms, they know what validation usually means, and they quietly do the reasonable thing. That gap-filling is a feature when the reader is a senior engineer and a liability when the reader is an agent, because the agent also fills the gap, just not necessarily with your version of reasonable. It picks a plausible interpretation, writes code against it, and the demo runs. The mismatch surfaces three weeks later when a real user pastes an emoji into a field you never specified.

The GitHub Spec Kit team is actively debating EARS integration for exactly this reason. The issue puts it plainly: EARS gives authors sentence templates that help them write specifications AI agents can parse more reliably. Amazon's Kiro already generates its acceptance criteria in EARS by default, one of two very different takes on spec-driven development. The tools converging here are not doing it out of nostalgia for a 2009 aerospace standard. They are doing it because a constrained sentence is a better instruction to a literal machine than a fluent paragraph is.

This is the same lesson the AI building community keeps rediscovering in its own words. Steinberger's line that your job is to design the loops that prompt your agents is really a statement about inputs: the loop is only as good as the target you hand it. EARS is one disciplined way to write that target so the agent and the verifier read it the same way.

Vague requirement versus EARS requirement

The difference is easiest to see side by side. Take a single feature, password reset, written the way it usually reaches an agent versus written in EARS.

Vague: "Users should be able to reset their password securely."

EARS: "When a user requests a password reset, the system shall send a reset link to the account email within one minute. The reset link shall expire 30 minutes after issue. When a user opens a valid reset link, the system shall allow a new password to be set. If a user opens an expired or already-used link, then the system shall display 'This link is no longer valid' and offer to send a new one. When a password reset completes, the system shall invalidate all existing sessions for that account."

The first version is a wish. It has one word, "securely," doing an enormous amount of undefined work. The second version is a set of facts you can check. Each "shall" is either true of the running app or it is not, with no room to argue. An agent can build against it, and just as important, a verifier can measure the result against it without asking anyone what "securely" was supposed to mean.

That is the connection most explainers miss. A well-formed EARS requirement is already an acceptance criterion. The syntax that makes intent unambiguous is the same syntax that makes "done" checkable. Write the requirement in EARS and you have not just specified the feature, you have specified the test.

flowchart LR
  A["Vague intent:<br/>'handle errors gracefully'"] --> B["Agent fills the gap<br/>with a guess"]
  B --> C["Demo runs,<br/>looks done"]
  C --> D["Bug surfaces<br/>in production"]
  E["EARS requirement:<br/>'If X, then the system<br/>shall do Y'"] --> F["Agent builds against<br/>a literal target"]
  F --> G["Verifier checks<br/>each 'shall'"]
  G --> H["Done means<br/>verified"]

Where BrainGrid fits

This is the layer BrainGrid works in. You describe a feature in plain language, "let users reset their password," and the Planning Agent turns it into structured requirements with acceptance criteria written to be checkable, the EARS-shaped "when this, the system shall that" statements rather than a paragraph of hope. Then the Builder Agent, working in a cloud sandbox or in your own GitHub repo through Claude Code, Cursor, or Codex, builds against those criteria, and a feature is not done until each one is verified with evidence.

The point is not that you must memorize five patterns and hand-write "shall" sentences all day. Most builders never learn the acronym, and they should not have to. The point is that the discipline EARS encodes, name the trigger, name the system, name the exact response, cover the unwanted path, is exactly the discipline that separates a spec an agent can build reliably from a prompt it has to guess at. BrainGrid captures that intent as a durable record so the plan outlives the chat window, instead of decaying the moment the context fills up.

The trade-off worth naming

EARS is not free, and pretending it is would be dishonest. Constrained syntax is slower to write than a fluent sentence, and it can feel stiff, almost robotic, when you first switch to it. "When a user submits the form, the system shall validate the email field" is less pleasant to read than "the form should check the email." Mavin's own work concedes EARS is a starting discipline, not a universal law: some requirements, particularly complex interacting behaviors, do not fold neatly into one template, and forcing them can make things worse rather than clearer. It is a floor for quality, not a ceiling.

It also does not verify anything on its own. A perfectly formed EARS requirement that nobody checks is still just a nicely worded wish. The syntax makes "done" definable. Something still has to do the defining-versus-reality comparison, which is the verification step, not the writing step. EARS gets you a target the machine can read. It does not pull the trigger.

What this means if you build with agents

If you hand your coding agent one-line prompts and get back plausible code that breaks on the second user, the fix is not a smarter model. It is a less ambiguous instruction. You do not need to adopt EARS formally to get the benefit. You need to write requirements the way EARS forces you to: state the trigger, state the exact behavior, and always write the "if this goes wrong, then the system shall" case, because that is the one your agent will otherwise invent for you.

A requirements syntax built for jet engines turns out to be the right shape for the age of coding agents, for a reason that has nothing to do with aerospace. The literal reader rewards the precise writer. EARS just happens to be the cleanest way anyone has found to write precisely.

FAQ

What is EARS notation?

EARS notation, the Easy Approach to Requirements Syntax, is a structured way to write natural-language requirements using a small set of keywords and a fixed clause order. Developed by Alistair Mavin and colleagues at Rolls-Royce in 2009, it constrains every requirement to the shape "While <precondition>, when <trigger>, the <system> shall <response>," which removes the ambiguity that makes ordinary requirements hard to build and impossible to test cleanly.

What are the five EARS patterns?

The five patterns are ubiquitous (always true: "the system shall encrypt all stored passwords"), event-driven (triggered: "when a user submits the form, the system shall send an email"), state-driven (conditional on a state: "while a payment is processing, the system shall disable the button"), unwanted behavior (error handling: "if the provider returns an error, then the system shall display the failure"), and optional feature (scoped to a configuration: "where 2FA is enabled, the system shall require a code"). Almost every requirement you need to write fits one of these five shapes.

Why is EARS used in spec-driven development and AI coding?

Because an AI agent reads a requirement literally, and a constrained sentence is a more reliable instruction than a fluent paragraph. Tools like Amazon's Kiro generate acceptance criteria in EARS, and the GitHub Spec Kit team is debating adding it, precisely because EARS templates produce specs that agents parse consistently. A well-formed EARS requirement is also already an acceptance criterion, so the same syntax that makes intent unambiguous makes "done" checkable, which is the core of spec-driven development.

What is the difference between EARS notation and acceptance criteria?

They overlap heavily. EARS is a syntax for writing any requirement clearly; an acceptance criterion is a condition that defines when a feature is done. The connection is that a requirement written in EARS is usually already a good acceptance criterion, because "when X, the system shall Y" is both a statement of intent and a checkable test. For the full craft of writing criteria an agent can verify, see how to write acceptance criteria an AI agent can actually verify.

Do I have to use EARS to write good requirements for AI agents?

No. EARS is one disciplined way to hit the target, not the only one. What matters is that your requirement names the exact trigger, the exact system, the exact response, and the unwanted-path behavior, which is precisely the discipline EARS enforces. You can get the same benefit by writing that way without ever learning the acronym, which is essentially what BrainGrid's Planning Agent does for you when it turns a plain-language idea into structured, verifiable criteria.

BrainGrid is the plan-first platform that turns your idea into requirements and acceptance criteria your agent can build and verify against. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

What Is a CLAUDE.md File? The One Anthropic's Own Docs Tell You to Keep Short

Nico Acosta — Sun, 09 Aug 2026 11:13:59 +0000

Everyone tells you to write a CLAUDE.md file, and almost nobody tells you what it is actually for. So you create one, paste in everything you can think of, and watch your agent behave beautifully for a week. Then it starts ignoring the file you spent an afternoon on, and a thread titled "What is the point of CLAUDE.md?" with 180 comments suddenly makes total sense.

Here is the claim worth sitting with. A CLAUDE.md file is not your project's memory. It is a set of standing instructions the model reads at the start of a session, and the more you treat it like a durable record of what your product is supposed to be, the faster it turns into a liability.

What a CLAUDE.md file actually is

A CLAUDE.md file is a plain Markdown file that Claude Code reads automatically at the start of every session. It goes in your project's root, you write it by hand, and it holds the things the agent would otherwise have to guess: your tech stack, your build and test commands, your coding conventions, the folders it should not touch. Anthropic's own docs describe it as persistent instructions for a project. The keyword there is instructions, not knowledge.

That distinction is the whole post. The file is prepended to the conversation, so it costs context tokens on every single turn. It is not a database the agent queries when it needs something. It is a preamble it carries the entire time, whether the current task needs those rules or not. Which is exactly why the advice that actually works, once you get past "just write one," is to keep it short.

The counterintuitive part is that cutting the file down often makes the agent better, not worse. One builder reported cutting roughly 80% of his Claude Code context and getting sharper results, echoing guidance from Anthropic's own team that less instruction beats more. That reframes the file from a place to hoard context into a budget you spend carefully. A 400-line CLAUDE.md is not a well-documented project. It is a 400-line tax on every request, and past a certain point the model starts skimming it, which is the exact behavior the Reddit thread was complaining about.

What goes inside a CLAUDE.md file

The useful contents are narrow and stable. Think of the small set of facts that are true today and will still be true next month: the frameworks you use, the command to run tests, the command to build, the linter you enforce, the one architectural rule you never want violated ("all API calls go through the client in lib/api, never fetch directly"). These earn their place because they change slowly and apply to nearly every task.

Here is the difference between a file that helps and one that rots, side by side.

Rots: "We migrated the auth flow last Tuesday and the new endpoint is /v2/login, but the old one still works for now, and Sarah is refactoring the session handling this sprint so check with her before touching it."

Helps: "Auth lives in src/auth. Run pnpm test:auth after any change there."

The first one is a status update. It will be false in a week, and when it is, the agent will confidently act on it anyway. The second is a durable fact about where things live and how to verify them. One is a note to a coworker. The other is a rule for a machine.

Should you commit your CLAUDE.md file?

Yes, for the project-level file. The whole value is that everyone on the team, and every remote agent, loads the exact same rules. Commit the CLAUDE.md in your repo root the way you commit your linter config, because it is the same kind of artifact: a shared standard, not a personal preference. Check it into Git and your agent behaves consistently no matter who runs it or where.

Your personal, machine-wide file (the one in ~/.claude/) is different. It holds your individual workflow quirks, it lives in your home directory outside any repo, and it should stay there. The rule of thumb: project rules are team property and get committed; personal preferences are yours and do not.

The reframe: instructions are not a record

Now the part that most "how to write a great CLAUDE.md" posts miss. Builders keep reaching for CLAUDE.md, or Claude's auto-memory, to solve a problem it was never designed for: remembering what the product is supposed to do. What did we decide about how billing works? Why is this feature built the way it is? What counts as done for the checkout flow? That is not instruction. That is your product's record, and stuffing it into a file the model skims on every turn is how it goes wrong.

The evidence for this is everywhere once you look. In a recent r/ClaudeCode thread on whether anyone actually uses Claude's memory feature, four separate builders landed on the same verdict without coordinating. One put it bluntly:

I made the mistake of trying to use it for project knowledge and now it is bleeding into other projects smh. Don't be like me.

Others in the same thread said it "quickly gets outdated," that it stayed "entirely opaque" for a month before they noticed a wrong note, and that memory "should be reserved for user preferences and nothing more. Not for actual knowledge." Four people, one conclusion: the model's memory is a preference store, not a project record. It bleeds, it goes stale, and you cannot see what is in it.

This is the capability point that does not go away as models improve. Better models make it more tempting to offload durable knowledge into the model's context, not less, because the agent feels smart enough to trust. But a smarter agent working from a stale note is not more reliable. It is more confidently wrong, and harder to debug, because the mistake traces back to something it "remembered" that stopped being true weeks ago. Models are stateless. Your product isn't. (If you want the deeper version of why auto-memory rots, we wrote it up in the state file pattern.)

Where the product record actually belongs

So if instructions live in CLAUDE.md and durable knowledge does not belong in memory, where does the record of what your product is supposed to do actually live? Outside the model, in something you own and update deliberately.

This is the gap BrainGrid fills. You describe a feature, and the Planning Agent turns it into a requirement with explicit acceptance criteria, the specific, checkable statements of what done means for that feature. When the Builder Agent builds it, whether in a BrainGrid Cloud sandbox or in your own GitHub repo through Claude Code, Cursor, or Codex over MCP, verification checks the result against every one of those criteria before the feature counts as done. And all of it, the specs, the decisions, the criteria, the verifications, accumulates per product as a record you can read.

The difference from a CLAUDE.md file is the point. CLAUDE.md tells the agent how you work: your commands, your conventions, your house rules. The product record holds what you decided and why, and it does not depend on the model remembering anything. One is a preamble the model reads. The other is the source of truth the model is checked against. You still want a lean CLAUDE.md. You just stop asking it to be something it was never built to be. This is the heart of context engineering: deciding what the model should carry in its head, and what belongs in a record outside it.

The one trade-off worth naming

Keeping durable knowledge out of the model's context has a real cost: it is more work up front. Writing an acceptance criterion is slower than typing a sentence into a chat and hoping the agent remembers it. The lazy path genuinely feels faster on day one. It just stops feeling faster the first time you spend an afternoon debugging behavior that traces back to a note nobody knew was there. The effortless option rots. The deliberate one compounds. That is the trade, and it is worth making on any project you intend to keep.

If you're building a real product with Claude Code or Cursor right now, this means your CLAUDE.md should get shorter over time, not longer, and the knowledge you were tempted to cram into it needs a home the model doesn't own.

FAQ

Is a CLAUDE.md file necessary?

Not strictly, but it is worth it for any project you return to. Without one, the agent re-guesses your stack, your commands, and your conventions every session, and guesses wrong often enough to waste real time. A short, accurate CLAUDE.md removes that friction. Skip it only for a throwaway experiment you will never open again.

What do you put in a CLAUDE.md file?

The stable facts an agent needs on nearly every task: your tech stack, the commands to run and test and build the project, your core coding conventions, and the hard rules you never want broken. Keep it lean. Leave out anything that changes week to week, like current sprint status or in-progress decisions, because that is exactly what goes stale and misleads the agent later.

Should I commit my CLAUDE.md file to Git?

Commit the project-level CLAUDE.md in your repo root, because its value is that every teammate and every agent loads the same rules. Do not worry about the personal file in your home directory (~/.claude/CLAUDE.md); it lives outside the repo and holds your individual preferences, so it stays local by design.

Why does Claude ignore my CLAUDE.md file?

Usually because the file is too long. Everything in CLAUDE.md is prepended to every request, so a bloated file both costs tokens on every turn and gets skimmed rather than followed. Cut it to the rules that matter most, phrase them as clear directives, and the model follows them far more reliably. If a rule is critical, keeping it near the top and stated plainly helps.

Is a CLAUDE.md file the same as agent memory?

No. CLAUDE.md is instructions you write and control, read at the start of each session. Auto-memory is notes the agent writes for itself in the background, in a Claude-specific location. The file you own stays accurate because you edit it; the notes the agent writes tend to go stale and bleed across projects, which is why most builders reserve memory for preferences and keep real project knowledge in files, or in a product record that lives outside the model entirely.

BrainGrid is the plan-first platform that gives your product a record the model can be checked against, not just instructions it reads. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

What Is AI-Native Development? (And Why \"Disposable Software\" Is Only Half True)

Nico Acosta — Sat, 08 Aug 2026 11:15:16 +0000

Search "AI-native development" today and every definition on the first page was written by a platform vendor. IBM, DevOps.com, a half-dozen consultancies, all describing a paradigm where "intelligent agents act as primary implementers" and "platforms enforce guardrails." It reads like the future arriving on schedule, clean and inevitable.

Then you open the Reddit threads where builders actually live in this paradigm, and the tone flips. Under a post titled "Is demand for new software decreasing?", the top comment is three words repeated twice: software is now disposable. The reply underneath: "I hate this so much."

Same paradigm. Two completely different emotions. The vendors sell AI-native as liberation. The people doing it feel something closer to grief. Both are describing something real, and the gap between them is the most useful thing to understand about where software is going.

Here is the hypothesis this post is going to test: AI-native development is real and worth adopting, "disposable software" is true for a narrower slice of what you build than the grief implies, and the thing that separates the disposable from the durable is not the agent. It's whether a plan and a set of acceptance criteria outlive the chat that produced the code.

AI-native development, defined honestly

Strip away the vendor gloss and AI-native development means one thing: you build assuming the agent writes most of the code, and you organize your work around that assumption instead of fighting it.

That is a real shift, not a marketing one. In the old model, AI was a consultant on your shoulder. You wrote the code and asked ChatGPT when you got stuck. AI-native inverts the default. The agent writes the first draft of almost everything, and your job moves up a level, to deciding what gets built, describing it precisely enough that the agent can execute, and verifying that what came back actually does the job.

Patrick Debois, who has done more than anyone to name this shift, frames it as four patterns:

Transitioning from producer to manager, focusing on intent over implementation through spec-driven development, moving from delivery to discovery, and managing agentic knowledge.

Read that list twice and notice what is not on it. None of the four patterns is "write better code." All four are about the work that surrounds the code: intent, management, discovery, memory. The framing reorders the whole job. The thing you used to be paid for, producing code, is now pattern zero, the part the agent handles, and every named pattern lives above it.

That is the honest core of AI-native development. The coding got cheap. Everything around the coding became the actual job. If you have felt your role quietly change from typing to describing and checking, you already work this way, whether or not you have a word for it.

The old way and the AI-native way, side by side

The difference is easiest to see in a single feature.

Old way: you get a ticket that says "add password reset." You know your codebase, so you open the auth module, write the endpoint, wire up the email, handle the token expiry, and test it as you go. The knowledge of what "done" means lives in your head the entire time, because you are the one holding all the pieces.

AI-native way: you tell an agent "add password reset" and it produces a working-looking flow in four minutes. Now the knowledge that used to live in your head has to live somewhere the agent can see, or it doesn't get applied at all. Did it expire the token after one use? Rate-limit the request endpoint? Invalidate old sessions on reset? The agent will happily skip every one of those unless someone wrote them down, because "add password reset" is not a specification. It's a wish.

That is the whole game. In the old model, the spec could stay implicit because the person writing the code was the person who knew the requirements. In the AI-native model, the writer and the knower are different entities, and anything you don't make explicit is anything the agent is free to get wrong. This is the practical difference between vibe coding and agentic coding: one accepts whatever the agent produces, the other writes down what "produced correctly" means first.

Where "disposable software" is actually true

Now the disposability claim, taken seriously.

The builders saying "software is now disposable" are not wrong. There is a large and growing category of software that genuinely is throwaway now, and pretending otherwise would be dishonest. The internal script that reformats a CSV once a quarter. The landing page for a launch that runs for two weeks. The prototype you build to answer a single question in a meeting, screenshot, and never open again. The one-off tool that scrapes a report so you don't have to.

For all of that, disposability is not a loss. It's the point. Building these used to cost an afternoon of a developer's time, which meant they mostly didn't get built. Now they cost ten minutes, so they get built, used, and discarded, and the world is slightly better for it. If the software has a lifespan measured in days and a blast radius of exactly one person, spec-driven rigor is overhead you should skip. Vibe your way through it and move on.

The grief in those threads is real, but a lot of it is misattributed. What feels like "all software is disposable now" is usually "the disposable category got much bigger and much more visible." That is a different and less alarming claim.

Where it's a bug, not a feature

The line gets crossed the moment other people depend on the thing.

A demo that only you will ever run can be disposable. The customer-facing app it turns into cannot. The script that formats your own CSV can be disposable. The billing job that formats every customer's invoice cannot. The prototype that proves an idea can be disposable. The product you charge money for, that holds someone's data, that you will still be editing in six months, cannot be. Not because rigor is virtuous, but because "disposable" and "load-bearing" are opposites, and you don't get to be both.

Here is the trap AI-native development sets, and it's worth stating plainly because almost nobody warns you about it. The disposable version and the durable version look identical when they're born. The agent produces the same clean, confident, working-looking output either way. That is the illusion of completeness: looking done and being done are different properties, and the agent only guarantees the first one. The demo that will run once and the app that will run for years come out of the same prompt looking equally finished. You cannot tell them apart by looking, which means the moment your throwaway quietly becomes load-bearing, and it will, because the useful ones always do, you inherit a codebase that was never specified, never verified, and never meant to survive.

Disposable software is fine until the day it stops being disposable. And that day never announces itself.

What makes software non-disposable

So what actually converts a disposable build into a durable one? Not more code. The code is the cheap part now, and adding more of it just gives you more to distrust.

What makes software non-disposable is the layer above the code: a plan that says what this thing is supposed to do, and a set of acceptance criteria an agent can actually verify that says how you'll know it does it. Those two artifacts are what let you change the software next month without fear, because they tell the next agent, and the next you, what must stay true. Code without them is a black box you're afraid to touch. Code with them is a system you can keep evolving. That is the entire difference between something you throw away and something you build on.

This is exactly the gap BrainGrid is built to close, and it's the whole point of practicing agentic engineering instead of just prompting faster. You describe what you want, and the Planning Agent turns it into a real requirement with acceptance criteria, the questions you didn't think to ask, and a spec that survives the conversation. Then the Builder Agent writes the code, in our cloud or in your own repo with Claude Code, Cursor, or Codex. And nothing counts as done until it's been verified against those criteria, with evidence that it does what you intended. The agent forgets everything the moment the session ends. The plan and the criteria don't. That persistence is what makes the output something you can depend on instead of something you'll be scared to open later.

It runs as a loop, Plan then Build then Verify then Repeat, and the point of the loop is that the durable version costs you almost nothing extra up front. You get the plan for free by describing the idea, and you get to keep it. The tax of AI-native development was never the coding. It was inheriting code nobody wrote down the intent for. The loop pays that tax at the start, once, instead of every time you come back scared to change something.

What this means if you're building right now

If you're shipping with agents today, the practical move is not "spec everything" or "spec nothing." It's knowing which side of the line a given build sits on, before you start.

Ask one question: will anyone other than me depend on this, now or later? If the honest answer is no and will stay no, vibe it and enjoy the speed. That is AI-native development working exactly as advertised, and the disposability is a gift. If the answer is yes, or if there's a real chance a throwaway becomes something people rely on, then the ten minutes you spend writing down what "done" means is the cheapest insurance you will ever buy. You are not adding process. You are refusing to inherit a load-bearing black box.

The verdict on the hypothesis: AI-native development is real, disposable software is real, and the grief is mostly about not knowing where the line is. The line is dependence. Below it, throwaway is a feature. Above it, the plan and the criteria are what turn the agent's confident output into something you can actually trust. The agent gave you the code for free. The intent is the part you have to keep.

FAQ

What is AI-native development?

AI-native development is an approach to building software where you assume AI agents write most of the code and you organize your work around that assumption. Instead of AI acting as an occasional assistant while you write the code yourself, the agent produces the first draft of almost everything, and your job shifts up a level: deciding what to build, specifying it precisely, and verifying that the result does what you intended. The four recurring patterns are moving from producer to manager, focusing on intent over implementation through spec-driven development, shifting from delivery to discovery, and managing knowledge so context survives across sessions.

What are the 4 patterns of AI-native development?

The four patterns, as named by Patrick Debois, are: (1) transitioning from producer to manager, where you operate and review agent output instead of writing every line; (2) focusing on intent over implementation through spec-driven development, where living specifications matter more than granular code; (3) moving from delivery to discovery, where the work shifts from shipping known features to exploring what should exist; and (4) managing agentic knowledge, where feedback from code, tickets, and incidents continuously updates the context your agents work from. All four are about the work surrounding the code, not the code itself.

What is the difference between AI-native and AI-first?

AI-first usually means AI is a priority or a default tool in how you work, bolted onto an existing process. AI-native means the process itself was designed from the ground up assuming AI does the core work, the way "cloud-native" meant designing for the cloud rather than lifting an old app into it. In practice, an AI-first team adds an agent to its existing workflow; an AI-native team rebuilds the workflow around the agent, which is why intent, specification, and verification become the load-bearing skills rather than typing speed.

Is AI-native development the same as vibe coding?

No, though they overlap. Vibe coding means prompting an agent and accepting what comes back without a written spec or verification, which is a legitimate mode for throwaway work. AI-native development is the broader practice of building around agents, and for anything that needs to last it adds the discipline vibe coding skips: a plan, acceptance criteria, and verification against them. Vibe coding is one style of AI-native work that is fine when the software is disposable and dangerous the moment it becomes something people depend on.

Does AI-native development mean software is disposable now?

Only for a specific slice of it. Software that one person uses briefly, a one-off script, a short-lived landing page, a throwaway prototype, genuinely is disposable now, and that category has grown a lot. But the moment other people depend on the software, or a throwaway quietly becomes load-bearing, disposability turns from a feature into a liability. The dividing line is dependence, and what keeps depended-on software from being disposable is a plan and acceptance criteria that outlive the code.

BrainGrid is the plan-first app-building platform: it plans before it builds, then verifies every change against acceptance criteria, so the software you depend on never has to be disposable. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

What Is an Agent Loop? The Reason-Act-Observe Cycle, Explained

Nico Acosta — Fri, 07 Aug 2026 11:18:43 +0000

A chatbot answers you once and stops. An agent keeps going until the job is done. The difference between the two is not a bigger model or a cleverer prompt. It is a loop.

That loop is the most important idea in AI building right now, and it is also the most misunderstood. The search volume for "agent loop" is up more than 1,000% in a year, and half the explanations you will find describe the mechanism perfectly while missing the part that actually determines whether your agent ships something good or burns through your budget producing confident garbage. The mechanism is simple. What you feed it is the whole game.

What an agent loop actually is

An agent loop is a cycle: the model reasons about a task, takes an action using a tool, observes the result, and then repeats, feeding what it just learned back into the next turn. It keeps going until it decides the work is done or it hits a limit you set.

Strip away the diagrams and it is four moves. Reason: the model looks at the task and its history and decides what to do next. Act: it calls a tool, running a terminal command, editing a file, hitting an API. Observe: it reads what came back, including the errors. Repeat: it writes that result into its own context and starts the next turn with more information than it had before.

That fourth step is the one that matters. Anyone can call a model and get a paragraph. Writing the result back into the context, so the next turn is informed by the last, is what turns a stateless text generator into something that can pursue a goal across many steps. Simon Willison put the whole thing about as bluntly as it can be put:

An LLM agent runs tools in a loop to achieve a goal.

Simon Willison

LangChain's team, writing about how they build agents, describe the core the same way:

At its core, an agent is just a model calling tools in a loop until a task is complete.

LangChain, "The Art of Loop Engineering"

If you have used Claude Code, Cursor's agent mode, or Codex, you have watched this happen. You ask for a feature. The agent reads a file, tries an edit, runs the tests, sees three of them fail, reads the error, fixes the edit, runs the tests again. Each of those is one turn through the loop. You did not prompt it five times. You prompted it once, and the loop did the other four turns on its own. Chain a few of these loops together across a whole task and you get an agentic workflow; the loop is the atom that everything larger is built from.

Why the loop, not the model, is the unlock

Here is the reframe most explainers skip. The loop is not a feature of the model. It is a feature of the harness wrapped around the model. The same model that gives you one flat answer in a chat window becomes an agent the moment you put it in a loop that can act and observe.

This is why the last two years felt like such a step change even when the underlying models improved only incrementally. a16z's Yoko Li described the shift precisely this week:

An AI model can almost always produce another answer. It can revise the paragraph again. It can try another implementation. Instead of a human prompting a model, inspecting the result, describing what went wrong, and prompting it again, we can ask the system to perform the whole cycle itself.

Yoko Li, a16z

That is the promise. The human used to be the loop, prompting and inspecting and re-prompting by hand. Now the system runs the cycle itself, and you step up a level to design the loop instead of running it. It is a genuine gain in leverage, one full step up the ladder.

It is also a genuine transfer of risk, and this is the part the excited version leaves out.

The loop's blind spot: it does not know what "done" means

A loop can act. A loop can observe. A loop can repeat. The one thing a loop cannot do is tell you whether the thing it produced is actually right. It only knows whether it finished.

That gap is not academic. It is the single most common failure builders describe, and this week I watched three people, in three different corners of the internet, name the same thing from three different directions. An agent-ops practitioner put it as a distinction:

When the loop stops, teams are tempted to mark success. But an agent can stop after a tool error or an unconfirmed write. Completion is a runtime event. Success is a verified state.

Stanislav Sorokin

Completion is a runtime event. Success is a verified state. Nine words, and they carry the entire problem. The loop terminates when the model returns a final answer with no pending tool calls. That is completion. Whether the feature it built does what you wanted, handles the edge cases, guards the auth route, and does not silently break the thing next to it, that is success, and the loop has no idea. It stopped. That is all it knows.

A builder in r/ClaudeCode arrived at the fix on their own, without a vendor telling them to:

You need a receipt for each a,b,c agent. That receipt, verified, becomes the record. That's how you not only perform loop engineering, but auditable loop engineering.

r/ClaudeCode commenter

They reinvented acceptance criteria and evidence from scratch because they needed them and nothing shipped them. That is the tell. When people independently build the same missing piece, the piece is not optional. It is load-bearing, and the loop leaves it out.

Without something to check against, a loop that runs longer does not get you closer to done. It gets you a more expensive way to be wrong. A commenter in r/VibeCodeDevs said it in one line:

Without those guardrails, loop engineering stops being leverage and just becomes an expensive way to keep the meter running.

r/VibeCodeDevs commenter

What changes for you

If you are building with an agent right now, this means your job moved. It did not disappear. When you were prompting one step at a time, you were the verifier: you read each response, caught the wrong turn, and corrected it before the next step. The loop takes that seat. Nobody is reading each turn anymore, which means the standard the agent is checked against has to exist before the run, not in your head during it.

Concretely, the difference looks like this.

Loop with no target: "Build a contact management view." The agent builds a table, calls it done, and stops. It works in the demo. It has no auth guard, the filter breaks on an empty state, and you find out in production.

Loop with a target: "Build a contact management view. Sortable table with name, company, last-contacted date. Row click opens a detail panel. Only authenticated users can access it; unauthenticated users redirect to /login. Empty state shows a 'no contacts yet' message." Now the loop has something to check itself against, and "done" means every one of those is true.

The second version is not a better prompt. It is a definition of done the loop can verify against. That is the input the loop cannot generate for itself, and it is exactly where the whole approach lives or dies.

Where BrainGrid fits

This is the gap BrainGrid is built to close. The loop is a powerful engine with no steering wheel, and the steering wheel is a plan with acceptance criteria. In BrainGrid, you describe what you want to build and the Planning Agent turns it into a requirement with acceptance criteria, the observable, testable conditions that define done, before any code runs. Then the Builder Agent runs the loop, either in a BrainGrid Cloud sandbox with a live preview or in your own GitHub repo through Claude Code, Cursor, or Codex. When the loop stops, the work is checked against those criteria, and a feature is not done until the evidence says it does what you intended.

That is the receipt the r/ClaudeCode builder wanted, generated for you instead of hand-rolled. The loop still does the acting and observing. BrainGrid supplies the one thing the loop cannot: a definition of done that outlives any single run and a record of whether the run met it.

The honest trade-off: writing acceptance criteria up front is work, and for a throwaway script it is work you can skip. Nobody needs a verified definition of done for a one-off data cleanup. The moment the thing you are building is something other people will use, though, the criteria stop being overhead and become the only thing standing between "the loop finished" and "the feature works."

The loop is the engine. The spec is the destination.

An agent loop is reason, act, observe, repeat, running until a stop condition is met. That is what turns a model into an agent, and it is genuinely the most important primitive in AI building today. But a loop optimizes for termination, not correctness. It will happily stop on a broken result and report success, because stopping is the only signal it has.

The models will keep getting better at running the loop. They will not get better at knowing what you meant. That part is still yours, and the way you hand it to the agent is a plan it can check itself against. Give the loop a destination and it becomes leverage. Give it none and it becomes a very fast way to arrive somewhere you did not want to go.

FAQ

What is an agent loop?

An agent loop is the continuous cycle an AI agent runs to complete a task: it reasons about what to do next, takes an action using a tool, observes the result, and repeats, feeding each result back into its context until it reaches a stop condition. This loop is what separates an agent, which can pursue a multi-step goal, from a chatbot, which answers once and stops.

What are the steps in an agent loop?

Most agent loops have four stages. Reason: the model evaluates the task and decides the next step. Act: it executes a tool, such as running a command, editing a file, or calling an API. Observe: it reads the output or error and feeds it back into its context. Repeat: it starts the next turn with that new information. The fourth step, writing the result back so the next turn is better informed, is what makes it an agent rather than a series of one-off answers.

How does an agent loop stop?

A loop ends when the model returns a final answer with no pending tool calls, meaning it believes the work is complete. Harnesses also add safety limits: caps on the number of iterations, a wall-clock time budget, a token budget, and error detection that breaks out when the agent keeps retrying the same failing action. Reaching a stop condition tells you the loop finished; it does not tell you the result is correct.

What is the difference between an agent loop and loop engineering?

An agent loop is the underlying cycle, reason, act, observe, repeat. Loop engineering is the practice of designing the system that runs those loops for you, on a schedule, so you are no longer prompting the agent by hand. Put simply, the agent loop is the engine, and loop engineering is the discipline of building and steering a fleet of those engines.

Why does my AI agent say it's done when the code is broken?

Because the loop's stop condition is completion, not correctness. The agent stops when it has no more actions queued, which can happen even after a tool error or an unverified change. The loop has no built-in notion of whether the result matches what you wanted. The fix is to give it an external standard to check against, acceptance criteria that define done in observable, testable terms, so "finished" and "correct" stop being the same claim.

BrainGrid is the system that takes an idea to a live product you can trust, giving your agent's loop the one thing it can't supply itself: a plan with acceptance criteria to verify against. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

What Is a System Prompt? Where Your Durable Instructions Actually Belong

Nico Acosta — Thu, 06 Aug 2026 11:17:06 +0000

A system prompt is the most powerful instruction you can give an AI model, and it is the wrong place to put almost everything people cram into it.

That sounds backwards. The system prompt sits above every other message, it steers tone, format, and behavior across the whole conversation, and it is the first thing most builders reach for when their agent misbehaves. So the instinct is to keep adding to it. When the agent forgets a rule, you add the rule to the system prompt. When it uses the wrong style, you add the style. A month in, your system prompt is a 400-line rulebook, and the agent still drifts.

The problem is not that the system prompt is weak. It is that you have been using it as a filing cabinet for things that were never supposed to live in a prompt at all.

What a System Prompt Actually Is

A system prompt is a set of standing instructions given to a language model before it ever sees a user's message. It defines how the model should behave across the entire session: its role, its tone, its constraints, the format it should answer in. NIST's glossary puts it precisely: system prompts are "application-specific instructions provided in-context to a GenAI system by the model developer or application designer." They are the ambient behavior layer.

Think of it as the difference between a job description and a task. The system prompt is the job description. It says "you are a senior code reviewer, you respond in plain language, you never approve code you cannot explain." The user prompt is the task: "review this pull request." The job description is set once and applies to everything. The task changes every time.

Every major model exposes this layer. In the OpenAI, Anthropic, and Google APIs, you pass a system role (or a system instruction) separate from the user turns. In consumer tools, it is the "custom instructions" or "personality" field. In coding agents, it shows up as the file the agent reads on startup, CLAUDE.md for Claude Code, AGENTS.md for the broader ecosystem, the ambient context that shapes every response before you type a word.

System Prompt vs User Prompt: The Distinction That Matters

The cleanest way to understand a system prompt is by what it is not. A user prompt is a single request in a single turn. A system prompt is the standing context that request lands in.

System prompt: "You are a technical writer for a developer audience. Write in short paragraphs. Never use marketing language. Always include a concrete code example when explaining an API."

User prompt: "Explain how our webhook signing works."

Swap the user prompt for a hundred different questions and the system prompt still holds. That persistence is the whole point, and it is also the trap. Because the system prompt persists, it feels like the natural home for anything you want the agent to remember. Your API conventions. Your database schema. The acceptance criteria for the feature you are shipping this week.

That is where builders go wrong. Persistence across a conversation is not the same as being the durable record of your product. A system prompt lives inside one model's context window, for one session, and it is invisible to everyone but you. Push project knowledge into it and you have created a record that only exists as long as the chat does.

The System Prompt Is Not Your Product's Memory

Here is the reframe. Builders keep discovering, the expensive way, that the model's context is a bad place to store what the product actually needs to know.

The clearest recent evidence came from a Claude Code thread where someone asked whether anyone actually uses the built-in memory feature as a project record. The answers were unanimous, and none of them were kind. One developer had tried exactly that and regretted it:

I made the mistake of trying to use it for project knowledge and now it is bleeding into other projects smh. Don't be like me.

Others in the same thread reported the same failure from different angles. The memory was "entirely opaque" and a wrong entry went undiscovered for a month. Another disabled it outright because "it quickly gets outdated." The consensus that emerged was a rule worth writing down: memory is for user preferences, not for knowledge. Behavior, not facts.

That rule applies to your system prompt too, because a system prompt and an agent's memory are the same kind of thing. Both are ambient context. Both shape behavior. Both go stale silently, because nothing checks them against reality. The moment you use either one to hold your product's requirements, you have made a record that bleeds, drifts, and lies without telling you.

The counterargument is fair, and you should sit with it: any written record goes stale, including the one you keep outside the model. That is true. But there is a difference between a record you can see, version, and verify against, and one buried in a context window you never read. A builder in another thread named the discipline that makes a written record survive: "the wiki must reflect the current state 100%." You cannot enforce that on a system prompt you last touched three weeks ago and cannot inspect. You can enforce it on a plan you own.

What Belongs in a System Prompt, and What Doesn't

The useful line to draw is between how your agent works and what it is building.

The system prompt is for the "how." Your conventions, your tone, your formatting rules, the commands the agent should run, the mistakes it made last week that you turned into a standing instruction. These are true across every feature. They are ambient by nature, and the system prompt is exactly where they should live.

The "what" is different. The requirements for the feature you are shipping, the acceptance criteria that define done, the specific behavior the code must exhibit, none of that is ambient. It is specific, it changes per feature, and it needs to be verifiable. Put it in the system prompt and it competes for attention with everything else in the window, degrades as the session grows, and leaves you no artifact to check the finished work against.

Compare the two failure modes:

The agent behaves inconsistently across a session: it forgets your code style, ignores your naming convention, switches tone. That is a system prompt problem. Fix the "how" in the ambient layer.

The agent builds the wrong thing, or builds something that looks right and breaks in production. That is not a prompt problem at all. That is a missing spec. No system prompt is going to define "done" for a feature it has never heard of.

This is the gap BrainGrid is built to close. The Planning Agent takes the feature you describe and turns it into a requirement with real acceptance criteria, the "what" written down as statements you can verify, not buried in a prompt. That requirement is the durable record. When the Builder Agent writes the code, in BrainGrid Cloud or in your own GitHub repo with Claude Code, Cursor, or Codex over MCP, the acceptance criteria are what the work gets checked against. A feature is not done because the agent stopped. It is done because every criterion is verified with evidence.

The system prompt still matters. It carries how your agent works. But the thing that defines whether the build is correct lives in the plan, where you can see it, version it, and hold the finished code up against it. Models are stateless. Your product is not.

The Practical Version

If you are debugging an agent that keeps misbehaving, the fastest triage is to ask which layer the problem lives in.

If the agent's behavior is off, tone, format, ignoring a convention, that is your system prompt. Tighten it, and keep it short. A shorter system prompt attends better than a long one, the same reason a bloated context window makes an agent dumber, not smarter. Deciding what earns a place in that ambient layer, and what belongs somewhere the model can be checked against, is the whole discipline of context engineering. Boris Cherny, who built Claude Code, found that cutting context beat adding it for the tool itself.

If the agent builds the wrong thing, stop editing the prompt. No amount of ambient instruction defines a feature the agent was never given. Write the requirement, with acceptance criteria, somewhere you own and can verify against. Then let the agent build against that.

The system prompt sets the stage. It does not write the play.

FAQ

What does a system prompt mean?

A system prompt is a set of standing instructions given to an AI model before any user message, defining how it behaves across the whole session: its role, tone, constraints, and output format. It is the ambient behavior layer that applies to every response, as opposed to a single request. Most model APIs expose it as a separate system role.

What is the difference between a system prompt and a user prompt?

A user prompt is a single request in a single turn ("review this pull request"). A system prompt is the persistent context that request lands in ("you are a senior code reviewer who responds in plain language"). The user prompt changes every turn; the system prompt is set once and shapes all of them. The system prompt is the job description, the user prompt is the task.

Do I need a system prompt?

For a one-off question, no. For anything you use repeatedly, yes: a good system prompt reduces the instructions you have to repeat in every message, lowers token usage, and makes responses more predictable. But keep it to behavior and conventions, the "how." Do not use it to store your product's requirements or a feature's acceptance criteria, which belong in a plan you can verify against, not in ambient context.

What is the system prompt in ChatGPT?

In ChatGPT, the system-level instructions come from OpenAI's own hidden system prompt plus your "custom instructions," the fields where you tell it how to respond across all chats. In the API, you set it explicitly with the system (or developer) role. Either way it plays the same part: standing behavior applied before your actual message.

Can a system prompt go stale?

Yes, and this is its main risk as a knowledge store. A system prompt is invisible ambient context that nothing checks against reality, so outdated instructions sit there silently steering the model wrong. That is why it should hold durable behavior, not fast-changing project facts. Requirements that change per feature belong in a record you can inspect and version, not in a prompt you last edited weeks ago.

Your agent's behavior belongs in the system prompt. What it is building belongs in a plan you can verify against.

BrainGrid is the system that takes an idea to a live product you can trust, turning what you want built into requirements with acceptance criteria your coding agent can be verified against. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

The Illusion of Completeness: Why Your AI Demo Feels Done and Isn't

Nico Acosta — Wed, 05 Aug 2026 11:15:32 +0000

Your AI-built app looks done. The screens render, the buttons click, the demo you showed a friend got a "wait, you built that?" And yet you have not shipped it, and if you are honest about why, it is not a to-do item you can name. It is a feeling. Something about it is not finished, and you cannot point to the part that is missing.

That feeling is correct, and it has a name. The demo is complete the way a movie set is a house: convincing from the one angle you were meant to look at, and hollow from every other. The reason you cannot name the missing part is that the missing part is, by definition, the thing nobody built and nobody wrote down. This is the illusion of completeness, and understanding it is the difference between a builder who ships and one who stalls on app number one forever.

Looks-done and is-done are two different states

Start with the honest version of what an AI coding tool actually does when it hands you a working demo. It builds the path you described. You asked for a login screen, a dashboard, and a way to add a record, so it built a login screen, a dashboard, and a way to add a record. Run it exactly the way you demoed it, with the one account you created and the three rows of data you typed in, and it works flawlessly. That is not a trick. It genuinely does the thing you asked for.

The illusion is not that the demo is fake. The illusion is that "does the thing I asked for, the way I asked for it" feels identical to "is a product," and it is not. A product is what happens when a second person logs in and can see the first person's data. It is what happens when someone leaves a required field blank, or pastes a 900-character name, or clicks submit twice because the first click seemed slow. It is what happens at 2am when the one API you depend on returns an error instead of an answer. None of those paths were in your demo, so none of them were built, and the app has no idea they exist.

Here is the reframe the whole piece rests on. A demo proves your app can exist. It does not prove your app works. Those sound like the same claim. They are as far apart as a blueprint and a building you can live in.

Why AI makes the illusion worse, not better

You might think this is just the normal gap between an MVP and a finished product, the one every builder has always faced. It is that, amplified, and the amplifier is the exact thing that makes AI building feel effortless. Speed.

When building was slow, the gap announced itself. You wrote the login screen by hand, so you knew, viscerally, that you had not yet written the password reset, the "email already taken" case, or the check that stops one user reading another's data. The unfinished parts were unfinished in your own memory. The slowness was annoying, but it was also an honest accounting of what existed.

AI removes the slowness and, with it, the accounting. The agent produces the happy path so fast and so polished that your brain files the whole feature under "done" before you have registered everything the feature would need to actually be done. The output looks like the output of a finished project, because the agent is very good at making the part it built look professional. Polish on the visible path reads as completeness across all paths. It is not.

This is why the felt experience of vibe-coded apps keeps landing on the same wall. Builders describe getting to something that looks shippable and then freezing, unable to trust it. One r/vibecoding builder put the fear plainly: they had a working app and could not deploy it, because they did not know how much they could trust the code the agent generated. That is not timidity. That is a builder correctly sensing the gap between looks-done and is-done, without the vocabulary to name it or the tools to close it. An agency that hardens AI prototypes into production systems describes the same gap from the other side, noting that prototypes routinely skip error handling, cost controls, and the unglamorous plumbing, exactly the parts a demo never has to show.

What actually lives in the gap

The gap is not mysterious once you name what is in it. It is a short, specific list, and it is the same list almost every time.

The first thing missing is anyone who is not you. Your demo has one user: you, with your data, your permissions, your well-behaved inputs. A product has strangers. The moment a second real person signs up, the questions your demo never asked become urgent. Can they see data that is not theirs? What happens when they do the thing you would never think to do? A builder on r/EntrepreneurRideAlong learned this the hard way when a real user saw another account's data, a permissions hole that existed across eleven different endpoints, none of which the builder's own testing ever tripped, because testing with your own account passes every check by design.

The second thing missing is every path except the one you walked. The demo is the golden path. The product is the golden path plus the empty form, the duplicate submit, the expired session, the network that drops mid-request, the file that is too big, the input that is not what you expected. Each of these is a small decision about what should happen, and in the demo, none of them were decided, because none of them came up.

The third thing missing is the honest failure. A demo never fails in front of you, because you drive it down the one road that works. A product fails in front of users, and the difference between a good product and a scary one is whether it fails loudly and safely or silently and destructively. An agent told to make something "work" will often paper over a broken state with a fallback that hides it, so the app looks healthy while quietly doing the wrong thing. That looks like completeness. It is the opposite: it is the app lying to you about being done.

None of these are code the agent wrote badly. They are behaviors nobody specified, so the agent, having no way to read your mind, did not build them. The gap is not a quality problem. It is a completeness-of-intent problem.

Closing the gap is a specification problem, not a coding problem

If the missing parts are the parts nobody wrote down, the fix is not "prompt better" or "review harder after the fact." The fix is to write down what done means before the build, so the invisible paths become visible requirements the agent can actually build and you can actually check.

Consider the difference in practice.

The demo instruction: "Build me a page where users can save their notes."

The is-done specification: "Build a notes page. A signed-in user can create, edit, and delete only their own notes, never anyone else's, enforced at the database. Empty notes are rejected with a clear message. If saving fails, the note stays in the editor and the user is told, never silently lost. An unauthenticated visitor is redirected to login."

The first produces a beautiful demo. The second produces something you can trust, because every sentence after the first is one of the invisible paths made explicit. The second version is not longer because it is bureaucratic. It is longer because it is honest about what "a notes page" actually has to do to be a product instead of a screenshot.

This is exactly where BrainGrid sits, and it sits before the first line of code. You describe the feature in plain language, and the Planning Agent asks the questions your demo never asked, the second-user question, the empty-field question, the what-happens-when-it-fails question, and turns your idea into a requirement with explicit acceptance criteria: the testable conditions that define done. Then the Builder Agent builds against that spec, in a managed cloud sandbox with a live preview or in your own repo through Claude Code, Cursor, or Codex over MCP. And here is the part the demo tools skip entirely: verification checks the result against every criterion before it counts as done, so "each user sees only their own notes" is not a hope, it is a checked fact with evidence behind it. That is the Verify step of the loop, Plan, Build, Verify, Repeat, and it is the step that turns looks-done into is-done.

The honest trade-off is that this is slower than typing one sentence and watching a demo appear. Writing down what done means takes real thought, and it will feel like friction the first few times, especially when the demo already looks finished and the specification feels like paperwork for something you can already see working. That friction is the point. It is the accounting that speed took away, deliberately put back. You are paying a few minutes of clarity up front to avoid the version where a real user finds the permissions hole for you.

What this means if you are stuck on your first ship

If you have an AI-built app that looks done but you have not shipped it, and you cannot say exactly why, this is the why. You are not being paranoid, and you do not need to learn to code to get past it. You need to convert the vague dread into a specific list: who else uses this, what can they see, what happens when they do the wrong thing, and how does it fail. Every item on that list is one of the invisible paths, and every one of them is answerable in plain language before you ask the agent to build it.

The builders who ship are not the ones who trust the demo. They are the ones who stopped mistaking a demo for a product, wrote down what the product actually has to do, and built against that instead. The demo was never the finish line. It was the moment the real work became visible, if you knew where to look. For the rest of the missing 20 percent that lives past the demo, the second 80 percent is where that work goes, and Lovable's limitations are the same wall seen from inside a single prototype tool.

FAQ

Why does my AI app work in the demo but break in production?

Because the demo and production exercise completely different paths. In a demo, you drive the app down the one route you designed, with your own account, your own clean data, and inputs you know it can handle. Production sends real strangers down every other route: a second user whose data must stay separate, an empty or malformed input, a duplicate click, an expired session, a dependency that fails. Your AI tool built the path you demoed and nothing else, because nothing else was described. The app breaks in production not because the code is bad, but because the paths that break were never specified, so they were never built. The fix is to write down what the app must do on those paths before the build, as acceptance criteria the agent builds against and the build is checked on.

What is the difference between a prototype and a production-ready product?

A prototype proves the idea can exist: it runs, it looks right, and it does the main thing you designed it to do. A production-ready product proves the idea works for people who are not you, under conditions you did not choreograph. The production version handles multiple users with separate data, rejects bad input gracefully, fails loudly and safely instead of silently, guards who can access what, and holds up when a dependency misbehaves. The prototype is one honest angle; the product is every angle. The distance between them is not more code, it is the specific set of behaviors, security rules, and failure cases that a demo never has to show, made explicit and verified.

Why do AI coding tools make apps that look finished but aren't?

Because they are optimized to produce the visible, happy path fast and make it look polished, and polish on the part you can see reads as completeness across the parts you cannot. When building was slow, the unfinished parts stayed unfinished in your own memory, so you knew what was missing. AI removes that slowness and the built-in accounting that came with it: the agent hands you a professional-looking result before you have registered everything a finished feature would need. It is not deceiving you on purpose. It built exactly what you described, and "what you described" left out every path you did not think to mention.

How do I know if my AI-built app is actually ready to ship?

Stop testing it as yourself and start testing it against a written definition of done. Create a second account and confirm it cannot see the first account's data. Submit empty and malformed inputs and confirm the app rejects them with clear messages instead of crashing or saving garbage. Force a failure (disconnect the network mid-save) and confirm nothing is silently lost. Check that unauthenticated visitors cannot reach protected pages. If you have not written down what "correct" looks like for each of those, you cannot know if it is ready, because clicking around your own app the way you always do will pass every time by design. Readiness is measured against criteria you set before the build, not against how good the demo felt.

Is a working demo the same as a minimum viable product?

No. A working demo shows that the core idea functions along the path you designed. A minimum viable product is the smallest version real users can actually rely on, which means it also has to handle the users, inputs, and failures your demo never encountered: separate data per user, graceful handling of bad input, safe failure, basic access control. A demo can become an MVP, but only after you close the gap between the path you showed and the paths real people will take. The demo is where the visible work ends and the real work becomes visible.

BrainGrid is the AI product planner that turns your idea into a requirement with acceptance criteria, then verifies every build against them, so looks-done becomes is-done before you ship. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

Requirements Management for AI Builders (Without the Enterprise Baggage)

Nico Acosta — Tue, 04 Aug 2026 11:14:37 +0000

Search "requirements management" and you land in 1998. The results are enterprise suites built for aerospace programs and medical-device compliance, all traceability matrices and DOORS licenses and words like "elicitation." None of it looks remotely like what you do when you open Cursor and start describing an app. So most AI builders take one glance, decide requirements management is a thing that happens to other people, and go back to prompting.

That instinct is half right. The tools are wrong for you. The practice is not.

Here is the part that flips it. The more capable your coding agent gets, the more you need requirements management, not less. A slow human developer who half-understood your idea would build slowly and ask you questions along the way. A fast agent that half-understands your idea builds the wrong thing at full speed, then writes tests that prove the wrong thing works. The gap between what you meant and what you wrote down used to close itself through conversation. With agents, nothing closes it but the requirement.

What requirements management actually is (minus the enterprise version)

Strip away the enterprise packaging and requirements management is three plain activities. You capture what the software has to do. You keep those statements current as your understanding changes. And you check the built thing against them. Capture, maintain, verify. That is the whole discipline. Everything Jama and IBM DOORS add on top of that, the sign-off workflows, the compliance audit trails, the multi-hundred-seat traceability, exists because a regulated program with 400 engineers needs a paper record that survives a lawsuit.

You're not building a pacemaker. You don't need the paper record. You need the three activities, because they're what stands between your intent and your agent's guess. This is the practical core of spec-driven development: the spec, not the chat, is what the build answers to.

The reframe worth sitting with: for an AI builder, a requirement is not documentation. It is the input to the build. In a human team, requirements are a communication artifact, a way for a product manager to tell an engineer what to make. When your engineer is an agent, the requirement is the literal thing it reads and executes against. Vague in, vague out, at machine speed. That single change, from "requirement as memo" to "requirement as build input," is why the practice matters more now than it did when it had a boring enterprise name.

The failure mode you already recognize

You've felt this even if you never called it a requirements problem. You describe a feature, the agent builds something that looks finished, you click through the demo, it works. Two features later something you never touched is broken, and when you go back to figure out what the app was even supposed to do, there's no answer written down anywhere. The only record of your intent was the chat, and the chat is gone.

One builder on Hacker News described exactly this after leaving an agent to run overnight against what he thought was a solid plan:

"Somewhere in the loop it had to make a decision and it made a wrong one. The code 'worked' but it had the wrong system design and wrote the most brittle tests around its assumption, validating its own decision."

That is not a coding failure. The agent coded fine. It is a requirements failure: the plan did not pin down the decision the agent hit at 3am, so the agent decided for itself and then graded its own homework. A managed requirement is what would have made that decision a checkable fact instead of a coin flip. This is the same trap we unpacked in why your AI agent keeps breaking things that worked: without a durable statement of intent, every session starts from zero and the agent is free to reinvent decisions you already made.

Requirements management vs. "just writing a good prompt"

The common objection: I already write detailed prompts, isn't that the same thing? It is not, and the difference is the whole point.

A prompt is a single message. It lives for one turn and then it is gone. A managed requirement outlives the conversation. It is the thing you return to when the agent drifts, the thing a second agent reads when the first one hits its context limit, the thing your verification step checks the build against. Prompts are how you talk to the agent right now. Requirements are how the product remembers what it is supposed to be.

Put them side by side:

Prompt: "Add a way for users to reset their password. Make it secure."

Requirement: "Authenticated and unauthenticated users can request a password reset by email. The reset link expires after 30 minutes and is single-use. On success, all existing sessions for that user are invalidated. Rate-limit reset requests to 5 per hour per email. Show the same confirmation message whether or not the email exists in the system."

The prompt gets you a password reset. Which behaviors you get is up to the agent's mood that day. The requirement gets you those behaviors, and, more importantly, it gives you five specific things to check when the agent says it is done. "Make it secure" is not checkable. "The reset link expires after 30 minutes" is. That checkability is the entire reason requirements management exists, and it is exactly what a good prompt, however detailed, cannot give you, because a prompt is not something you keep and verify against later.

Where this fits the loop

Requirements management is not a phase you do once at the start. It is the part of the build loop that everything else depends on. Plan, build, verify, repeat: the plan is where requirements are captured and maintained, and the verify step is where they get checked. Skip the first and the last has nothing to check against.

flowchart LR
    A[Idea] --> B[Capture as requirement<br/>with acceptance criteria]
    B --> C[Agent builds<br/>against the requirement]
    C --> D[Verify build<br/>vs. each criterion]
    D -->|criteria met| E[Ship]
    D -->|criteria missed| B
    E --> F[New idea /<br/>change] --> B

Notice the requirement is the hub, not a one-time input. When you change your mind two weeks in, you change the requirement, and the verify step now checks against the new target. That is the "maintain" activity doing its job. The alternative, changing your mind in a fresh chat and hoping the agent remembers the last six decisions, is how apps drift into a state nobody can describe.

This is the gap BrainGrid is built to close. You describe the idea, and the Planning Agent turns it into a requirement with real acceptance criteria, asking the clarifying questions that surface the decisions you did not know you were leaving to chance, and scoring whether the requirement is actually ready to build before any code exists. The Builder Agent then builds against that requirement, in BrainGrid's cloud or in your own repo through Claude Code, Cursor, or Codex. And verification checks the finished work against every criterion, so "done" is evidence, not a vibe. The requirement is not a document you file and forget. It is the spine the whole loop runs on, and it accumulates in the product record so the next feature starts from what the app already is instead of from a blank prompt. That is the same discipline behind the three artifacts that actually matter: requirements, acceptance tests, and code, in that order.

The honest trade-off

Writing requirements is slower at the start than firing off a prompt and watching something appear. That is real, and pretending otherwise would be dishonest. The first ten minutes of naming what "done" means for a feature feels like overhead when the agent could already be generating.

The trade shows up later. The cost of skipping requirements is not paid on feature one. It is paid on feature four, when the agent has quietly made a dozen decisions you never saw, and untangling them costs an afternoon and a pile of tokens. You are choosing between ten minutes of clarity now or an afternoon of archaeology later. For a throwaway weekend toy, skip it, genuinely. For anything you intend to keep, maintain, and put in front of a user, the ten minutes wins every time it comes up, which is every feature.

The takeaway

Requirements management sounds like the most enterprise phrase in software, and for decades it was. AI builders inherited the problem it solves without inheriting the practice, which is why so many vibe-coded apps hit a wall nobody can diagnose. The fix is not a compliance suite. It is treating the requirement as what it now is: the build input your agent reads, the target your verification checks, and the memory your product keeps when the chat is gone. The faster your agent gets, the more that written-down intent is the only thing holding the line between what you meant and what you shipped.

FAQ

What is requirements management?

Requirements management is the practice of capturing what a piece of software must do, keeping those statements current as your understanding changes, and checking the built software against them. Traditionally it meant heavyweight enterprise tools for regulated industries. For AI builders, it is simpler and more direct: the requirement is the plan your coding agent builds against and your verification step checks.

Do AI builders and vibe coders actually need requirements management?

Yes, and arguably more than traditional teams do. A fast coding agent that misunderstands your intent builds the wrong thing at full speed and can even write tests that validate its own wrong assumptions. A managed requirement is what pins down the decisions the agent would otherwise make on its own. You do not need enterprise tooling, but you do need to capture, maintain, and verify intent.

Is a detailed prompt the same as a requirement?

No. A prompt lives for one conversation turn and then it is gone. A requirement outlives the conversation: it is what you return to when the agent drifts, what a second agent reads when the first hits its context limit, and what your verification checks the finished build against. Prompts are how you talk to the agent now. Requirements are how the product remembers what it is supposed to be.

What is the difference between requirements management and requirements management software?

Requirements management is the practice (capture, maintain, verify). Requirements management software is the category of enterprise tools built to do it at scale for regulated programs, with traceability matrices, sign-off workflows, and audit trails. Most AI builders do not need that machinery. They need the practice, embedded in the build loop, close to where the agent actually reads the spec.

How do you write a requirement an AI agent can build against?

Write it as checkable behavior, not intent. Instead of "make the login secure," specify the observable facts: session expiry, rate limits, what happens on success and failure, what the user sees in each case. Each statement should be something you can later confirm as true or false against the built app. If a line cannot be checked, it is a wish, not a requirement. See how to write acceptance criteria an AI agent can actually verify for the full method.

BrainGrid is the plan-first app-building platform that turns your idea into a requirement your agent can build against, then proves the build matches it. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

Human in the Loop vs On the Loop: Where You Belong When Agents Build

Nico Acosta — Mon, 03 Aug 2026 11:13:31 +0000

The phrase "human in the loop" is supposed to make you feel safe. In practice, it is often the thing slowing you down the most.

Being in the loop means you approve every step before the agent moves on. That is exactly what you want when a decision is expensive and rare. It is exactly what you do not want when an agent can open twelve pull requests before lunch and you are the one gate all twelve wait behind. At some point, sitting inside the loop stops being oversight and starts being a bottleneck wearing oversight's clothes.

So the real question is not whether a human belongs in the loop. It is which loop, and where in it.

The two postures, in plain language

Two terms get used interchangeably and mean very different things. Getting them straight is the whole point.

Human in the loop (HITL): the human sits inside the execution path. The agent drafts or proposes, then stops and waits. Nothing finalizes until you review and approve. Control is high, and so is the cost of your attention, because every single action routes through you.

Human on the loop (HOTL): the human sits alongside the execution path. The agent runs autonomously inside limits you set in advance. You monitor, and you step in to correct or stop it when something crosses a line. Control is supervisory. You are watching the standard hold rather than pressing the button each time.

The cleanest articulation of this comes from Martin Fowler, who lays out three postures for humans working with coding agents: outside the loop, in the loop, and on the loop.

Humans on the loop [...] design the specifications, tests, and feedback mechanisms that guide AI agents rather than reviewing every generated artifact directly.

Read that carefully, because it reframes the whole debate. On-the-loop is not "caring less." It is moving your effort from inspecting each output to defining what a good output is, up front, in a form the agent and the system can check. You trade a thousand small approvals for one durable standard.

The mistake is treating it as a personality, not a decision

Most builders pick a posture once and never revisit it. The cautious ones stay in the loop forever and drown in review. The optimistic ones jump on the loop too early and wake up to a merged PR that quietly broke checkout.

Neither is a character trait. It is a per-task call, and the variable is stakes.

High-stakes, low-volume, hard-to-reverse work belongs in the loop. A schema migration on your production database. The auth logic that decides who can see whose data. A payment flow. You want to be the gate here, because the cost of a wrong action dwarfs the cost of your time.

High-volume, lower-stakes, easy-to-reverse work belongs on the loop. Renaming variables across forty files. Drafting the tenth CRUD endpoint that looks exactly like the previous nine. Writing tests for code whose shape you already approved. Sitting inside each of those approvals is not diligence. It is waste.

Here is the shift that matters: as agents get more capable, more of your work slides from the first bucket toward the second. That is not a reason to disengage. Anthropic's 2026 Agentic Coding Trends Report found developers now integrate AI into 60% of their work while maintaining active oversight on 80 to 100% of the tasks they delegate. The agents do more. The humans do not do less. They do something different. They move from in to on. That move is the whole reason oversight, not generation speed, is the skill that now compounds.

What actually lets you move from in to on

You cannot supervise a loop you have no standard for. This is the part every generic "HITL vs HOTL" explainer skips, because it is written for compliance officers, not builders shipping features.

To be in the loop, you need attention. You read the diff, you feel whether it is right, you approve or reject. That works, and it does not scale.

To be on the loop, you need something the loop can be checked against without you. A written definition of what "done" means for this feature. The edge cases it has to handle. The behavior that would count as a failure. In other words, acceptance criteria that exist before the agent starts and outlive the conversation it happens in.

Consider two builders shipping the same feature with the same agent.

Builder A stays in the loop by instinct. They prompt, the agent builds, they eyeball the result, they approve. It works in the demo. Three weeks later a user hits an unauthenticated route the demo never exercised, because "only logged-in users can see this" lived in Builder A's head and nowhere the agent could read.

Builder B writes the criteria first: authenticated users see the dashboard, unauthenticated requests redirect to login, an expired session is treated as unauthenticated. Then Builder B lets the agent run on the loop, and checks the output against those three lines. The redirect was missing. They caught it in thirty seconds, because they were comparing against a standard, not a memory.

Same agent. Same speed. The difference is that Builder B had something to be on the loop of.

This is the gap BrainGrid is built to close. When you describe a feature, the Planning Agent turns it into a requirement with real acceptance criteria before any code exists, so the standard is written down instead of carried in your head. The Builder Agent then builds against that requirement, in BrainGrid Cloud or in your own repo with Claude Code, Cursor, or Codex over MCP. Verification checks each criterion with evidence, so a feature is not done until the proof says it does what you intended. That is the on-the-loop posture made concrete: you set the standard once, and the loop is checked against it every run instead of you inspecting every line by hand.

Karpathy already named the destination

When Andrej Karpathy introduced "agentic engineering" in early 2026, he described the new default this way:

You are not writing the code directly 99% of the time, you are orchestrating agents who do and acting as oversight.

Orchestrating and oversight. Not typing. That is the on-the-loop role stated as a career, not a config setting. And notice what makes it possible: you can only orchestrate work whose target you have defined, and you can only oversee output you have a standard to judge. The word "oversight" quietly assumes there is something to oversee against. This is also why designing the loop itself becomes the real work: once you are on the loop, you are no longer the one prompting the agent, you are the one who decided what the agent is checked against.

The honest trade-off

Moving on the loop is not free, and pretending it is would be the same hype that got people into trouble.

Writing acceptance criteria up front costs time you do not spend when you just prompt and hope. For a throwaway prototype, that cost is not worth it. Vibe code the weekend project. Stay outside the loop entirely on the demo you will delete Monday.

The cost also does not disappear, it moves. On-the-loop supervision means you have to notice when the standard itself is wrong. If the criteria you wrote are incomplete, the agent will satisfy them perfectly and still ship the wrong thing. Being on the loop shifts your job from catching bad code to catching bad definitions of done. That is a better job, and a real one. It is not no job.

And there is a failure mode worth naming: on the loop can decay into outside the loop if you stop watching. The monitor who never intervenes is not supervising, they are absent. The posture only holds if you actually check the evidence.

What this means for you

If you are building a SaaS product with AI agents right now, your edge is not how fast you can approve things. Approving is the bottleneck you are trying to escape. Your edge is how clearly you can define what good looks like before the agent runs, so that you can step back to the loop's edge and still trust what comes out.

Stay in the loop where a mistake is expensive and hard to undo. Move on the loop everywhere else, but only after you have written the standard the loop gets checked against. The builders who scale with their agents are not the ones who trust more or review more. They are the ones who wrote down what "done" means, so the loop can hold the line when they are not staring at it.

FAQ

What is the difference between human in the loop and human on the loop?

Human in the loop means the person sits inside the execution path and approves each action before the agent proceeds, so nothing finalizes without a human decision. Human on the loop means the person sits alongside an agent that runs autonomously within preset limits, monitoring the process and intervening only when something goes wrong. In the loop is direct control per action; on the loop is supervisory control over the whole run.

When should you use human in the loop vs on the loop?

Use human in the loop for high-stakes, low-volume, hard-to-reverse decisions where the cost of a wrong action is high, such as production database migrations, authentication logic, or payment flows. Use human on the loop for high-volume, lower-stakes, easily reversible work where approving every step would create a bottleneck, such as repetitive endpoints, renames, or test generation. The choice is per task, not a fixed personality, and it depends on the stakes and reversibility of the work.

What are examples of human on the loop?

Common examples include fraud detection systems that flag transactions for later review, content moderation that auto-removes clear violations while a human monitors edge cases, and coding agents that open pull requests autonomously while a builder reviews the output against a written standard rather than watching each line get typed. In each case the system acts on its own within limits and the human supervises and can override.

Is human in the loop the same as human oversight?

Not exactly. Human oversight is the broader goal of keeping a person accountable for what AI does. Human in the loop is one way to achieve it, by requiring approval on every action. Human on the loop is another way, by supervising an autonomous system against a defined standard. Oversight can be exercised from inside the loop or from on the loop, and as agents get more capable, more oversight happens on the loop rather than in it.

How do you move from human in the loop to human on the loop safely?

The safe path is to define your standard before you step back. Write acceptance criteria that state what "done" means, which edge cases must be handled, and what counts as a failure, so the agent's output can be checked against something explicit instead of your memory. Once the standard exists, you can let the agent run autonomously and verify the result against those criteria, intervening when the evidence shows a criterion is unmet. Without a written standard, moving on the loop is really moving outside it.

BrainGrid is the plan-first app-building platform that turns your idea into a plan with acceptance criteria, builds against it, and proves every change with evidence, so you can move from in the loop to on the loop without losing trust. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

OpenSpec vs Spec Kit vs SuperPowers: Stop Shopping for the Right SDD Tool

Nico Acosta — Thu, 30 Jul 2026 11:15:00 +0000

A builder on r/SpecDrivenDevelopment recently laid out, carefully and honestly, the difference between SuperPowers, OpenSpec, and Spec Kit. He had clearly done the homework. He could tell you that SuperPowers keeps timestamped specs that accumulate, that OpenSpec merges everything into a single spec artifact, that Spec Kit scaffolds the whole flow. And then he ended with the most honest line in the entire thread:

"I think we are all still figuring these things out. Sometimes it's best to just dive in and give it a try."

That sentence is the real story of spec-driven development right now. Not which tool wins. The fact that thoughtful, motivated builders are spending their evenings comparing CLIs instead of shipping features, because the tooling layer is moving faster than anyone can keep up with. The shopping has become the work.

Here is the hypothesis worth testing: the tool you pick for spec-driven development matters far less than you think, and the time you spend choosing is mostly wasted, because the practice underneath every one of these tools is identical and that practice is the only durable part.

The Tools Genuinely Differ (and It Mostly Doesn't Matter)

Let's be fair to the tools first, because they are real and they are good.

OpenSpec is a lightweight, open-source framework that crossed 27,000 GitHub stars in under six months. Its whole pitch is a minimal three-step loop: propose, apply, archive. Specs live as markdown in your repo, no API keys, no MCP required. Thoughtworks' Technology Radar praised exactly that minimalism: "fluid, minimal workflow."

GitHub Spec Kit is the scaffolding-heavy option. It gives you a structured set of commands and templates that walk you from a specification through a plan to tasks, often generating acceptance criteria in EARS syntax. It is opinionated about the phases.

SuperPowers takes yet another stance: specs are timestamped and accumulate over time, so you get a running history of intent rather than one merged document.

Those are real differences. If you are the kind of person who enjoys this, you can spend a happy weekend comparing them. But notice what you are actually comparing. You are comparing how each tool stores and sequences the same four things: a description of what you want, a plan for building it, criteria for knowing it's done, and a record of decisions. The storage format is the variable. The four things are the constant.

This is the reframe. The spec-driven tools are not competing on whether you should write a spec. They all agree on that completely. They are competing on file layout.

What Actually Survives

Here is where it gets uncomfortable for anyone deep in tool comparison.

Look at how fast this layer is churning. Latent.Space recently catalogued what they called "meta-harness summer": Conductor, Zed's ACP, Vercel's Eve, HarnessAgent, Databricks' Omnigent, a new orchestration layer landing seemingly every week. The SDD tools sit one layer down and they are churning just as fast. The tool you carefully chose this month may be unmaintained by spring, or eclipsed by something that didn't exist when you started reading the comparison threads.

So what survives the churn?

Not the tool. The spec.

A requirement that says what you're building and why. The acceptance criteria that define done. The record of decisions that explains, six months from now, why the code is the way it is. Those artifacts are plain text. They outlive any CLI that produced them. You could move them from OpenSpec to Spec Kit to a text file to a different tool entirely, and they would lose nothing, because they were never really about the tool.

Boris Cherny, who reports writing 100% of his Claude Code contributions with Claude Code, describes his job now as writing loops and making sure they can verify themselves. The loop is what he owns. The model is rented. The same logic applies one level up: the spec is what you own, the tool is rented.

Once you see it that way, the comparison shopping looks different. You weren't choosing a methodology. You were choosing a temporary container for the thing that actually matters.

The Practice Underneath All Three

Strip away OpenSpec, Spec Kit, and SuperPowers entirely, and here is the practice every one of them is trying to encode. It comes down to three habits.

One spec per feature. Not a 40-page document for the whole product, and not a one-line prompt. A focused description of a single buildable thing, scoped tightly enough that an agent can build it and you can check it.

A plan you can review before the agent writes code. The point of planning first is not bureaucracy. It is that catching a wrong assumption in a paragraph costs minutes, and catching it in a generated codebase costs an afternoon. The plan is where you find the questions you didn't think to ask.

Criteria that accumulate. Each feature's acceptance criteria become part of a growing record of what your product is supposed to do. That record is what lets you change things later without breaking what already worked, and it is what tells you, definitively, whether a feature is done or just looks done.

That's it. That is the whole of spec-driven development, and it is tool-agnostic by definition. The r/SpecDrivenDevelopment poster had actually already figured this out, almost word for word. He described the shared model as "one spec per feature, one plan per spec." He just couldn't tell that he'd found the answer, because the tool comparison was still demanding his attention.

Consider the difference concretely.

Tool-first thinking: "Should I use OpenSpec or Spec Kit? OpenSpec is lighter but Spec Kit has better task templates, though SuperPowers' accumulation model fits how I work, but the community around OpenSpec is bigger right now."

Practice-first thinking: "This feature is 'let users reset their password by email.' Here's what done looks like: a logged-out user requests a reset, gets a one-time link valid for an hour, sets a new password, and the old one stops working. Now which tool helps me build that against those criteria?"

The second builder is going to ship. The first one is going to keep reading comparison threads.

Where BrainGrid Sits

This is the gap BrainGrid is built to close, and it's worth being precise about how.

The SDD tools hand you a framework and leave you to run it. You install the CLI, learn its commands, wire it into your agent, and remember to follow the steps every time. The practice is sound, but you are assembling and maintaining it yourself, which is exactly the labor the r/SpecDrivenDevelopment thread is full of. (If you want a deeper look at one tool's tradeoffs, we compared Kiro and BrainGrid's takes on spec-driven development and where each fits.)

BrainGrid ships the practice as a product instead of a framework. You describe a feature, and the Planning Agent turns it into a requirement with acceptance criteria, data models, and designs, challenging the vague parts and asking the questions you didn't think of before any code is written. That is "one spec per feature, one plan per spec," done for you rather than configured by you. Then the Builder Agent builds it, two ways: in BrainGrid Cloud, a sandbox with live preview that opens a pull request, or on your own computer in your GitHub repo with Claude Code, Cursor, or Codex over MCP. Whichever agent you point at it, the plan and the criteria are the same. Every feature flows across a board from planning to building to published, and the specs, decisions, and verifications accumulate into a record of the product. Swap the agent, swap the model, keep the workflow.

The structural point is the same one the tools are trying to deliver, just without the assembly: the spec is the durable asset, and a feature isn't done until the evidence says it matches what you intended. You don't pick a file format and hope you maintain the discipline. The discipline is the product.

The Honest Trade-Off

There is a real cost here, and it cuts against BrainGrid as much as it favors it.

If you love your tools, an open-source framework like OpenSpec gives you total control over every file and every step. You own the whole stack. Some builders genuinely want that, and for them the comparison shopping is not waste, it's craft. A managed product trades that control for the thing being done for you. That is a real choice, and it's not the right one for everyone.

But for most builders, and certainly for the ones writing "we are all still figuring these things out," the control isn't the point. Shipping is the point. (If you're specifically weighing the open-source frameworks, our BrainGrid vs Spec Kit comparison walks the tradeoff in detail.) And the truth the tool-comparison threads obscure is that you can start practicing spec-driven development today, in any tool, the moment you write one tight spec with real acceptance criteria for the next feature you build. You do not need to finish the research first.

FAQ

What is OpenSpec?

OpenSpec is a lightweight, open-source spec-driven development framework for AI coding agents. It stores specifications as markdown in your repo and runs a minimal three-step loop, propose, apply, archive, with no API keys or MCP required. It is one of several tools (alongside GitHub Spec Kit and SuperPowers) that help you write a spec before your coding agent writes code. The framework differs from the others mainly in how it stores and sequences specs, not in the underlying practice.

What is the difference between OpenSpec and Spec Kit?

OpenSpec is minimal and merges work into a single evolving spec artifact through a propose-apply-archive loop. GitHub Spec Kit is more scaffolding-heavy, giving you structured commands and templates that walk you from a specification through a plan to tasks, often in EARS syntax. The practical difference is file layout and how opinionated each is about the phases. Both encode the same core practice: one spec per feature, a reviewable plan, and acceptance criteria that define done.

Which spec-driven development tool is best?

There is no single best tool, and the choice matters less than most comparison threads suggest. OpenSpec, Spec Kit, and SuperPowers all encode the same practice and differ mainly in how they store and sequence specs. The better question is whether you are actually practicing spec-driven development: writing one focused spec per feature, reviewing a plan before the agent codes, and keeping acceptance criteria that accumulate. Any of the tools can support that. So can a managed product like BrainGrid, which ships the practice rather than a framework you assemble.

Do I need a tool to do spec-driven development?

No. Spec-driven development is a practice, not a tool. You can start today by writing one tight spec for your next feature, including specific acceptance criteria for what "done" means, then building against it and checking the result. The tools (OpenSpec, Spec Kit, SuperPowers) automate and structure that habit, and a product like BrainGrid runs the whole loop for you, but the practice itself works in a plain markdown file. The durable asset is the spec, not the software that produced it.

Why does spec-driven development matter for AI coding agents?

Because a vague prompt is a confident mistake machine. When an agent writes most of the code, the bottleneck stops being typing speed and becomes clarity: how precisely you describe what you want and how done is defined. A spec gives the agent a target and gives you a way to verify the result against acceptance criteria instead of reading every line. As agents get more autonomous, this matters more, not less, because more autonomy means more decisions nobody wrote down unless the spec captured them.

BrainGrid is the plan-first app-building platform that ships the spec-driven practice as a product: it plans each feature into acceptance criteria, builds with your choice of agent, and verifies every change with evidence, so you stop shopping for tools and start shipping. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

Definition of Done for AI Builders: The Quality Bar Every Agent Build Must Clear

Nico Acosta — Wed, 29 Jul 2026 11:14:42 +0000

Your agent will tell you it is done. It will say so confidently, with a green checkmark, a passing demo, and a tidy summary of what it built. And it will be wrong often enough that "the agent said done" has quietly become the most expensive phrase in AI building. The problem is not that the agent lies. The problem is that nobody told it what done means, so it picked its own definition, and its definition is "the happy path runs."

For most of software history, that gap was covered by a team. A developer finished a feature, but "finished" was understood to include tests, a review, and a deploy, because the team shared an unwritten standard. Now the developer is an agent that has no unwritten standards and no shared anything. It has whatever you wrote down, and it fills the rest with the shortest path to something that looks complete. So here is the hypothesis this post rests on: the more of your building an agent does, the less you can rely on a shared sense of "done," and the more you need that standard written down as one explicit, every-feature bar. That bar has a name. It is your definition of done.

What a definition of done actually is

The term comes from agile, and the agile definition is worth keeping because it is clean. A definition of done is a shared set of conditions a piece of work must satisfy before anyone calls it complete. Scrum.org puts it as a formal description of the state of the work when it meets the quality required for the product. The key word is "shared." It is not per-feature. It is the standing bar that applies to every feature, the checklist that is true whether you are shipping a login screen or a billing page.

That makes it different from the thing it gets confused with. Acceptance criteria answer "is this the right thing," feature by feature. The definition of done answers "is it built to standard," every time. A login feature's acceptance criteria might say a wrong password shows an error. Your definition of done says, for that feature and all the others, that the tests pass, the change was verified against its criteria, and it works in a real environment, not just a demo. One is specific to the feature. The other is the bar underneath all of them. You need both, and we go deep on the per-feature half in how to write acceptance criteria an AI agent can verify. This post is about the standing bar.

Strip away the agile vocabulary and the idea is older than software. A definition of done is just the answer to a question every builder has always had to answer: when do I get to stop. The answer used to live in people's heads. It cannot anymore.

Why AI builders need one more than anyone

Here is the part that surprises people. Definition of done is treated as a process nicety, a thing mature teams have and small teams skip. For AI building, it is the opposite. The smaller and faster your operation, the more you need it, because the agent is moving faster than your ability to catch what it skipped.

Consider the line from the apimatic team's writeup on moving from vibe coding to agentic engineering with Claude Code:

"It should work correctly" is not a criterion.

That is the whole problem in five words. To you, "it should work correctly" is obviously the bar. To an agent, it is noise, because nothing in it is checkable. The agent cannot run "correctly." It can run a test, hit an endpoint, render a page. When your standard is a feeling and the agent only understands facts, the agent ships the version that matches the facts it can see and silently drops everything else. A definition of done is how you translate your felt standard into facts the agent, and you, can actually check.

The stakes scale with autonomy, which is exactly why this gets worse as the models get better. Addy Osmani, talking about the loop-driven way agents now work, made the point cleanly when The Register pushed back on the whole idea:

The loop changes the work, it does not delete you from it. The agent runs more of the loop unattended every month. The work that does not disappear is deciding what the loop is allowed to call finished. A definition of done is that decision, written once, applied to every run.

What goes in it (and what does not)

A good definition of done for AI building is short, concrete, and the same for every feature. It is not the feature spec. It is the floor. Here is the difference between a standard an agent can clear and a wish it cannot.

The wish: "The feature should be done, tested, and ready for users."

The standard: "Every acceptance criterion is verified with evidence. Automated tests for the new behavior pass. The change runs in a real preview environment, not just locally. Inputs that should fail (empty, wrong, malformed) are handled, not just the happy path. Nothing that worked before is broken."

The first one feels complete and checks nothing. The second one is five facts, each of which is either true or false for any feature you build. An agent can be pointed at the second list. You can read down it at the merge button. Neither of you has to interpret a mood.

Notice what is not on it. There is no business logic, no "the report should show monthly revenue," no feature detail at all. That belongs in the acceptance criteria for that one feature. The definition of done is deliberately generic, because its job is to be the one bar that holds no matter what you are building. The moment it starts describing a specific feature, it has stopped being a definition of done and become a spec.

Here is how the two layers sit together across a build.

flowchart LR
  A[Idea] --> B[Acceptance criteria<br/>is it the RIGHT thing?]
  B --> C[Agent builds]
  C --> D[Definition of done<br/>is it built to STANDARD?]
  D -->|all clear| E[Merge / ship]
  D -->|gap found| C

Acceptance criteria gate the front of the build: are we building the right thing. The definition of done gates the back: is what got built allowed to be called finished. An agent that passes the first and fails the second has built the right feature badly, which is the single most common way AI work looks done and isn't.

The trap, and the honest limit

The failure mode to name out loud is the demo. An agent produces something that runs in front of you, and a running demo is the most persuasive evidence there is and the least reliable. The demo is the happy path the agent was always going to nail. Your definition of done exists to ask the questions the demo never does: what happens with bad input, what broke upstream, is there a single shred of evidence beyond "it looked fine when we clicked it." Approving because the demo worked is approving the eighty percent and inheriting the missing twenty.

And the honest limit, because pretending otherwise would be its own kind of hype. A definition of done is a floor, not a ceiling. It catches the predictable, repeatable gaps, the missing tests, the unhandled error, the broken neighbor. It will not catch a subtle security flaw or a design decision that is technically "done" and strategically wrong. For a personal project, a strong definition of done plus behavioral review is genuinely enough to ship with confidence. For anything touching real user data or money, you still want a deeper technical pass on top. The bar raises your floor a lot. It does not replace judgment about which floor you need.

How to make the bar enforce itself

A definition of done that lives in your head, or in a doc nobody opens, is the same as not having one. The whole value is that it gets checked, every feature, without you remembering to. That is the gap between knowing the standard and having it hold.

This is where BrainGrid fits, and it sits on both sides of the build. When you describe a feature, the Planning Agent turns it into a requirement with explicit acceptance criteria, so the per-feature "right thing" is written down before any code exists. When the Builder Agent builds it, in BrainGrid Cloud with a live preview or in your own repo with Claude Code, Cursor, or Codex, verification checks the result against every one of those criteria and reports the evidence, so "verified against its criteria" stops being a hope you have to police and becomes a step that runs on every feature. That is the standing bar made automatic: the same check, every build, with proof attached. It is the Verify step of the loop, Plan, Build, Verify, Repeat, and it is what turns "the agent said done" into "here is the evidence it is done."

So here is the verdict on the hypothesis. The faster your agent moves, the less a shared sense of done can be assumed and the more it has to be written, because the one thing an autonomous builder cannot supply is its own standard for stopping. Write the bar once. Make every feature clear it. The code got cheap and fast. The decision about what counts as finished is still yours, and it is more load-bearing than it has ever been.

FAQ

What is the definition of done in code?

In code, the definition of done is the standing set of conditions a change must meet before it can be merged or shipped, applied to every feature rather than written fresh each time. Typical conditions are: automated tests for the new behavior pass, the change was verified against its acceptance criteria, it runs in a real environment and not just locally, error and edge cases are handled, and nothing that previously worked is broken. It is deliberately generic. The feature-specific requirements live in the acceptance criteria; the definition of done is the quality floor that holds regardless of which feature you built.

What is the difference between definition of done and acceptance criteria?

Acceptance criteria are specific to one feature and answer "did we build the right thing": a wrong password shows an error, the report totals monthly revenue, and so on. The definition of done is generic and answers "is it built to standard": tests pass, criteria were verified, it deploys, edge cases are handled. Acceptance criteria change with every feature. The definition of done stays the same across all of them. You need both, because a feature can satisfy its acceptance criteria (right thing) and still fail the definition of done (built badly, no tests, breaks something else).

What is DoR and DoD in agile?

DoR is the Definition of Ready and DoD is the Definition of Done. The Definition of Ready is the bar a piece of work must clear before anyone starts building it, usually meaning it is clear, scoped, and has acceptance criteria. The Definition of Done is the bar it must clear before anyone calls it complete. For AI builders the pair maps neatly onto the loop: readiness is whether the plan is good enough to hand to the agent, and done is whether what the agent produced is good enough to ship. Both exist to stop guessing, one at the start, one at the end.

What does "done" mean in software?

In software, "done" means a change meets every condition the team agreed defines completeness, not just that it appears to work. That usually includes the feature behaving as specified, automated tests passing, the change reviewed or verified, and it deploying to a real environment without breaking existing behavior. The reason teams write this down as a definition of done is that "done" otherwise means something slightly different to everyone, and an AI agent has no shared sense of it at all. Without an explicit standard, "done" collapses into "the demo ran," which is the weakest possible bar.

Do small teams or solo builders really need a definition of done?

Yes, and arguably more than large teams do. A big team has reviewers, QA, and shared habits that catch skipped steps even when nothing is written down. A solo builder shipping through an agent has none of that backstop, and the agent moves faster than any one person can manually inspect. A short, explicit definition of done is the fastest way to get a quality floor without a team: five or six conditions, the same for every feature, that the agent is held to and you can read at the merge button. It takes minutes to write and prevents the most common and most expensive AI failure, shipping something that looked done and wasn't.

BrainGrid plans every feature into acceptance criteria and verifies each change against them with evidence, so "done" stops being the agent's opinion and becomes a bar you can prove. Try it at braingrid.ai.

Originally published on the BrainGrid blog.