Value propositions for coding agents

Day 21: The Value Proposition Is an Engineering Input

Your agent can ship forty green tests for a feature nobody asked for. It isn't being careless. It builds what the ticket implies, and if the ticket never says why the feature matters to the customer, the agent has to guess. You get clean code that solves the wrong problem. One sentence about customer value is the cheapest fix you have, and most tickets don't include it.

The hook: a polished feature for the wrong problem

This example is a composite of tickets I've seen across several teams. The ticket was short and looked fine. The agent took a few minutes and came back with clean code, passing tests and a tidy PR description. Here's the ticket next to the result:

TICKET (as written)
-------------------
Title: Add CSV export to Reports page
Body:  Users want to export report data to CSV.
       Should support all report types.

WHAT THE AGENT BUILT
--------------------
- Export modal with a column picker (drag to reorder)
- Date range selector with 8 presets
- Delimiter option (comma / semicolon / tab)
- Generic CSV writer, ISO dates, raw numeric amounts
- 40+ unit tests, all green

WHAT THE CUSTOMER ACTUALLY NEEDED
---------------------------------
A clinic finance manager closes the month by importing invoices
into their accounting software. Today they copy the table into
Excel and fix date formats, credit notes and GST columns by hand
before the import will accept it.

The agent did exactly what the ticket asked for. Read 'users want to export' plus 'all report types' and any sensible reader would build a flexible, general exporter. That's what it built. Now picture the finance manager using it. They open the modal, pick columns, download the file, and then lose most of the afternoon in Excel fixing it anyway. The code was fine. What went wrong is that nobody wrote down who the feature was for or what it had to change for them.

The reframe

A senior teammate picks up intent without trying: a hallway chat, a comment in standup, a complaint over lunch. An agent hears none of that. Anything your team leaves unsaid about customer value, the agent fills in with its default assumption, and that default is nearly always 'generic and configurable'.

Where this fits in the course

Earlier lessons covered who your customer is and what job they hire your product to do. Today you'll compress that into a single line a machine can act on.

What a value proposition is, in plain words

A value proposition is one sentence saying who the feature is for, what it changes for them, and how you'll know it worked. For engineering work, use this template:

For [customer] who [struggles with X],
this [feature] [does Y],
unlike [current workaround],
so they [measurable outcome].

Don't treat this as a writing exercise. Every slot changes what the code should optimise for. Here's what each one does to the build:

• ▹For [customer] sets the defaults, the vocabulary and how much configuration to offer. A finance manager doing month-end close wants a correct default, not a column picker. Put a power analyst in that slot and the flexible exporter becomes the right build.
• ▹Who [struggles with X] tells you which failure hurts most, so you know which edge cases to protect. If the struggle is 'imports get rejected', a malformed date is a P1 bug. If it's 'data is hard to find', the same malformed date is cosmetic.
• ▹This [feature] [does Y] is the core path, the one thing that has to work end to end. Everything off that path is optional and needs its own reason to exist.
• ▹Unlike [current workaround] tells you what not to rebuild. When the workaround is Excel, don't recreate Excel's column editing inside your product. Get rid of the reason they open Excel at all.
• ▹So they [measurable outcome] turns into your acceptance criteria and test assertions. You can test 'import accepted on first try'. You can't really test 'users can export data', because a wrongly shaped file still counts as an export.

The agent read test (10 minutes)

If you only keep one habit from today, keep this one. You don't need to guess whether your value prop is clear, because you can test it. Open a fresh agent session with no repo context, no CLAUDE.md and no chat history. Paste in only the value prop and the ticket, then ask:

Here is a value proposition and a ticket. Do not write code.

1. Describe the feature you would build, in 5-8 bullets.
2. List what you would deliberately leave out, and why.
3. List the edge cases you would treat as must-not-fail.
4. State the default behaviour a first-time user sees.
5. Name any assumption you had to make because the text didn't say.

VALUE PROP:
<paste>

TICKET:
<paste>

Compare the answer with what you had in mind, paying most attention to points 2, 4 and 5. Every place the agent's plan drifts from yours points to a gap in your value prop. Fix the sentence, not the agent's reply, then run the test again. Two rounds is usually enough. The session has to be fresh because the one you're working in already carries context that the agent doing the actual implementation may never see.

Before and after: the same ticket, rewritten

BEFORE
------
Add CSV export to Reports page.
Users want to export report data to CSV. Support all report types.

AFTER
-----
Value prop:
For clinic finance managers who lose an afternoon each month
fixing exported invoices before their accounting software will
accept them, this invoice export produces an import-ready file
in one click, unlike copying the table into Excel and cleaning it
by hand, so they close the month without manual reformatting and
the import is accepted on the first attempt.

Ticket:
Add 'Export for accounting' to the Invoices report only.

On the read test, the agent's plan changed like this:

• ▹Fewer screens. The column picker, delimiter option and date presets disappeared, leaving one button with last calendar month preselected.
• ▹A different default: output that matches the accounting software's import format (date format, tax column, account codes) rather than a generic ISO dump.
• ▹New edge cases it protects. Credit notes go out as negative amounts on their own lines. Invoices issued near midnight get dated in the clinic's timezone, not UTC. Either mistake would get the file rejected.
• ▹It cut scope without being asked. Other report types were left out because they're 'not part of the month-end close outcome'.
• ▹The test checks the outcome now: a fixture file validated against the import schema, rather than just 'file has N rows'.

Three smells that mean your value prop is still fuzzy

• ▹It names a feature instead of an outcome. 'Users can export to CSV' describes a button. Ask what's different for the customer after they press it.
• ▹A competitor could use it unchanged. If the sentence would fit a rival's ticket word for word, it doesn't explain why your customer needs this from you. Usually the 'unlike' slot is what's missing.
• ▹Two engineers, or two agents, build noticeably different things from it. Run the read test twice, or with two different models. If they disagree on defaults or scope, the sentence still leaves too much open.

The subtraction payoff

Once the value prop is sharp, the agent starts telling you what not to build, and most of the real speed comes from there. In the export example there was a follow-up item in the backlog: 'Scheduled email exports (daily/weekly)'. We ran it against the value prop and the agent flagged it. The outcome is a once-a-month close done by someone sitting at their desk. Scheduled delivery doesn't move that outcome, and it adds new ways to fail (email deliverability, stale data). We dropped the item without anyone having to win an argument, because the one line had already settled it.

That's the skill this lesson is about. Engineers who only build fast end up shipping more things. Engineers who can write and test a one-line value prop ship fewer things, get more of them right, and keep their reviews short because the agent's output already matches the intent.

When to use it, and when not to

• ▹Use it on any ticket an agent will implement that touches user-facing behaviour, defaults or scope.
• ▹Write it before you split an epic, so every child ticket traces back to the same outcome.
• ▹Pure refactors, dependency bumps and infra chores don't need the full template. A one-line 'why now' covers it.
• ▹Pitfall: writing the value prop after the build to justify what you made. At that point it's decoration and doesn't steer anything.
• ▹Pitfall: filling the outcome slot with vanity metrics like 'increase engagement'. Choose something you could check with one real customer next week.

Today's exercise

• ▹Pick one open ticket that you or an agent will work on this week.
• ▹Write its value prop in one sentence using the five-slot template.
• ▹Run the agent read test in a fresh session and note every gap between the agent's plan and what you meant.
• ▹Revise the sentence and test again until the plan matches, including what gets left out.
• ▹Post the before/after (original ticket, value prop, agent plan diff) in your team channel.

Tomorrow, Day 22: you know the value, so how do you tell whether it actually landed? We'll look at measuring outcomes instead of output, and why that matters even more now that agents make output almost free.

Extend your knowledge

• ▹Geoffrey Moore's 'Crossing the Chasm' is where the 'For [customer] who... unlike...' structure comes from. Look at its positioning statement template.
• ▹'Competing Against Luck' by Clayton Christensen et al. uses Jobs to be Done, which will make your 'struggles with X' slot much sharper.
• ▹Try Strategyzer's Value Proposition Canvas on one feature. Then squeeze the canvas into a single line and run the agent read test on it.
• ▹Read Anthropic's Claude Code best-practices guidance on giving specific instructions and writing CLAUDE.md files, and think about adding a 'Value prop' field to your team's ticket template.