All Articles
Beyond Tools in MCP: Designing with Resources, Prompts, and Sampling
Cramming everything into MCP tools hits a wall fast. Here is how resources, prompts, and sampling untangle a server, told through a real wallpaper-app asset manager I cut from 14 tools down to 5.
Guard Your Agent's Destructive Operations with Pre- and Post-condition Contracts
A design for wrapping an autonomous agent's writes in deterministic pre- and post-condition checks. A contract gate stops the destructive operations that better prompts can never reliably prevent.
Before You Send Reviews and Crash Logs to the Claude API: A Reversible PII Masking Design
When you run App Store reviews and Crashlytics logs through the Claude API, the personal data buried in the text is unavoidable. Here is a reversible masking design that lets you trace the model's output back to the real record, plus the pitfalls I hit in production, with code.
Grouping Crashes by Root Cause: A Triage Design Built on the Claude API
Crashlytics 'Issues' often scatter the same root cause across separate entries. After years of running apps with 50M+ cumulative downloads, here is how I use the Claude API to regroup crashes by actual root cause and rank them, with working code and real numbers.
Isolating Poison Messages in a Claude Async Pipeline: A Dead-Letter Queue Implementation Note
How one broken input can stall an entire batch — and how to isolate these 'poison messages' with a Cloudflare Queues dead-letter queue. Covers classifying Claude API failures and safe redrive, all from production experience.
Make Agent Failures Reproducible: Deterministic Replay and Event Sourcing
An autonomous agent that fails at 2 a.m. can't be reproduced by simply running it again. Record every nondeterminism boundary as an append-only event log and replay the failed run deterministically — with working code and operational lessons.
Continuing past max_tokens in the Claude API without duplicated text or broken code fences
Detect stop_reason: max_tokens, continue the generation with an assistant prefill, and stitch the parts back together without duplicated seams or broken code fences. A production-tested continuation pattern in TypeScript.
Catching Claude Quality Regressions With an Eval Harness
I tweaked a prompt by one line and, for a different set of inputs, the output quietly got worse. Here is the eval harness I built to protect Claude's production quality across every prompt change and model update, with full implementation code and real operating numbers.
Diagnosing invalid_request_error When You Pass an Image URL to the Claude API
When the Claude API rejects an image you passed via `source.type: url`, the root cause almost always lives in one of four buckets: scheme, MIME, size, or reachability. Here is the diagnostic order I use in production.
Splitting Claude API prompt cache into 5m and 1h tiers — separate TTLs cut cost and stabilize ops
Anthropic's cache_control supports two TTLs: 5 minutes and 1 hour. Splitting them into a two-tier layout — 1h for static system/tools, 5m for variable few-shot — meaningfully changed both my costs and my on-call life. Here's the design with the numbers I observed.
Rewiring Claude API Observability with OpenTelemetry GenAI Conventions — A Design Memo for Model Migrations and Cost Audits
An implementation memo for rewiring production observability around Claude API to match the OpenTelemetry GenAI semantic conventions — span attributes, metrics, cost tracking, and model-migration replay — written from running this in indie services for six months.
Why JSON.parse Fails on Claude API Streaming tool_use Arguments — and How to Fix It
When you stream a Claude API response with tool_use, calling JSON.parse on each input_json_delta throws SyntaxError. Here is the correct way to assemble partial_json fragments, plus disconnect handling.