Agents are human. PRD or die!

Christian Saugmann

21h (edited) • 💬 General discussion

Agents are human.

PRD or die!

Ok, maybe not human, but human like.

Enough to create chaos and wreak havoc.

Enough to take you to the edge of insanity, if you're not careful.

If you don't write a solid Product Requirements Document.

Note: These are my observation after having worked with Windsurf, Cursor, and now Claude Code in both the app and in VS Code, building a web app with a Firestore set-up and some complex business logic. I'm not an AI expert, I'm not a developer, but I have about 20 years of experience working in fintech. Mainly as a product manager, managing teams of developers and business analysts, working with architects and other stakeholders.

What do I mean by human like?

In my experience, at this point in time, AI agents are as good or better than the best developers.

For good or for worse.

So, let me elaborate. On this potential issue, on confusion, my sins, and that special place in hell.

As a product manager, I've worked with overloaded backlogs of items I wanted to build.

I've had a million requests from stakeholders, many half baked.

I've come in fresh to teams who had gone down one particular path, with a set in stone architecture, and, important, terminology and concepts that were in no way logical to the outsider.

Like a company isn't a company.

Say what!?

Yes, once decided, something completely illogical become logical, or at least sets a standard. Even for supposedly standard terms, everyone makes assumptions based on their own experience and context.

In all these cases, working with smart and dedicated people, I have experienced chaos and havoc, when we didn't take the time to define exactly what we wanted to build. That's why I say "agents are human.", or at least "agents are human-like."

A) They are as good or better than good developers.

B) Each time you run a session with an agent, it's like working with a new developer on the team.

Without context, they will make assumptions to do the job you ask them to.

This is of course what Jake has been preaching for a long while.

You need to direct the agents and give them context.

However... I see a major pitfall when using AI.

One that I sense many folks overlook.

It's sooo easy to get lazy.

And ask the agent to build something, based on half baked instructions.

There is a special place in hell for product managers who give developers poorly defined requirements.

Hand on heart, there is a slight chance that one day, you can find me down there, in the flames, or by an ironing board or whatever evil punishment is measured out.

And if you're not a certified developer, when using agents, well then my friend, you're a product manager.

So, to save you from flames and ironing boards, I'd like to share how I document product requirements.

How I plan work in a way that removes ambiguity when working with humans and agents.

Note: It can be a high friction process (it may require hard thinking). But the harder you find the process, the more critical it is to document. Because that's a sign of complexity or at least lots of options that need steering and navigation.

Note (again? really?): These are my terms. I've set them as standards when I develop. Some of them I've borrowed. Others I've picked the best word and made a hard definition in my documentation. So, if these terms have a different meaning to you, then please set that aside. This is my standard. Set in stone until I decide to redefine something. Don't get hung up on the terms, focus on the approach.

Note (what, another frigging note!?): I'm working on a web app, with a broad scope (calculators, online courses, a gear inventory, a trip planner, and more in the future). So, I needed to expand the way I manage functionality. If you work on a lighter app, you can probably do away with the "module" level.

Here's a summary of the hierarchy.

Level 1 - module

The app has several MODULES, for specific functional areas, e.g. my "quartermaster" gear management and trip planner." Often a top menu item.

Level 2 - features

Each module has several FEATURES, which are groups of functionality, like the inventory feature in quartermaster. Often a menu sub-item or a menu item inside the module.

Level 3 - user stories

Each feature is defined via several USER STORIES. The feature often evolves over time. I might launch a feature with the first batch of stories (what I refer to as p0), and then add single or batches of user stories (p1, p2, pn).

Importantly, I describe each module, feature, and user story using the common user story statement.

As a [user type] I want to [action/goal] So that [benefit/value].

I want to stress that, I use this formula for both modules, features and user stories, to make it clear what purpose each level serves.

For each user story, the central elements are the 3C

Card - the story statement from above
Conversation - 2-4 sentences: the problem in plain language, the proposed solution, and what is out of scope.
Confirmation - Acceptance criteria (see below)

The story doc contains more stuff like a very light status tracker, and a reading list etc., but the 3C is the product management core.

Level 4 - acceptance criteria

Each user story has several ACCEPTANCE CRITERIA. An acceptance criterion is WHAT the user must be able to do, not so much HOW. At least not for UI user stories.

Note (not again!): For UI user stories, the HOW is the design, and these days I get Claude Design to create a high-fidelity prototype so I can test the user experience for how the app will actually work. I use the user story documents as input for Claude Design. Plus design system.Acceptance criteria is a bundle of different types of criteria.

[User action and expected result]
If [field] is empty, show "[validation message]" below the field
If [condition], then [behaviour]
If [error condition], show [error message/state]

Sometimes I cover all the above types. Other times it's only one or two.For context, my standard development process is:

Module creation
Feature creation
User story design (tollgates 1-3)
Documenting how to build (tollgates 4a-c and 5)
Build and ship (tollgates 6-10)

At the end of tollgate 3, what needs to be built should be clear and unambiguous.

And on this basis, plus existing architecture and existing design standards and perhaps new design prototypes, agents can research best practice and document how to build.

In some cases I have a strong opinion on exactly how things must work or look.

This is the core of my app's value proposition.

It ties in to the business logic I have designed for the system my app supports.

In other cases, e.g. user management, I ask agents to use best practice. I want it to work, but I don't have a strong opinion. And often I'm severely lacking technical knowhow.

Sometimes User Story Design is straightforward, but often I go through some iterations between Claude Design and user story design before it's all dialled in, for a single story, and across a batch of stories.

Iterations take longer, but when they happen, it's on the edge of my value prop, and critical work that's worth doing.

I'm starting to use skills and the Jake style documentation to make documenting how to build and build and ship as automated as possible.

The only stops being me performing User Acceptance Testing at staging (tollgate 9) and switching production flag in tollgate 10.

Ok, this is my process.

One that I have tweaked and adjusted based on lessons learned and as my project grew.

I started with a simple prompt for each piece of work. And ran each "user story" (not as detailed as what I've shown above) in a single session.

My process might be more than you need.

You may need to tweak it to suite your projects.

Or you might think I'm insane and that it's garbage.

Either way, I hope the above will make you pause and consider how you approach things. I hope this post has given you food for thought to help improve the way you build tech using AI.

All the best,

Christian

PS.I've got a family, a fulltime job, the app I'm working on and much more. So I can't promise to respond to all comments or questions.

PPS. In case I've said something that conflicts with anything Jake has said, ignore my statement. I'm not an AI expert. I can't write a single line of code. I'm just sharing a small corner of how I build tech using Claude Code, based on the lessons I've learned (including Jake's lessons) And, the above is indeed a small corner. There are a lot of other things going on in my particular set-up so this is not all I do to manage agents and sub-agents.

6 comments