The Field Guide to Shipping Software

[ Chapter I ]

Ideas are free. Shipping isn't.

There has never been more free advice about what to build: feeds of startup ideas, trend reports, teardown threads. Much of it is good. Very little of it gets built.

AI made the typing part of software cheap. An engineer with good agents now writes far more code in a day than was possible a few years ago. You'd expect every product to ship faster. Some do. In our experience, many don't, because writing code was never the whole job.

Every product, at every size, needs four things done well:

• What to build. The one thing worth doing first, and a clear no to the rest. (Chapter II.)
• Who builds it. The right people, sized to the stage, working to one plan. (Chapter IV.)
• How it ships. Releases that reach users every week, not demos that reach a slide. (Chapters III, V, VI and IX.)
• What keeps it running. Production, money, data, and the day after launch. (Chapters VII to IX.)

AI helps with all four and replaces none of them. Cheaper code doesn't remove the hard parts. It makes them easier to see: deciding, integrating, reviewing and operating. That's what this guide is about.

It's written for founders and business leaders who commission or oversee software. It comes from the technology side of real products: deep fintech projects, AI engineering, and engineers working inside other companies' teams. It's opinionated on purpose, and it's based on what we've seen rather than on studies. Where it says "do this", that's what we'd recommend. Where your situation is different, trust your situation.

[ Chapter II ]

Decide what to build

In the projects we've seen go wrong, the failure usually wasn't in engineering. It came in the week someone decided what "version one" meant and nobody wrote it down.

Start the build plan

Before you commit to building, write six lines in plain words. They become the first sections of the template in chapter X:

1. The problem, in the customer's words, not yours.
2. Who it's for first. One kind of user, not everyone.
3. The one job version one must do. If it did only this, would someone use it?
4. What's out. The good ideas you're not building yet. This is the most valuable line on the page.
5. The riskiest assumption, and the cheapest way to test it.
6. How you'll know it worked: a number you can check in 30 days.

Say no early

Every feature costs something after launch. It has to be tested, supported, secured and explained. A feature that won't pay that back isn't free just because an agent can write it in an hour. Cheap code makes saying no more important, not less.

Prototype to decide, not to impress

A prototype exists to answer one question. Will they use it? Can we build it? Does the data exist? Build it in days and put it in front of the people who will use it. Then throw it away, or keep it on purpose. Exploring like this comes before the plan is final; committing to a production build comes after. A polished vision deck answers none of those questions.

[ Chapter III ]

Make the technical calls

Technical calls are cheap to make and expensive to undo. Make the expensive-to-undo ones slowly and the rest fast.

Build versus buy

Buy what every company needs and no customer notices: sign-in, email, payment rails, analytics, hosting. Build what makes you different, the part a customer would miss if it disappeared. When in doubt, buy now and keep the seam clean so you can replace it later.

Pick vendors by how you'd leave them

Before you sign, ask four questions:

• Can we export all our data, in a format we can use?
• What happens to our cost at ten times today's usage?
• What are the rate limits, and what happens when we hit them?
• If they shut down or get bought, how many weeks would it take to replace them?

Choose boring architecture

Use one well-understood database. Ship one deployable application with clear modules inside it before you split anything into services. Prefer managed infrastructure to self-hosted. Boring choices leave your attention for the product. Split something only when a real constraint forces it: one team keeps blocking another, or one part has a very different load.

Write decisions down

Give each decision one paragraph: what we chose, what we didn't, why, and what would make us change our mind. Keep these paragraphs in the repository. Six months later, they're what stops a new engineer, or a new agent, from undoing a good decision.

[ Chapter IV ]

Put the right team on it

There are three common starting points for a technology team. They can overlap: a company with a CTO can also have an asset to build on. Start from the one that describes you best.

• You have a CTO. You need people who work to their plan. They join the existing team, its tools and its definition of done. They follow your CTO's lead on architecture, and they raise risks and propose improvements rather than running a plan of their own.
• You don't have one yet. You need someone to lead the technology side with you: make the calls in chapter III, assemble the team and own delivery.
• You have an asset, not a product. Supplier access, data, a licence or an audience. Start with the plan in chapter II, then a small team to turn the asset into something people use.

How to embed engineers well

As of October 2026, ten of our people work embedded in client teams. The same few rules decide whether embedding works:

• Same tools, same rituals. Their tracker, their repository, their standup. No parallel process.
• A change in production in the first week, however small. It proves the access, the pipeline and the review path.
• One named person on the client's side who can answer "is this what you meant?" within a day.
• Written handover from day one, so nothing lives in only one head.

Size the team to the stage

In the first months, a small team of two or three strong people with good agents can often move faster than a much larger one, as long as the scope is narrow and one person makes the calls. Add people when there's a second stream of work, not when the first one is late. As Fred Brooks observed decades ago, adding people to a late project usually makes it later.

[ Chapter V ]

Build with AI without making a mess

In a well-run team, agents now write a large share of the code. The teams that get faster, rather than just noisier, keep a few rules.

Give agents the context a new engineer would get

Every repository gets a context file (AGENTS.md, CLAUDE.md, whatever your tools read). It says how to run the code, how to test it, what the conventions are, and which decisions from chapter III stand. An agent with context writes code that fits. Without it, the agent writes code that merely compiles.

Keep changes small, and review them like a junior's

Agents are fast, confident, and sometimes wrong in ways that look right. Keep changes small, and have each one reviewed by a person who understands the system. If a change is too big to review properly, it's too big to merge.

Tests are the contract

Ask for tests with every change, and read the tests first: they say what the code is meant to do. Have the important cases written or checked by someone who knows what the feature is for, separately from the code. Code and tests written from the same wrong assumption can agree with each other and both be wrong. For AI features, the equivalent is evals. They're examples of good and bad output, written with someone who does the job, and they run on every change.

Keep the model swappable

Models change every few months. Put the model behind one interface and keep prompts in files. An interface alone doesn't make a model swappable, though: tool use, output formats and the way models fail all differ. Let the evals tell you whether a new model does your job better, including how it fails. Use the cheaper model wherever it's good enough.

People own what agents can't be accountable for

Architecture, security, data access, and what ships when. An agent can draft any of these, but a named person decides.

[ Chapter VI ]

Unstick a stuck project

Stuck projects rarely look stuck. They look busy. These are the signs:

• Demos instead of releases. Something new to see every week, and nothing new for users.
• "Almost done" for more than two weeks.
• Only one person can explain how it works.
• Every estimate is for the whole thing, and nobody can say what ships first.

The first two weeks of a rescue

1. Get it running locally and in staging from the written instructions alone. Write down every step that wasn't documented.
2. Read the code and the open issues. List what's blocking, in order.
3. Ship one small, real change to production. It proves the pipeline works and resets the rhythm.
4. Cut the stuck feature down to the smallest version a user can use, and agree on it in writing.
5. Ship that. Then the next slice.

Don't rewrite on day one

The urge to start over is strong and usually wrong. A rewrite is a second project with the first one's deadline. Rewrite a part only once you understand why it's the way it is.

[ Chapter VII ]

When the product moves money

Money changes the rules. A bug in a feed is an annoyance. A bug in a ledger is a loss, a complaint and sometimes a question from a regulator.

Six rules that don't bend

• Ledger first. Double-entry and append-only. Balances are computed from the entries and never edited.
• No floating-point money. Store amounts as integers in the smallest unit, or as exact decimals (PostgreSQL's numeric, for example), with the currency next to every amount. Write down the precision and the rounding rules.
• Idempotency everywhere. Every request that moves money carries an idempotency key, created once per payment and stored with it, so a retry of the same request isn't processed twice. Check how long your provider keeps keys (Stripe, for example, can remove them once they're 24 hours old), and never reuse a key for a new payment.
• Reconcile every day. Compare your records with the provider's automatically, and have a person look at every difference.
• Audit every change: who, what, when and from where.
• Put providers behind one interface. Banks, card issuers and processors change. Your product shouldn't have to.

Compliance is a product requirement

Decide on know-your-customer checks, anti-money-laundering monitoring, data retention and who is licensed to do what together with the product, not after it. Regulated providers can carry much of this work, but using one doesn't automatically remove your own obligations. Write down who owns each one: you, the provider or a partner. Then integrate the providers properly and keep the evidence.

Build the operations tools early

At 11pm someone will need to freeze an account, refund a payment or explain a balance. Give them a screen for it before launch, not a database console.

[ Chapter VIII ]

When the user is an agent

More and more software is used by other software: agents that search, book, buy and file on someone's behalf. Building for them is a different job from building a screen.

• Clear contracts. Every tool or endpoint has a precise name, typed inputs and outputs, and errors an agent can act on. Vague tools get misused.
• Least access, enforced outside the model. Read before write. Check permissions in your own code, so a confused or tricked agent still can't go beyond them.
• Two kinds of action. Some can run on their own inside limits a person set in advance: spend up to a set amount, change only these records. Others need a person to approve each one on a review screen: moving money above the limit, deleting anything, anything you can't undo.
• Limits. Rate limits and spending limits per agent and per user, so one runaway loop can't run up a bill.
• Treat what the agent reads as untrusted. Web pages, emails, documents and tool results can carry instructions meant to hijack it (prompt injection). Nothing an agent reads should widen what it's allowed to do.
• Plan for a failure halfway. An agent can stop in the middle of a multi-step action. Make each step safe to retry, record what's done, and give a person a way to finish or undo it.
• A log a person can read: what the agent asked, what it got back and what it changed.

Protocols like MCP make it easy to expose a product to agents. That's exactly why you need to be careful about what you expose.

[ Chapter IX ]

Ship it, and keep it running

Launch is the start of the expensive part. Plan for it from the first week.

Agree what "done" means

A feature that works in a demo isn't done. Done means it meets the acceptance criteria you agreed before building it, handles the failures you expect (bad input, a provider timing out, a retry), is monitored, and has a named owner after release. Write that down for every release. Section 5 of the template has the lines for it.

What to have in place

• Release small and often, at least weekly. Use feature flags, so that shipping something and switching it on are separate decisions.
• A staging environment that looks like production, with realistic, masked data.
• Monitoring before launch, not after the first outage. Watch errors, latency and the one business number that tells you it's working.
• Someone on call, with a written runbook for the five most likely problems.
• Backups you've restored at least once. A backup you haven't restored is only a hope.
• Your running cost per user, including AI model costs. They grow quietly.
• A changelog that people outside engineering can read.

[ Chapter X ]

Your build plan

The whole guide on one page. Fill it in before you commit to a production build. Prototypes that test an assumption can come first; they're how you answer section 4.

Paste it into Claude Code, Codex or Cursor along with your notes. Ask it to fill in what it can and to list the questions it can't answer. Then answer those questions yourself. They're the ones that matter.

# Build plan: [product or feature]

From The Field Guide to Shipping Software, brightdot.tech/field-guide/

How to use it: fill this in before you commit to a production build. Prototypes that test an assumption can come first; they're how you answer section 4. Paste it into Claude Code, Codex or Cursor together with your notes. Ask it to fill in what it can and to list the questions it can't answer. Then answer those yourself.

## 1. The first user and their problem
Who they are (one kind of user, not everyone):
The problem, in their words:

## 2. The one job version one must do
The workflow a user can complete from start to finish:

## 3. Not now
Good ideas we're not building yet:
-

## 4. The riskiest assumption
What it is:
How we'll test it, and by when:

## 5. Done means
Acceptance criteria (what must be true before we call it done):
The failures it must handle:
How we'll monitor it:
Who owns it after release (see section 8):

## 6. First release
What reaches users first, and the date:

## 7. Technical calls
Build (what makes us different):
Buy (what every company needs):
Decisions, one paragraph each (what we chose, what we didn't, why, and what would change our mind):

## 8. Team and owners
Who, how many, and which starting point (you have a CTO, you don't have one yet, or you have an asset, not a product):
Who decides scope, priorities and trade-offs:
Who runs it in production:
The named person on the product side who answers "is this what you meant?":

## 9. Budget
What we'll spend to reach the first release:

## 10. Running it
Monitoring (errors, latency, the business number):
On call and runbook:
Backups (when were they last restored?):
Running cost per user, including AI models:

## 11. Outcome and decision
The number we'll check, and the date:
What result means we continue, what means we change direction, and what means we stop: