DEV Community: Nico Acosta

How to Run Selenium in Docker for Screenshots (and the Ops Tax It Adds)

Nico Acosta — Mon, 17 Aug 2026 11:43:26 +0000

Running Selenium in Docker to capture screenshots is a well-trodden path, and the setup is short. The reason people still end up searching for it is not the happy path. It is the three failure modes underneath: a blank white image, a Chromium crash halfway through a run, and a session not created error that traces back to a version mismatch you did not know you had.

This guide covers the working setup with the official image, a runnable Python example, the errors that actually show up, and the honest boundary where containerizing a browser stops being worth it.

Use the official standalone-chrome image

Selenium publishes an image that bundles Chrome, chromedriver, and their system libraries, all versioned together:

docker run -d -p 4444:4444 --shm-size=2g selenium/standalone-chrome:latest

That starts a Selenium Grid standalone with a WebDriver endpoint on port 4444. The --shm-size=2g is not optional in practice: Chromium leans on shared memory, Docker's default /dev/shm is 64MB, and the default is exactly enough to make the browser start fine and then die partway through a page. Raise it up front and you skip the most common crash.

The distinction that matters: the browser runs inside the container, but your automation code does not have to. You connect to it over the network with a Remote WebDriver, so nothing but Docker needs to be installed on the host.

A working Python example

With the container running, this connects to it, loads a page, waits for it to paint, and saves a PNG:

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

options = Options()
options.add_argument("--headless=new")
options.add_argument("--window-size=1280,720")
options.add_argument("--disable-dev-shm-usage")

driver = webdriver.Remote(
    command_executor="http://localhost:4444/wd/hub",
    options=options,
)

try:
    driver.get("https://example.com")
    WebDriverWait(driver, 10).until(
        EC.presence_of_element_located((By.TAG_NAME, "h1"))
    )
    driver.save_screenshot("example.png")
finally:
    driver.quit()

The three Chrome options carry their weight. --headless=new is Chrome's modern headless mode, which renders the same as headed Chrome instead of the old separate code path. --window-size sets the viewport, because headless defaults to a small window and a small window is a small screenshot. --disable-dev-shm-usage is the belt to the --shm-size braces: it moves shared memory to /tmp, which keeps Chromium alive even when /dev/shm is tight.

The WebDriverWait is the part most first attempts skip, and it is why they come back with a blank image.

Why the screenshot comes back blank

save_screenshot captures whatever is painted at the instant you call it. Call it immediately after driver.get() and you photograph the page mid-load: no images, no web fonts, no JavaScript-rendered content. On a modern single-page app that means a white rectangle.

The fix is to wait for a real signal that the page is ready, not a fixed guess. Waiting on a specific element with WebDriverWait is the precise version. When the content you need is drawn by JavaScript after the initial elements appear, add a short explicit pause before capturing:

import time

driver.get("https://example.com/dashboard")
WebDriverWait(driver, 10).until(
    EC.presence_of_element_located((By.CSS_SELECTOR, "[data-loaded]"))
)
time.sleep(1)  # let late-rendering charts finish painting
driver.save_screenshot("dashboard.png")

A blank image with no error is nearly always this. A blank image where the whole viewport is one flat color can also mean the window never got sized, so confirm --window-size is set.

The errors you will actually hit

session not created: This version of ChromeDriver only supports Chrome version N. A mismatch between Chrome and chromedriver. This is the reason the official image exists: it pins the two together. If you built your own image and hit this, you now own the job of upgrading both in lockstep on every Chrome bump.

Chromium crashes mid-run. Shared memory. Start the container with --shm-size=2g and pass --disable-dev-shm-usage in the options. Use both; they solve the same problem from opposite ends.

The screenshot only shows the top of the page. save_screenshot captures the viewport, not the full document. Either set the window height to the page's full scroll height before capturing, or use Chrome DevTools Protocol, which renders the whole page in one pass:

result = driver.execute_cdp_cmd(
    "Page.captureScreenshot",
    {"format": "png", "captureBeyondViewport": True},
)

connection refused on port 4444. The container is still booting. Selenium Grid takes a couple of seconds to come up, so poll http://localhost:4444/wd/hub/status until it reports ready before your first connection.

Works locally, fails in CI. Usually the container did not get enough shared memory on the CI runner, or the image tag drifted. Pin the image tag and pass --shm-size explicitly in the CI job rather than relying on a default.

When Docker is the right call, and when it is not

Containerizing Selenium buys you a reproducible browser environment, and that is worth the setup cost when your automation is doing browser work: logging into an app, stepping through a multi-page flow, filling forms, asserting on the result. There you need the whole browser under your control, and a container is how you make "the whole browser" identical on a laptop and a CI runner.

The calculation flips when the browser is incidental. A large share of Selenium-in-Docker setups exist to produce one thing: an image of a page. A dashboard snapshot, an OG card, a nightly capture of a report, a thumbnail for a listing. There the container is not giving you determinism you need, it is giving you a browser you now have to maintain, so that an HTTP request can come back with a PNG. That maintenance is the real cost, and it is exactly the tax developers describe: self-hosted Chromium at concurrency is where teams lose weekends to memory creep, sticky workers, and restart storms.

If the job is just "URL in, image out," the render can move off your infrastructure entirely:

curl -sS https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/dashboard",
    "width": 1280,
    "full_page": true,
    "delay_ms": 1000,
    "format": "webp"
  }'

The response carries an image_url pointing at the stored capture. No container to build, no Chrome and chromedriver versions to keep aligned, no --shm-size to remember, nothing to rebuild when a base image ships a new glibc.

The parameters map closely to the Selenium options you would otherwise write: width (320 to 1920) sets the viewport the way --window-size does, full_page renders the whole document like the CDP captureBeyondViewport call, delay_ms (0 to 10000) replaces the explicit sleep after load, selector captures a single element instead of the page, and format accepts png, jpeg, or webp.

The honest boundary: if the capture has to happen after a login, a click, or a form submission, none of this helps and Selenium in a container is the correct tool. An API call renders a URL. It does not drive a session.

Cost, honestly

The comparison is not per-request price against zero, because self-hosting is not free. A containerized browser costs CI minutes on every build, image storage, and the recurring attention of whoever fixes it when a Chrome bump breaks chromedriver or a base image runs the container out of shared memory.

Grabbit is $0.002 per live grab, prepaid, with credits that do not reset monthly, which fits bursty capture work that runs hard some weeks and not at all in others. Test-environment keys return placeholder images at no cost, so you can wire the whole flow before any real capture runs. Some providers list lower per-grab rates, so if unit price is the only variable you care about, compare directly.

Where to go next

If you are keeping the container and just want the capture code to be right, how to take screenshots in Selenium covers the full-page, element, and CDP cases in depth. For the browser-agnostic version of the container problem, running headless Chrome in Docker walks the same setup without Selenium in the middle, and running Playwright in Docker covers the equivalent decision from the other major library. The screenshot API page covers the hosted side if you decide the browser is not worth maintaining.

Originally published on the Grabbit blog.

How Much Time Should You Spend Planning Before Coding With AI?

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

AI made writing code almost free, which should have finally ended the old argument about how much to plan before you start. Why design carefully when regenerating the whole thing takes thirty seconds? Instead the opposite happened. The cheaper the code got, the more the planning started to matter.

That is not a paradox once you watch where the time actually goes. This week in r/nocode, someone who had burned through Lovable, Replit, and Cursor credits and still had nothing working asked which AI app builder to buy next. An experienced builder replied with a ratio, not a tool: you should spend about 1 hour designing the specs and 20-30 minutes actually building. Then the line that turns it from advice into a diagnosis: if you find yourself cursing the AI that it is not what I asked for, it is largely because you didn't set the requirements properly.

Two to one, planning to building. From someone whose building step is an agent that writes the code for him. That is the number worth explaining.

The hypothesis: unplanned time doesn't vanish, it moves

Here is the claim this post is built to test. The hour you skip up front does not disappear. It reappears downstream as debugging, reprompting, and rework, and it costs more there than it would have cost as planning.

The old wisdom was that planning trades slow-now for fast-later, a tax you pay to avoid mistakes. With an AI agent that math gets sharper, because the agent removes almost all of the "building" time but none of the "deciding what to build" time. When the code was the expensive part, a vague plan cost you a few extra hours of typing. Now the code is nearly free and the vague plan costs you something worse: an agent that confidently builds the wrong thing, fast, and reports done.

You have felt this if you have ever watched an agent produce a beautiful, complete, working feature that solves a problem you did not have. It did exactly what you said. You just had not decided what you meant. The gap between those two is where the skipped hour went.

Cursing the AI is a requirements bill coming due

The r/nocode builder's reframe is the whole argument in one sentence. When the output is wrong, the instinct is to blame the tool and go shopping for a better one. Sometimes the tool is genuinely weak. Far more often, the requirements were never set, and no tool can build what you did not specify.

This shows up as a specific, repeatable feeling. Builders in r/ExperiencedDevs described feeling illiterate about the codebase as agents generate faster than anyone can read, and one named the root cause bluntly: people run agentic loops to solve problems they do not even understand themselves. That is not a model problem. An agent handed a fuzzy goal will fill the gaps with its best guess, and its best guess is a coin flip that looks like a decision. You do not discover the mismatch until you are three features deep and the auth logic it invented in feature two fights the state management it invented in feature four. This is the same drift that makes your agent keep breaking things that already worked: nothing carried your intent forward, so each feature quietly renegotiated it.

The planning hour is where you catch that before it's written. Not because planning is virtuous, but because it's the only place the mismatch is cheap to fix. A wrong sentence in a spec costs one edit. The same wrong assumption discovered in a shipped feature costs a debugging session, a reprompt, and the quiet erosion of your trust in the whole app.

The ratio is not the point. The exit condition is.

Two-to-one is a useful anchor, but do not turn it into a rule. The honest version is that planning time should scale with how much of your intent the agent would otherwise have to guess. A one-file script needs almost none. A multi-screen app with auth, data, and money needs a lot, because every unstated rule is a decision the agent makes for you.

What you are actually buying with that hour is a definition of done the agent can be measured against. This is the difference between a loop that converges and a loop that just burns tokens. A builder in r/AI_Agents put the failure mode precisely while defending the idea of agent loops against the skeptics: a bare loop with no verifiable exit is guaranteed token burn with fingers-crossed results. Planning is how you write the exit condition. Without it, "build until it looks done" is the only stopping rule the agent has, and looks-done is exactly the thing that fails in production.

Consider the same feature, planned two ways.

Vague: "Build me a client portal with login and file upload."

Structured: authenticated users land on a dashboard listing their own files in a table with name, size, and upload date; clicking a row downloads the file; uploads accept PDF and images under 10MB and reject everything else with a visible error; unauthenticated users redirect to /login; a user can never see another user's files. Every clause in the second version is a line the finished build can be checked against. That is the skill underneath the planning hour, and it has a name: writing acceptance criteria an agent can actually verify. The agent still moves at agent speed. It just can no longer quietly ship the version where any logged-in user can download everyone's files, which is the kind of gap a demo hides and production reveals.

Where BrainGrid fits

That planning hour has a shape, and doing it well is a skill most builders are learning on the fly. This is the gap BrainGrid was built to close, so the hour is spent on decisions instead of on staring at a blank requirements doc.

You describe the idea in plain English, and the Planning Agent turns it into a structured requirement with acceptance criteria, data models, and designs. It asks the clarifying questions you did not think to answer and pushes back when the intent is vague, which is precisely the "set the requirements properly" step the r/nocode builder was pointing at. Then the Builder Agent 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 the part almost nobody does by hand happens automatically: verification checks the finished build against every acceptance criterion, so the feature is not done until the evidence says it matches what you asked for.

That is the two-to-one ratio turned into a workflow, and it is the whole idea behind spec-driven development: the planning is where you decide what you mean, and the verification is where the agent proves it built that and not its best guess. Charity Majors made the underlying point in The Pragmatic Engineer: when you did not write the code, you have to move your trust to the other end of the process, to validation. The plan is what validation checks against. Skip the plan and there is nothing to verify against except vibes.

What changes for you

If you are shipping with an AI coding agent right now, here is the concrete implication. Your instinct is to measure progress by how fast the agent produces code, so a slow planning step feels like the agent is idling. Invert it. Measure progress by how few times you have to say "no, not like that." The builders who spend an hour framing the feature say it once or zero times. The builders who skip straight to building say it five times across three reprompts, and each round quietly rewrites something that already worked.

The trade-off is real and worth stating. On a genuine throwaway, a scratch script, a one-day prototype nobody will maintain, the planning hour is pure overhead, and you should skip it and vibe. The ratio only pays off when the thing has to keep working after you stop looking at it. That is also exactly the moment most builders wish they had planned, and by then the skipped hour has already been spent, at a worse exchange rate, on figuring out why the app broke.

So how much time should you spend planning before coding with AI? Enough that the agent is executing a decision instead of making one. The code was never the expensive part. Deciding what it should do always was, and pretending otherwise just moves the bill to the end and adds interest.

FAQ

How much time should you spend planning versus coding?

There is no universal ratio, but builders working with AI agents converge on planning taking as long as or longer than the build, often around two-to-one for anything non-trivial. The reason is that an AI agent collapses the coding time to near zero while leaving the "decide what to build" time untouched, so planning becomes the larger share by default. Scale it to ambiguity: a small script needs minutes, while a multi-feature app with auth, data, and permissions needs real planning because every unstated rule becomes a decision the agent makes for you. The goal is not a fixed percentage. It is that the agent should be executing decisions you made, not guessing at ones you skipped.

Is it better to plan before coding or just start coding?

For a small, well-understood task you have done before, starting directly is fine because you are effectively planning as you type. For anything with multiple moving parts, planning first wins, and it wins harder when an AI agent is doing the building. Unplanned work does not save time, it relocates it: the decisions you skip come back as debugging, reprompting, and rework, which are more expensive than the same decisions made up front. The practical test is whether you can state what "done" looks like before you start. If you cannot, you are not ready to build yet, you are ready to plan.

Why does my AI agent keep building the wrong thing?

Almost always because the requirements were underspecified, not because the model is weak. An agent handed a vague goal fills the gaps with its best guess and reports success, so "wrong" usually means "technically what I said, not what I meant." The fix is to write the acceptance criteria before building: the specific behaviors, edge cases, and constraints the result must satisfy. When those exist, the agent has something concrete to build toward and you have something concrete to check the result against. When they do not, you are relying on the agent to read your mind, and it cannot.

What is the 80/20 rule in coding?

The 80/20 rule (the Pareto principle) observes that roughly 80% of outcomes come from 20% of causes, and in software it shows up several ways: a small fraction of the code causes most of the bugs, a small set of features drives most of the value, and the last 20% of a project often takes 80% of the effort. For AI-assisted building, the useful version is that a small amount of upfront planning prevents a large amount of downstream rework. The 20% you spend deciding exactly what to build is what keeps the other 80% from turning into a debugging spiral.

Does planning still matter when AI writes the code so fast?

More than before, not less. When writing code was slow, a vague plan cost you extra typing. Now that an agent writes code in seconds, a vague plan costs you a confident, fast build of the wrong thing, which is worse because it looks finished. Speed makes the mismatch cheaper to produce and more expensive to catch, so the planning that prevents the mismatch is the best-paying time you spend. The bottleneck moved from writing code to deciding what the code should do, and that is exactly the part AI does not do for you. It's the same reason a vague prompt costs more than it looks like it should: the cost is just deferred.

BrainGrid is the plan-first app-building platform: it turns your idea into a spec with acceptance criteria, builds against it with your agent, and verifies the result before you call it done. Try it at braingrid.ai.

Originally published on the BrainGrid blog.

Screenshot API Alternatives: An Honest Comparison (2026)

Nico Acosta — Wed, 12 Aug 2026 11:39:27 +0000

If you are comparing screenshot API alternatives, you have almost certainly hit one of three walls: a monthly quota that resets before you use it, a feature the tool does not have, or an integration path that does not fit how you actually build. This is an honest, side-by-side comparison of the main options, with a clear note on where each one wins.

The short answer

Every screenshot API does the same core job: send a URL, get back a rendered image. They differ on three things that actually matter, so pick by whichever is your bottleneck:

Billing model. Monthly plans reset unused capacity; a flat annual plan does not. This is the biggest hidden cost for spiky or seasonal workloads.
Per-grab rate. Browserless and Thum.io list the lowest rates. Neither is a one-call REST endpoint for every feature, so cheap-per-grab comes with a trade-off.
Integration. A raw REST endpoint, a first-party SDK for your language, or an agent-callable MCP tool are three different developer experiences.

Grabbit is the alternative when monthly waste and agent onboarding are your pain: $0.002 per capture, 25,000 prepaid credits per year that never reset or expire, plus a built-in MCP server. It is not the cheapest option overall, and this post says so plainly below.

How the alternatives compare

Prices verified June 2026 from each provider's public pricing page, normalized to roughly 10,000 grabs per month. "Included" is each provider's entry-plan allowance. The honest caveat up front: two providers list a lower per-grab rate than Grabbit.

Provider	Per grab	Billing	Included	Monthly waste	Agent
Grabbit	$0.002	Annual flat	25,000 / yr	None	One-line + MCP
ScreenshotOne	$0.0079	Monthly	2,000 / mo	Resets	MCP
Urlbox	$0.0066	Monthly	2,000 / mo	Resets	None
ApiFlash	$0.0035	Monthly	1,000 / mo	Resets	None
ScrapingBee	$0.0049 †	Monthly	~10,000 / mo	Resets	MCP
Browserless	$0.0013 ‡	Monthly	20,000 units / mo	Resets	MCP
Thum.io	$0.0002	Usage metered	$1–$20 / mo min.	Minimum spend	None

† ScrapingBee is credit-based (roughly 25 credits per screenshot grab). ‡ Browserless bills in units (roughly 1 unit per grab) and is a managed browser you drive with your own scripts, not a one-call REST endpoint.

Browserless and Thum.io are cheaper per grab. The trade-offs are real: Browserless is a headless browser you drive with Puppeteer or Playwright, so you still write and maintain the capture code, and Thum.io has a narrow feature set (no full-page capture, no wait controls, no selector targeting). If raw per-grab price is the only thing you care about, one of those two is the honest recommendation, not Grabbit.

Match the alternative to the pain

If monthly resets are wasting money

On a monthly reset plan, a team that captures 1,500 pages in January and 9,000 in March pays the full monthly allowance both months, and January's unused capacity evaporates. You pad the plan to cover the busy month and forfeit the difference every quiet one. Flat annual prepaid credits remove that pressure: you buy a block once, it covers actual usage, and nothing expires at the end of a cycle. For variable workloads (OG images on publish, monitoring runs, batch research), the billing model often matters more than the headline rate. See why monthly screenshot quotas waste money for the full math.

If you need a first-party SDK

ScreenshotOne maintains client libraries for Ruby, PHP, Go, Java, C#, and more. If you want a supported SDK in your language rather than a raw HTTP call, that is a genuine advantage and a good reason to stay with it. Grabbit is a plain REST endpoint plus an MCP server, not a per-language SDK set.

If an AI agent needs to see the page

Most screenshot APIs were designed before agent frameworks existed: you get an API key and call the endpoint from backend code, which means custom glue for every agent that needs visual data. Grabbit and ScreenshotOne both ship an MCP server, so an agent registers capture as a callable tool and gets back a hosted image_url with no glue code. If agent onboarding is why you are shopping, prefer a provider with a one-line or MCP path over a REST-only endpoint.

If you just want the lowest possible rate

Browserless ($0.0013) or Thum.io ($0.0002). Accept that Browserless means writing your own browser scripts and Thum.io means a thin feature set. That is the trade you make for the lowest number in the table.

Try an alternative before you pay

You can wire up Grabbit and run it in CI before adding a card. Every account gets a test key (sk_test_...) that returns a placeholder image at no charge; switch to a live key (sk_live_...) for real captures. Here is a real request against Grabbit's API:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "height": 720,
    "format": "webp",
    "full_page": true
  }'

The response includes image_url (the hosted screenshot), bytes, execution_ms, and id. Set full_page: false with a fixed height (240 to 1080) for a viewport shot, add delay_ms (up to 10000) to wait for JavaScript-heavy content, or selector to clip to a single element. Point at a sk_test_ key first, so migrating an existing integration costs nothing to prototype.

How to choose

Monthly reset waste, variable volume: Grabbit (flat annual, no reset).
Lowest per-grab rate, willing to script: Browserless.
Simple thumbnails, minimal budget: Thum.io.
First-party SDKs for a non-JS backend: ScreenshotOne.
An AI agent needs to call it: Grabbit or ScreenshotOne (both ship MCP).

If your comparison is really "managed cloud browser vs. a screenshot endpoint," see the Browserbase alternative breakdown. For a wider field than this table, read our honest comparison of the best screenshot APIs. For Grabbit's pricing, parameters, and agent onboarding, see screenshots as a service.

Originally published on the Grabbit blog.

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.

Browserbase Alternative: When You Need a Screenshot, Not a Whole Cloud Browser

Nico Acosta — Mon, 10 Aug 2026 11:43:50 +0000

If you are searching for a Browserbase alternative, the first question worth asking is not "which vendor," it is "do I actually need a cloud browser?" Browserbase gives your code a full, programmable Chrome running in the cloud: persistent sessions, live interaction, stealth, the works. That is the right tool when you are driving a browser through multi-step flows. It is a lot of machinery when all you needed was a picture of a page.

This is an honest comparison, including an explicit section on when you should stay on Browserbase.

The short answer

Browserbase is cloud browser infrastructure for AI agents and automation: you open a session, connect over CDP or an SDK, and operate a real browser remotely. It is built to run whole interaction flows, and it bills accordingly (by session and concurrency).

If your job is narrower, capture a rendered screenshot of a URL, then a screenshot API is the simpler and usually cheaper alternative. You send one request with a URL and get back a hosted image. There is no session to open, keep alive, or tear down.

Grabbit is that alternative when the job is a screenshot: $0.002 per capture on flat prepaid credits that never reset or expire monthly, plus a built-in MCP server so an agent can call it as a tool. Grabbit is not a cloud browser and does not pretend to be one, and this post says plainly below when Browserbase is the correct choice.

Two different jobs that look similar

The reason "Browserbase alternative" is a confusing search is that a screenshot and a browser session look related but are different jobs:

A cloud browser is a live, stateful thing. You navigate, click, type, wait, read the DOM, maybe hand control to a human. You are operating the page. Browserbase, Browserless, Hyperbrowser, Anchor Browser, and Steel all sell this.
A screenshot API is a stateless request. You name a URL and how you want it rendered, and you get an image. You are observing the page, not operating it.

Most of the "Browserbase alternatives" you will find in a SERP are other cloud browsers, which makes sense if you truly need to drive a browser. But a large share of the traffic to that search is people who reached for a cloud browser because they thought a screenshot required one. It does not.

How they compare for the screenshot job

Scoped to "I need a rendered image of a URL," not to full browser automation. Cloud-browser pricing is session or minute based, so a per-grab comparison is only fair for the capture use case. Prices verified August 2026 from each provider's public pricing page.

Tool	What it is	Billing shape	Best when
Grabbit	Screenshot API	Per grab ($0.002), flat prepaid	You need a rendered image of a URL
Browserbase	Cloud browser	Per session / concurrency	You drive a real browser through steps
Browserless	Cloud browser + REST screenshot	Per unit / monthly	You want full control and self-host options
Hyperbrowser	Cloud browser (containers)	Per session / monthly	Lightweight isolated sessions, CAPTCHA handling

The honest read: if you need persistent sessions and live interaction, do not pick a screenshot API, pick a cloud browser. If you need a picture of a page, do not rent a whole browser to take it. Grabbit is also not the cheapest screenshot API in the field; Browserless and Thum.io list lower per-grab rates. Grabbit's edge is the fit and the billing model, prepaid credits that never expire, not a bottom-of-market rate. For the wider field of screenshot APIs specifically, see our honest comparison of the best screenshot APIs.

Why the billing shapes differ

This is the part that makes the cost comparison feel unfair until you see it: you are paying for different things.

A cloud browser holds a real Chrome open for you. You pay for the time that browser is alive and for how many you run at once, because keeping browsers healthy at concurrency is the expensive, hard part (memory creep, restart storms, sticky workers). That cost is real and Browserbase absorbs it so you do not lose weekends to it.

A screenshot API runs the render, uploads the image, and is done. There is no session to keep warm between calls, so it bills per capture. For a workload that is "render this URL, give me the image," paying for session time is paying for a capability you are not using.

Try it before you commit

You can wire up Grabbit and run it in CI before adding a card. Every account gets a test key (sk_test_...) that returns a placeholder image at no charge; switch to a live key (sk_live_...) when you want real captures. Here is a real request against Grabbit's API:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.browserbase.com",
    "width": 1280,
    "height": 720,
    "format": "webp",
    "full_page": true
  }'

The response includes image_url (the hosted screenshot), bytes, execution_ms, and id. Use full_page: true for a scrolling capture, delay_ms (up to 10000) to wait for JavaScript-heavy content to settle, or selector to clip to a single element. Because test captures are free placeholders, prototyping the swap from a cloud-browser screenshot call to Grabbit costs nothing.

For AI agents

Many people arrive at Browserbase because an agent needs to work with the web, and "the agent needs the web" gets rounded up to "the agent needs a whole browser." Sometimes it does: if the agent clicks, types, and navigates across steps, that is a cloud-browser job and Browserbase (or an agent framework on top of it) is the right call.

But a large slice of agent-web work is just seeing a page: feed the rendered view into a vision step, verify your own frontend, or ground the model in what a URL actually looks like. For that, a screenshot API is the lighter path. Grabbit ships an MCP server, so the agent registers capture as a callable tool and gets back a hosted image_url to pass downstream, with no browser session to manage. For the agent-eyes use case in depth, see screenshots for AI agents.

When to stay on Browserbase

An honest comparison names when not to switch:

You need multi-step interaction. Logging in, filling forms, clicking through a flow, reading the DOM between steps. A screenshot API captures a page; it cannot operate one.
You need persistent, authenticated sessions. Holding a logged-in browser open across calls is exactly what a cloud browser is for.
You use an interactive agent framework. Tools like Stagehand drive a real browser. A screenshot endpoint is not a substitute.
You need live takeover or stealth. Human-in-the-loop control and advanced anti-bot handling are cloud-browser features, not screenshot-API features.

Grabbit's pitch is not "we replace Browserbase." It is narrower and honest: if the job is a screenshot, you do not need a whole cloud browser to take it, and paying per session for a per-image job is waste.

How to choose

You need a rendered image of a URL: a screenshot API (Grabbit, or a cheaper-per-grab option if raw rate is all that matters).
You drive a browser through multi-step flows: stay on Browserbase.
You want a cloud browser but with self-host options: Browserless.
Your agent needs to see, not operate, a page: Grabbit (one call + MCP).
Your agent needs to click and navigate: Browserbase or an interactive framework.

For Grabbit's pricing, parameters, and agent onboarding, see the screenshot API page. To schedule captures without running any browser yourself, see screenshot automation.

Originally published on the Grabbit 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.

Why Monthly Screenshot Quotas Waste Your Money (Screenshot API Pricing, Explained)

Nico Acosta — Sun, 09 Aug 2026 11:42:15 +0000

If you are comparing screenshot API pricing, the pricing pages all look roughly the same: a few tiers, a monthly price, a screenshot quota per tier, and overage per extra capture. The number that decides your real cost is not on the card. It is the quota that resets every month, and how much of it you actually use. On a spiky workload, a monthly reset plan makes you pay for a peak you hit occasionally and forfeit the rest. This post explains the mechanic, then shows how to read a pricing page so you buy captures instead of empty allowance.

The short answer

Most screenshot APIs bill a fixed monthly subscription with a reset quota: you pay for, say, 2,000 captures a month whether you make 2,000 or 200, and next month the counter goes back to zero. That model is fine when your usage is steady. It quietly wastes money when your usage is spiky, which screenshot workloads almost always are.

The waste is the gap between what you provision and what you use. To cover an occasional busy month you size up your plan, then forfeit the unused allowance in every quiet month. The sticker price hides that gap.

Grabbit takes the other approach: $50 per year for 25,000 prepaid captures ($0.002 each) that never reset or expire monthly. Grabbit is not the cheapest screenshot API on headline price, and this post is explicit about that below. The point here is the pricing model, not a rock-bottom rate.

How screenshot API pricing usually works

Walk a typical pricing page and you will see one of three billing models:

Monthly subscription with a reset quota (the common one). A tier bundles a fixed number of captures per month. Unused captures do not roll over. Go over and you pay overage per extra grab, or get blocked until next cycle. This is what most listings on a "screenshot api pricing" search use.
Usage metered. You pay per request with a small monthly minimum. No quota to waste, but the minimum spend is its own small floor, and metered plans often have a thinner feature set.
Prepaid credits. You buy a block of captures once. They draw down as you use them and do not expire on a monthly boundary. Grabbit sells these on a flat annual plan.

The three models can show nearly identical per-grab math on paper and produce very different bills, because the reset quota charges you for allowance, not for work done.

Why a reset quota wastes money on spiky workloads

Screenshot volume is rarely a flat line. The real pattern looks like bursts:

A batch of Open Graph images generated the day you publish a dozen posts.
A visual monitoring run that fires on a schedule, then nothing until the next one.
A one-off research crawl capturing a list of competitor pages, then quiet.
An agent pipeline that captures heavily during a task and idles between tasks.

Put concrete numbers on it. Say you capture 1,500 pages in January, 9,000 in March, and a few hundred most other months. To not get blocked in March, you provision a plan sized for roughly 9,000 captures a month. In January you pay for that whole allowance and use a sixth of it. Every quiet month, you pay for thousands of captures you never make. Over a year, the forfeited allowance can dwarf the cost of the captures you actually took.

That is the mechanic. A reset quota bills your peak every month and hands you nothing back for the troughs. The lower the ratio of your average month to your busiest month, the more a monthly plan overcharges you.

Prepaid credits invert it: you buy a block once, draw it down at your real pace, and the busy month and the quiet month both bill only the captures you made. For variable capture volume, the billing model usually matters more than a fraction of a cent on the per-grab rate.

The honest caveat: cheapest sticker price is not Grabbit

A "screenshot api pricing" search is full of pages claiming the lowest number, so here is the honest version. Grabbit is not the cheapest screenshot API by headline price. Some providers advertise entry plans from $5 to $9 per month, and on raw per-grab rate Browserless ($0.0013) and Thum.io ($0.0002) both list lower numbers than Grabbit's $0.002.

The trade-offs behind those lower numbers are real: Browserless is a managed headless browser you drive with your own Puppeteer or Playwright scripts rather than a single REST call, and Thum.io has a limited feature set (no full-page capture, no wait controls, no selector targeting). If the only thing you care about is the lowest per-grab rate and you are willing to script, one of those is the honest pick, not Grabbit.

Grabbit's claim is narrower: flat annual billing with zero monthly reset waste, and one-line agent onboarding. If your pain is a quota you keep forfeiting, that is the thing that saves you money, not the sticker price. Prices here were verified June 2026 from each provider's public pricing page, normalized to roughly 10,000 grabs per month.

Why "temporary need" is the category's real pricing problem

There is a deeper reason the reset-quota model fits this category badly. The screenshot API market skews toward temporary needs: a project that ends, a marketing job that ships, a migration that finishes. When the market leader ScreenshotOne was publicly torn down in 2026, the founder said the category's core problem in the open: there is no single ICP it can scale with, and customers churn because the need was temporary. A monthly subscription is the worst possible fit for a temporary need, you keep paying after the work is done until you remember to cancel.

Prepaid credits that never expire suit a temporary-or-spiky need better: you buy what the job needs, use it when the job runs, and nothing keeps billing you between jobs. (Whether that changes long-run retention is a separate question we are not claiming to have answered, it is a better fit for the buying pattern, full stop.)

How to read a screenshot API pricing page

When you land on a pricing page, get past the sticker price and check five things:

Reset or roll over? Does unused quota carry forward, or evaporate at the cycle boundary? This is the single biggest driver of real cost on spiky usage.
Effective cost per capture you make. Divide the plan price by the captures you realistically make in an average month, not by the quota. That is your true per-grab cost.
Overage behavior. Do you pay per extra grab, or get hard-blocked until next cycle? A hard block can break a publish or a monitoring run at the worst moment.
What the free tier excludes. Free plans often gate full-page capture, custom viewports, or output formats. Confirm the free number is a real preview of the paid product, not a stripped-down one.
Feature parity across tiers. Some providers put the parameters you need (selector targeting, wait delays, WebP) behind a higher tier, so the cheap plan cannot actually do your job.

Test the integration before you pay a cent

You do not have to guess. Grabbit gives every account a test key (sk_test_...) that returns a placeholder image at no charge, so you can wire up the API and run it in CI before adding a card. Switch to a live key (sk_live_...) when you want real captures. Here is a real request:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "height": 720,
    "format": "webp",
    "full_page": true
  }'

The response includes image_url (the hosted screenshot), bytes, execution_ms, and id. Add delay_ms (up to 10000) to wait for JavaScript-heavy content, or selector to clip to a single element. Point at a sk_test_ key first: test captures are free placeholders, so proving out an integration costs nothing.

How to choose

Spiky or seasonal volume, quota waste is your pain: a flat prepaid plan like Grabbit (no monthly reset).
Steady, predictable monthly volume: a monthly subscription wastes nothing, and the per-grab math is what it is.
Lowest per-grab rate, willing to write scripts: Browserless.
Simple thumbnails, minimal budget: Thum.io.
Low, flat volume and you enjoy owning infra: self-host Puppeteer or Playwright.

For a full field comparison, see our honest comparison of the best screenshot APIs and the head-to-head ScreenshotOne alternative breakdown. If an agent is what needs to capture pages, the screenshots for AI agents guide covers the integration path. For Grabbit's pricing, parameters, and onboarding, see screenshots as a service.

Originally published on the Grabbit 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.

Open Graph Meta Tags: The Complete Reference (Every Tag, With Examples)

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

Open Graph meta tags are the snippets in your page's <head> that control how a link looks when someone shares it. Get them right and your URL unfurls into a rich card with a title, a summary, and an image. Miss them and the same link shows up as bare text. This is the complete reference: every tag worth setting, what each one does, and copy-paste examples.

The short answer: five tags

Most pages need exactly five Open Graph tags. Put these in the <head>:

<meta property="og:title" content="Your page title" />
<meta property="og:description" content="A one-line summary of the page." />
<meta property="og:image" content="https://yoursite.com/og/your-page.png" />
<meta property="og:url" content="https://yoursite.com/your-page" />
<meta property="og:type" content="website" />

Facebook, LinkedIn, Slack, Discord, iMessage, and WhatsApp all read these. Set them and your link previews work almost everywhere. The rest of this reference covers the optional tags and the X-specific ones.

The required tags, one by one

These five carry the card. Skip any of them and the preview degrades.

Tag	What it does
`og:title`	The headline of the card. Independent of the `<title>` element.
`og:description`	The summary line under the title. One or two sentences.
`og:image`	The picture in the card. Absolute URL, 1200 by 630 for the large card.
`og:url`	The canonical URL of the page, without tracking parameters.
`og:type`	The category: `website`, `article`, `video.movie`, and so on.

A few details that trip people up:

og:title is not your <title>. They can match, but og:title lets you write a version tuned for sharing. Keep it under about 60 characters so it does not truncate.
og:url should be the canonical URL. Use the clean permanent address, not the one with ?utm_source=... on it, so every share collapses to the same object.
og:image must be an absolute https:// URL. A relative path like /og.png will not resolve for the crawler. It also has to be publicly reachable: if the image needs a login, the card shows nothing.

The image tags that make the large card render

og:image alone works, but three companion tags make the difference between a big card and a small thumbnail:

<meta property="og:image" content="https://yoursite.com/og/your-page.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="A short description of the image" />

Declaring og:image:width and og:image:height lets the platform reserve the right space and render the large card immediately instead of guessing the dimensions on first fetch. Use 1200 by 630 pixels, the size every major platform treats as the full-width preview. og:image:alt is the accessibility description, read by screen readers on platforms that expose it.

The optional tags worth setting

Beyond the core five, a handful of tags add polish and matter for specific og:type values:

<meta property="og:site_name" content="Your Brand" />
<meta property="og:locale" content="en_US" />

og:site_name is the name of the overall site, shown as a small label on some cards (LinkedIn, for instance). Set it once to your brand.
og:locale declares the language and region, like en_US or fr_FR. Useful if your pages are localized.

When og:type is article, these structured tags become relevant and show up on news and blog cards:

<meta property="og:type" content="article" />
<meta property="article:published_time" content="2026-08-08T09:00:00Z" />
<meta property="article:author" content="https://yoursite.com/authors/jane" />
<meta property="article:section" content="Engineering" />
<meta property="article:tag" content="open graph" />

You only need the article:* tags on pages that are genuinely articles. For a marketing page or a landing page, og:type of website and the core five are enough.

X (Twitter) tags: what you actually need

X reads its own twitter: tags but falls back to your og: tags when they are absent. The one tag you should always set is twitter:card:

<meta name="twitter:card" content="summary_large_image" />

Without summary_large_image, X renders a small square thumbnail beside the text instead of the big image card. Note the attribute difference: og: tags use property=, while twitter: tags use name=.

You can stop there. X will pull the title, description, and image from og:title, og:description, and og:image. Only add these if you want a different headline or image on X than everywhere else:

<meta name="twitter:title" content="A headline tuned for X" />
<meta name="twitter:description" content="A summary tuned for X." />
<meta name="twitter:image" content="https://yoursite.com/og/your-page.png" />

A complete, copy-paste example

Here is the full <head> block for a typical article page, combining everything above:

<head>
  <title>Open Graph Meta Tags: The Complete Reference</title>

  <!-- Open Graph -->
  <meta property="og:title" content="Open Graph Meta Tags: The Complete Reference" />
  <meta property="og:description" content="Every og: tag worth setting, with examples." />
  <meta property="og:image" content="https://yoursite.com/og/reference.png" />
  <meta property="og:image:width" content="1200" />
  <meta property="og:image:height" content="630" />
  <meta property="og:url" content="https://yoursite.com/blog/og-meta-tags" />
  <meta property="og:type" content="article" />
  <meta property="og:site_name" content="Your Brand" />

  <!-- X (Twitter) -->
  <meta name="twitter:card" content="summary_large_image" />
</head>

How to generate the og:image from a URL

Writing the tags is the easy part. The hard part is producing a unique, on-brand og:image for every page without designing one by hand. The pattern that scales: build one HTML template that renders the page title and your branding, then capture that template as an image at 1200 by 630.

A screenshot API turns that into a single request. Point it at your template URL with a fixed viewport, and get back a hosted image you can drop straight into og:image:

curl -X POST https://grabbit.live/api/v1/grabs \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/og-template?title=Your+Post+Title",
    "width": 1200,
    "height": 630,
    "format": "png"
  }'

The response includes the hosted image URL. Set og:image to it, and every page gets its own preview card generated from real HTML, no design tool required. This is the same approach behind dynamic OG images in Next.js and any other framework: render a URL, screenshot it, ship the result.

For the deeper background on why the image matters and how platforms crop it, see what an OG image is. Once your tags are live, run the page through an OG image checker to confirm the crawler sees what you expect, and if a preview looks wrong, an Open Graph debugger shows you the exact tags each platform scraped.

Grabbit is a screenshots-as-a-service API built for exactly this job: point it at a URL, get back a hosted image, no headless browser to run. Live grabs are a flat $0.002 each on prepaid credits that never expire, and a test key renders free placeholders so you can wire up your OG pipeline before adding a card. See the screenshot API for the full reference.

Common mistakes

Injecting og: tags with client-side JavaScript. Crawlers run little to no JS, so they see an empty <head>. Server-render your meta tags.
A relative og:image path. It must be an absolute https:// URL, or the image will not resolve.
Forgetting twitter:card. Without summary_large_image, X shows a small thumbnail instead of the large card.
Not clearing the cache after a fix. Platforms cache the scrape. Use each platform's debugger to force a re-scrape once you have corrected a tag.

Originally published on the Grabbit 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.

Selenium vs Playwright: Which Should You Use in 2026?

Nico Acosta — Fri, 07 Aug 2026 11:42:57 +0000

Playwright and Selenium are the two tools most teams weigh when they automate a browser, and in 2026 the momentum is clearly with Playwright: it just passed Selenium in adoption surveys for the first time. But "which is winning" and "which should you use" are different questions. The right answer depends on your language, your existing suite, and whether you are automating tests or just need an image back from a URL. Here is the honest comparison.

The short answer

New project, JavaScript or TypeScript or Python: Playwright. Auto-waiting, a smaller API, and three bundled browser engines make it the faster path to reliable automation.
Existing enterprise Selenium suite, or a non-JS ecosystem (Java, C#, Ruby): Selenium is still a reasonable default. The WebDriver standard, the language breadth, and the grid ecosystem are hard to walk away from.
You need cross-browser tests with the least flakiness: Playwright. One API drives Chromium, Firefox, and WebKit, and auto-waiting removes most timing bugs.
You just need a screenshot of a URL, not a test framework: neither. A hosted screenshot API returns a hosted image from one request, with no browser to run.

The rest of this post shows where the two actually differ so you can decide with the details.

Architecture: WebDriver vs direct control

The core difference is how each tool talks to the browser.

Selenium drives browsers through the W3C WebDriver protocol. Your script sends commands to a driver (chromedriver, geckodriver), which relays them to the browser over HTTP. That standardization is Selenium's superpower and its tax: it works with almost any browser and language, but every command is a separate round trip.

Playwright talks to the browser over a single persistent connection using the browser's own debugging protocol. Fewer round trips, and it can observe the page state directly, which is what makes auto-waiting possible.

This one design choice explains most of the practical differences below: speed, waiting, and reliability all trace back to it.

Language and browser support

This is where Selenium still leads.

	Selenium	Playwright
Languages	Java, Python, C#, Ruby, JavaScript, and more	JavaScript/TypeScript, Python, Java, C#
Browsers	Chrome, Firefox, Edge, Safari (real installs) + huge grid/cloud ecosystem	Bundled Chromium, Firefox, WebKit
Standard	W3C WebDriver	Browser debug protocol (not a standard)

If your team is on Ruby, or you must drive a specific real browser build on a specific OS through a cloud grid, Selenium's breadth wins. If you want three engines that cover the matrix most apps care about, with zero driver management, Playwright's bundled browsers are simpler.

Note that "WebKit" in Playwright is the engine behind Safari, not Safari itself, so it is a very close approximation rather than a byte-for-byte Safari render.

Auto-waiting: Playwright's biggest day-to-day win

Flaky tests are almost always timing bugs. An element is not clickable yet, or the network has not settled, and a fixed sleep either wastes time or fails intermittently.

Selenium makes you manage this. The recommended pattern is an explicit wait:

const { Builder, By, until } = require('selenium-webdriver');

const driver = await new Builder().forBrowser('chrome').build();
await driver.get('https://example.com/login');
await driver.wait(until.elementLocated(By.css('#submit')), 5000);
await driver.findElement(By.css('#submit')).click();
await driver.quit();

Playwright waits for you. Its locators auto-wait for the element to be attached, visible, and actionable before acting, so the same flow needs no explicit wait:

const { chromium } = require('playwright');

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com/login');
await page.locator('#submit').click();
await browser.close();

Across a full suite, deleting hundreds of wait and sleep calls is the single biggest reliability and maintenance improvement teams report after migrating.

Speed

Playwright is generally faster, and the architecture explains why. Selenium's per-command HTTP round trips add up over a long test, and explicit waits are often padded to be safe. Playwright's single connection and auto-waiting mean it acts as soon as the page is ready, not after a fixed delay.

The gap is real on multi-step flows. On a single screenshot it is mostly noise, because page load time dominates and both tools spend that time the same way.

Locators: role and text over XPath

Selenium's world is CSS and XPath selectors tied to the DOM structure. That works, but a renamed class or an extra wrapper div breaks the locator.

Playwright still supports CSS and XPath, but pushes you toward user-facing locators that read the accessibility tree:

// Playwright: resilient, user-facing locators
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Email').fill('user@example.com');
await page.getByText('Welcome back').waitFor();

These survive DOM refactors because they find the button labelled "Submit" rather than its position in the markup. It is a small API difference with a big effect on how often tests break when the frontend changes.

Migrating from Selenium to Playwright

Migration is worth it when flaky tests and explicit-wait upkeep are costing you real time, and your app is JavaScript-heavy. The wait-code deletion alone often pays for the move.

It is not worth it when your Selenium suite is stable, your team lives in a language Playwright serves poorly, or your grid, reporting, and CI are deeply wired into WebDriver. A working suite is an asset; do not rewrite it for fashion.

If you do migrate, do it incrementally: run new tests in Playwright while the Selenium suite keeps guarding old ground, and port flaky tests first, because those are exactly the ones auto-waiting fixes.

Screenshots: where both tools are overkill

Both frameworks take screenshots, and the code is nearly identical. In Selenium:

const image = await driver.takeScreenshot();
require('fs').writeFileSync('page.png', image, 'base64');

In Playwright:

await page.screenshot({ path: 'page.png', fullPage: true });

But if a screenshot is the only thing you need, either tool is a lot of moving parts. You are installing a driver or a bundled browser, running headless Chromium in your own infrastructure, and owning the parts nobody enjoys:

Provisioning. Headless browsers need a long list of system libraries. Slim containers and serverless functions hit missing-dependency errors before the first pixel.
Memory and zombie processes. A browser not closed on every error path leaks memory and orphans processes until the box falls over.
Patching. Browser engines ship security updates constantly, so a long-lived capture service becomes a browser fleet you keep current.
Concurrency. One browser does one job at a time well. Thousands of captures a day means a pool, a queue, and back-pressure to build and operate.

None of that is test code, and it is the same whether you picked Selenium or Playwright.

The same capture as one API call

When screenshots are a feature you ship rather than a step inside a test, a hosted screenshot API skips the browser entirely. Here is a full-page capture as a single request to Grabbit:

curl https://api.grabbit.live/v1/grabs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1280,
    "full_page": true,
    "format": "webp"
  }'

The response includes a hosted image_url you can use directly:

{
  "id": "grb_01jx...",
  "status": "done",
  "image_url": "https://cdn.grabbit.live/grabs/grb_01jx....webp",
  "width": 1280,
  "format": "webp",
  "bytes": 48210,
  "execution_ms": 1180
}

The options you reach for in either framework map onto request parameters: fullPage becomes full_page, a locator or selector becomes the selector field, and a manual wait becomes delay_ms (0 to 10000). Width accepts 320 to 1920, height 240 to 1080, and format is png, jpeg, or webp. Pricing is a flat $0.002 per capture on prepaid credits that never reset, so a screenshot you run once a week costs the same per image as one you run a thousand times a day.

Which to choose

Greenfield project, want the least flakiness: Playwright.
Existing enterprise suite, or a non-JS stack, or a specific real-browser grid: Selenium.
Learning automation from scratch in 2026: start with Playwright, add Selenium for enterprise roles.
You just need an image from a URL, not a test framework: skip the browser and call an API.

For the framework-specific deep dives, see taking screenshots in Playwright and taking screenshots in Selenium. If you are weighing hosted options, the honest comparison of screenshot APIs covers the trade-offs without the marketing, and Puppeteer vs Playwright compares the two Chromium-first libraries head to head.

Originally published on the Grabbit blog.