Livemark

Guides

How much spec does an AI coding agent need?

Decide what an AI coding agent needs before it builds, with a CSV export example showing scope, permissions and acceptance cases.

By ·

Before you hand a feature to an AI coding agent, you have to decide how much to write down. A few lines might be enough to get it moving. But what if the agent fills in the gaps differently than you intended? You could write a detailed spec first, but how much of that work is useful before you've tried building anything?

Suppose the agent delivers a feature that runs, passes its tests and still doesn't do what you wanted. The missing piece might be a decision neither of you noticed was missing: who can use it, which records it acts on, or what should happen when there's nothing to show. Writing more about the implementation would not necessarily have answered those questions.

Give the agent the decisions it needs for the next piece of work. Describe the behavior you want, the boundaries it must respect and how you'll check the result. A small, familiar change may need only a short request. A feature involving permissions or customer data needs those decisions spelled out before the agent builds on a guess.

On this page:

Separate what to build from how to build it

Suppose you run an online shop. Each Friday, the person handling fulfillment needs the previous week's orders in a spreadsheet. They can filter the orders list by date and browse the results, but they have no way to download them. You ask a coding agent to add CSV export.

The agent still needs to know what that download means. Should it include only the orders matching the current date filter? Every matching order, or just the current page? Which fields does fulfillment need? Should anyone who can view an order be allowed to export it?

An implementation plan can list models, routes and components without answering any of those questions. The agent could follow that plan exactly and deliver the wrong behavior.

Here, “spec” means the agreement about what the feature should do. “Plan” means the approach to building it in the existing codebase. You don't need a separate PRD and technical spec to make that distinction. For a small feature, both can be sections of the same ticket or document: you settle the behavior, then the agent proposes how to build it.

For the export, “include all orders matching the date filter” is a behavior decision. Which existing query to reuse is an implementation choice. If that choice would expose orders from another account, it changes the promised behavior and needs to be reconsidered. It isn't something to leave buried in the plan.

GitHub's Spec Kit feature template makes a useful distinction: user journeys should be independently testable, and success criteria should be measurable without prescribing the technology. You can adopt that distinction without adopting the whole template.

Some of those questions need investigation; others need a decision from you. The existing code can show how the orders list applies account permissions and date filters. It cannot tell you which fields the person handling fulfillment needs in Friday's spreadsheet.

In Livemark, you can connect GitHub, choose which repositories the assistant can access and ask it to check that existing behavior from the document's chat. Let the assistant investigate what is already true, then bring the remaining choices to the people who need the export. You don't have to describe the codebase from memory before the conversation can start.

Make one feature specific enough to test

For the shop's weekly fulfillment task, start with the short request:

Add CSV export.

Two implementations could satisfy that request. One downloads the orders on the current page. Another downloads every order in the account. Neither tells you whether the export should respect the date filter the person just applied.

This is a useful point to have the assistant question the request. Skills such as Matt Pocock's /grill-me guide an agent through that conversation, following up as answers reveal more decisions. You can save your team's questioning procedure as a skill in Livemark and select it by typing / in the document's chat. For this export, ask it which choices about the file's contents are still unanswered, rather than asking it to produce a longer spec.

Work through those choices, then write down what the person should receive:

A person who can view orders can download those same orders as a CSV. The export includes every order matching the list's current filters, across all pages, within the account they are viewing. It contains order number, order date, total and currency, in that column order. The export does not grant access to orders the person cannot otherwise view.

Then make the less obvious choices explicit:

If no orders match, download a file with the column headers and no data rows. Customer names, email addresses and payment details are excluded. Scheduled exports and choosing which columns to include are outside this first increment.

The answers need to become part of the spec. If a teammate questions the headers-only result in a comment on that paragraph, settle the choice there and update the paragraph if the answer changes. An agreement buried in a conversation won't help an agent working from the document.

Now describe how you'll check that the implementation follows those decisions. An acceptance case is a concrete situation and the result you expect: given these orders and this date filter, which rows should the CSV contain? It gives you and the agent something specific to check instead of asking whether the feature looks finished.

For the export, write cases that would catch a working download with the wrong contents:

  • Apply a date filter that includes one order and excludes another. The CSV contains the matching order, not both.
  • More matching orders exist than fit on one page. The CSV includes matches from the next page too, without duplicates.
  • Another account has an order matching the same filter. That order does not appear in the export.
  • A person without permission to view orders requests an export directly. The request is rejected and returns no order data.
  • No orders match. The file contains the four column headers and no data rows.
  • An order has a customer email and payment details. The CSV still contains only order number, order date, total and currency, in the agreed order.

The first case gives the implementation a concrete wrong answer to catch: exporting all orders despite the active filter. The pagination case catches a different mistake: treating the rows currently visible on screen as the entire result.

Downloading a CSV is not enough to show that the feature meets the request. The file could open correctly and still contain the wrong orders. These checks tell you whether the person handling fulfillment gets the records they asked for, without prescribing a query or a CSV library.

Stop before you prescribe details nobody needs yet

This example does not name a database table, a component or a route. Those choices can follow the codebase's conventions. Add a technical constraint when it matters to correctness or compatibility, not to make the spec look complete.

For decisions that need to hold across features, see how to keep coding agents to your architecture.

For a small, obvious task, a separate planning document can be unnecessary. Anthropic's Claude Code guidance explicitly allows going straight to implementation for clear, small fixes.

Changing the export button's label from “Download” to “Export CSV” might need only that request and a check that the download still works. Changing which orders the export includes is different. The code change might be small, but you still have to decide whether the current filters apply. Skipping a written plan doesn't answer that question; it leaves the agent to choose.

Before you start, ask whether the agent can build and check the next piece without guessing at a product decision you haven't made. If it can, start there. If it can't, answer the missing question. When you don't yet know the answer, ask the agent to investigate it and bring back what it finds before building the feature.

That leaves room to change your mind. The Agile principles explicitly welcome changing requirements, even late in development. Write down what you've decided, mark what is still open, and update the spec when building or testing reveals something new.

Start with your next feature

For your next feature, start a spec in Livemark with the outcome you need. Use the document's chat to work through the unanswered questions, then turn the decisions into behavior the coding agent can build and check. For the export, that means knowing which orders and columns belong in the file, not writing out every route and component.

If you'd rather have that conversation with an external coding agent, connect it to Livemark through MCP instead. It can read the same spec and follow the team's skills. Whichever way you work, put the answers in the document so the next person or agent doesn't have to reconstruct them from chat.

You don't need to finish every future decision. You need a clear agreement about the next piece of work and a way to tell whether it does what you asked.