← Writing

03·4 min·AI

Notes on building with Claude

Editorial hero for the essay Notes on building with Claude. Left panel: title, dek 'Prompt design, retrieval, and evaluation harnesses,' byline. Right panel: a flowchart starting at an accent-colored 'prompt, treated as UI, versioned in the repo' box, into a diamond asking 'does this need a vector database?' — usually routing to 'a SQL query, or grep, most AI features we ship,' sometimes routing to 'embeddings + retrieval, rare in practice' — both feeding an accent-colored 'evaluation harness, the hard part' box, which either ships or, on a dashed path, iterates and loops back to the prompt.

Most advice on integrating AI into products comes from one of two camps: people selling a wrapper, or people warning that it's all hype. Neither is useful if you actually have work to ship.

We've been building with Claude across a handful of products — an auto-blogging plugin, a couple of mobile app prototypes, internal tooling. A few patterns keep coming back.

The prompt is the interface

People think of prompts as strings you send to an API. They're actually product UI.

Every prompt encodes a way of thinking — a shape of output, a tolerance for ambiguity, an implicit user model. Treat them the way you'd treat a form design. Iterate. Version them in your repo. Write down what you changed and why.

RAG is overrated; retrieval is not

You don't always need a vector database. Sometimes you need a well-structured JSON file, a SQL query, or a grep. Match the sophistication of retrieval to the actual problem, not to what's fashionable on the timeline.

Half the AI features we've shipped pull their context from a single database table.

Evaluation is the hard part

Anyone can wire up an LLM call. What's hard — and what most tutorials skip — is knowing whether the output got better or worse after you changed the prompt last week.

We invest more in evaluation harnesses than in generation code. A golden set of thirty to fifty inputs, a rubric, and a small script that flags regressions. It's not glamorous. It's what makes the thing work.

A prompt, treated as UI and versioned in the repo, answers one question: does this need a vector database? Usually the answer routes to a SQL query or a grep; sometimes it routes to embeddings and retrieval. Either way it passes through an evaluation harness — the hard part — before it ships or is rewritten and re-run.

It earns its place

We don't add AI because we can. We add it when the alternative is worse for the user — typically when they'd otherwise face a blank page, a heavy setup task, or a tedious classification.

The test isn't whether it's impressive. The test is whether the product is better without having to explain it. That connects directly to our broader stance on quiet software — features should justify themselves by getting out of the way, not by announcing their arrival.

If you're thinking through an AI integration and want another set of eyes on it, the AI and machine learning work is where we spend most of our time right now.