I want to write the post I wish had existed before I started.
Most writing about building with Claude API or any LLM API falls into one of two categories: breathless hype about how AI will change everything, or step-by-step tutorials that stop right where the real problems begin. Neither of those helped me when I was three weeks into an integration that wasn’t working the way I expected.
This is the honest account. The product, the decisions, the things that broke, and what I would do differently.
The Problem
The client was a mid-sized media company — a WordPress-based publication with a small editorial team producing several long-form articles a week. The bottleneck wasn’t writing. It was briefing.
Before any article was written, an editor had to produce a brief: the angle, the key questions to answer, the competing coverage to be aware of, the suggested sources. For a team producing 15–20 pieces a week, that briefing work was consuming two to three hours a day of a senior editor’s time. Time they would rather have spent editing the actual work.
They had tried to solve this before. Templates. A shared Google Doc with a prompt they’d paste into ChatGPT. A Notion database that nobody updated. None of it stuck because none of it lived where the editors actually worked — inside the WordPress backend where articles were created.
The ask was straightforward: build something inside WordPress that would help editors generate first-draft briefs based on a working title, without making them context-switch to another tool.
Why Claude API
I chose Claude for three reasons, none of which were loyalty to a brand.
First, the output quality on structured, context-rich editorial tasks was consistently better in my testing. I ran the same brief-generation prompt through three APIs. Claude’s output required less cleanup and followed the format I specified more reliably.
Second, the context window. Editorial briefs benefit from being able to include the article title, a category taxonomy, related articles already published, and sometimes a rough notes dump from the commissioning editor. That’s a lot of input. I needed room to work.
Third, I wanted streaming support. I already suspected the latency problem was going to be my biggest UX challenge, and I needed an API that would let me stream tokens to the frontend. Claude’s API does this cleanly.
The Design Decisions That Mattered
Decision 1: Where in the workflow to live
The first prototype surfaced the feature as a standalone panel in the WordPress sidebar — a “Generate Brief” button that appeared on every new post. This was wrong.
Editors told me they didn’t want it at post creation. They wanted it earlier — during the commissioning stage, before an article was even assigned. The feature was solving the right problem in the wrong place in the workflow.
I moved it upstream. The revised version lived on the editorial planning board (a custom post type used for commissioning), not on the article post itself. Usage tripled after that change.
The lesson has nothing to do with AI: build the feature where the workflow actually lives, not where it’s technically convenient to add it.
Decision 2: Streaming vs. waiting
The brief generation call takes between three and six seconds depending on the complexity of the input. I tested three approaches to making that wait bearable.
Option A was a spinner with a “Generating your brief…” message. Users clicked the button again. Every time. They assumed it had frozen.
Option B was a skeleton loading state — placeholder lines that gave a sense of the structure being built. Better, but users still checked their email during the wait and lost context when it finished.
Option C was streaming. Text appeared token by token, typewriter-style, from the moment the first tokens arrived from the API. Editors watched it build. They stayed engaged. A few told me they found themselves reading as it generated and already had notes forming before it finished.
Streaming won decisively and it wasn’t close. If you are building with Claude API and your response time is over two seconds, streaming is not optional. It changes the product.
Decision 3: Prompt architecture
The first prompt I shipped was entirely engineered by me. It was structured, detailed, and almost completely useless to the people using it.
The briefs it produced were too long, too generic, and structured in a way that matched how I thought about editorial briefs, not how the editors did. I had written a good prompt for myself.
I fixed this by sitting down with the senior editor for ninety minutes and asking her to walk me through how she actually wrote a brief when she did it manually. Not the ideal version — the real version, with all the shortcuts and priority calls.
That conversation changed the prompt entirely. The structure shortened. The tone changed. References to competing coverage moved from a late-document appendix (where I had put them) to the second element (where she always put them). The “suggested questions” section that I thought was the most valuable part got cut — she never used it when briefing writers.
The best prompt engineering I did on this project happened in a conversation that had nothing to do with prompts.
What Didn’t Work
The “just regenerate” problem. Because regeneration was one button click, editors quickly developed a habit of clicking it multiple times and picking the version they liked best. This sounds fine until you realise that each regeneration is a different interpretation of the same input — and the act of choosing between them became a task of its own. Briefs that had previously taken one generation started requiring three or four.
I added a light friction: a “refine” mode where editors could note what they wanted to change before regenerating, rather than blank regenerating. This produced better briefs, reduced regeneration volume by about 60%, and — unexpectedly — produced briefs that editors felt more ownership over because their judgment was part of them.
Context window mismanagement (early versions). In the first builds I was including everything: article title, category, recent articles in the same category, SEO keywords, any commissioning notes. The outputs were comprehensive and wandered. I was giving the model so much that it tried to address all of it.
I progressively restricted the input until I found the minimum context that produced a useful output. Ironically, less context produced more focused briefs. The model needs direction, not information dumps.
Error state design. API calls fail. Rate limits happen. Network blips happen. My first error handling was a red toast notification that disappeared in three seconds. Editors didn’t see it, clicked the button again, got another failure, and assumed the feature was broken.
Error states need to be persistent, clear, and tell the user what to do next — not just that something went wrong.
Five Things I Would Tell Myself Before Starting
1. Solve the UX for latency before you write a single prompt. Decide whether you’re streaming or not, and design the loading state first. Everything else follows from that decision. A fast, bad-output feature has a path to good. A slow, bad-output feature gets abandoned.
2. Your first prompt is for you, not for the user. Don’t ship until you’ve watched a real user interact with the output and told you what’s wrong with it. The gap between what you think is useful and what is actually useful will surprise you every time.
3. The integration is the easy part. The Claude API is well-documented, straightforward to authenticate, and reasonably predictable. The hard work is product thinking: where does this live, what does it replace, what friction does it add, what friction does it remove.
4. Build for the unhappy path from the start. Errors, timeouts, rate limits, and malformed outputs are not edge cases. They’re regular occurrences at scale. Design your error states with the same care you design your success states.
5. Less context is often more. Give the model what it needs to do the specific job, not everything you think might be relevant. Specificity of input produces specificity of output. Information dumps produce comprehensive wandering.
What It Looked Like at the End
The feature shipped after about six weeks of build and iteration. The senior editor who had been spending two to three hours a day on briefs now spends about forty minutes. The briefs are not perfect — she edits them every time — but they’re good enough to be a starting point rather than a blank page.
That’s a meaningful outcome. Not because of AI. Because someone understood a workflow problem well enough to build something that actually fit inside it.
Building with Claude API is accessible. The documentation is good, the API is clean, and the capability is genuinely impressive. What is not simple is building something useful with it — that requires product thinking that no API can substitute for.
If This Was Useful
I write occasionally about building AI products, consulting, and the decisions that don’t make it into tutorials. If that interests you, the newsletter is the best way to follow along — sign up below.
If you’re working on an AI integration and could use a thinking partner or a second set of eyes on the product decisions: that’s something I do.
