Skip to content

Guide · 6 min read

How to write a tech design AI agents can build from

Coding agents are good at building a well-described ticket and poor at guessing what you meant. The quality of what they produce follows the quality of what they read. This guide shows how to write a tech design that an agent can build from, in a form your team can review before any code exists.

Why a chat is a poor spec

Most features start as a conversation with an agent. By the end, the chat holds the plan: the approach you settled on, the one you rejected, the edge case you remembered halfway through. Then the session ends.

The next session starts from zero. A teammate's agent never saw it. Even inside the same chat, the decision from message 12 and its reversal in message 40 look equally valid to a model skimming the history. A transcript records how you got somewhere. A design says where you ended up.

One section per ticket

The most useful change is structural: split the design into sections, and make each section the source for one ticket.

A single long document forces every agent to read all of it, or to guess which part matters. With one section per ticket, the agent building the payments work reads the payments section and nothing else. Its context stays small and relevant, and two agents on two tickets do not trip over each other's details.

A good test: could you hand this section, alone, to someone who has never seen the feature, and would they build the right thing?

What a section needs

Keep each section short and concrete. Five parts cover almost every case.

Goal

One or two sentences on what exists when this is done. "Failed card payments are retried automatically" is a goal. "Improve payment reliability" is not.

Constraints

What must stay true. No double charges. The payment provider does not change. These are the lines an agent cannot infer from the code.

Behaviour and interfaces

The decisions other tickets depend on: the retry schedule, the table and its columns, the function another ticket will call, the states an order can be in. If two tickets have to agree on something, write it here, once.

Out of scope

What this ticket does not do. Agents are eager. Without this line, a ticket about card retries will also "helpfully" refactor the email sender.

How to check it

Acceptance checks a person or an agent can run: three attempts at the stated intervals, no second charge when an attempt is replayed, the order marked failed after the third.

Before and after

Here is a section as it often comes out of a chat:

Payments: add retries for failed payments. Use idempotency keys. Make sure we don't double charge. Should be configurable.

And the same section written to be built from:

Retries. A failed card payment is retried after 1 minute, 10 minutes, then 1 hour. Each attempt sends its own idempotency key. After the third failure the order is marked payment_failed and no further attempt is made.

Data. A payment_attempts table holds one row per attempt: order id, attempt number, idempotency key, status, provider error code.

Out of scope. Changing the payment provider. Retrying payment methods other than cards. The schedule is fixed, not configurable.

The second version is longer by a few lines and removes four guesses: how many retries, how far apart, what happens at the end, and whether "configurable" was a requirement or a passing thought.

Review the design, not the diff

The cheapest moment to catch a wrong approach is when it is one sentence. Review the design the way you review code: read it line by line and comment on the line you disagree with.

A reviewer reads "each attempt sends its own idempotency key" and asks how long the keys are kept. That one comment, answered in the design, saves a table that grows forever and a 2,000-line pull request built around it.

Two habits make this work. First, review before tickets are cut, so a change costs an edit and not a rewrite. Second, let an agent process the comments: it makes the change, says what it did, and resolves the thread, while the reviewer keeps the final say.

Keep it true while you build

A design that stops matching the code is worse than none. When an agent finishes a ticket and something turned out different, it should say so in the section: the column that was renamed, the limit that had to change. The next agent then starts from what is, not from what was planned.

Where Tuskway fits

Tuskway is built around this shape. Your agent drafts the design in sections with /write-design, each section tied to the ticket it becomes. Your team comments on lines, and any agent can work through the open threads. /draft-tickets turns sections into briefs with a goal, acceptance checks and the files to touch, and /tackle-ticket gives an agent that brief and its section. The same spec is read from Cursor, Claude Code, Codex, ChatGPT and other tools.

You can apply everything in this guide with markdown files and discipline. The tool matters once more than one person, or more than one agent, builds the feature.

Questions

How long should a tech design be?

As long as it needs to remove the guesses, and no longer. A section that fits on one screen is a good sign. If a section keeps growing, it is probably two tickets.

Should the agent or a person write the design?

Let the agent draft it from what you tell it, then review it as a team. Drafting is cheap for an agent; deciding is your job.

What if the design changes during the build?

Change the section, not just the code. A short note on what changed and why keeps the next agent, and the next reviewer, in step.

Run spec-driven development with your whole team.

Connect Claude Code, Cursor, Codex or ChatGPT, and run /start-epic on your next feature.