The engineering behind the agents.

Every non-trivial build starts as a one-page markdown spec under specs/ or docs/plans/. Four fields: Intent (one paragraph, plain English), Constraints (stack, conventions, what not to touch), Context (what the agent must read first), and Acceptance criteria (a testable checklist).

The spec is the contract; the implementation follows it. The point isn’t more documentation — it’s removing ambiguity beforecode exists, so the agent never has to guess. When the bottleneck moves off the keyboard, the hard part is no longer implementation. It’s clarity.

Generated content — restaurant copy, neighborhood voice, itineraries — never ships on the strength of one model’s output. A separatemodel scores it against tasting notes: factual accuracy, voice match, no hype words. The judge isn’t a vague “is this good?” — it scores against explicit, weighted criteria, and anything below threshold routes to manual review instead of publishing.

The discipline is in treating the judge as a regression test, not a rubber stamp. I’ve written about the tasting-notes approach and about a same-day regression the eval caught before it reached anyone.

Chat answers are constrained to retrieved chunks. Content lives in MDX, chunked by heading, embedded with text-embedding-3-small (1536 dims) and stored in Postgres + pgvector behind an HNSW index. Retrieval is cosine distance, top-k 5, with a similarity threshold tuned to the embedding model rather than copied from a spec.

The model is instructed to answer only from what it retrieves and to acknowledge gaps rather than invent. A low-confidence fallback runs a second, looser search and surfaces the nearest sections instead of claiming nothing matches. Same pattern across this site and the product chatbots — see how the chat works for the real retrieval traces.

The editorial systems are agentic in the literal sense: structured data goes in, and a multi-phase Claude Code pipeline runs it through voice-aware enrichment and judge scoring before emitting publication-ready MDX. The same MDX file then feeds both the rendered page and the RAG index — one source, two consumers.

Voice is handled per domain. Each product carries its own voice.md (sometimes one per neighborhood), and voice files are style only — identity facts live in the indexed content so they can be cited honestly rather than asserted. Most of these systems are bilingual: English and Brazilian Portuguese as first-class, with locale-aware retrieval, not a translation bolted on at the end.

The same patterns run inside enterprise healthcare, where the constraints are real. As a Senior Enterprise Architect at Scripps Health, I led the introduction of agentic coding to the engineering team — standing up Anthropic models via Azure AI Foundry and establishing how agentic patterns apply under security, compliance, and change-management requirements.

That’s the difference between a demo and a discipline: making agentic engineering survive contact with audit trails, legacy integrations, and a regulated environment — not just a greenfield side project.