Skip to content

deep dives

Engineering, explained

Long-form writing on the systems I build and the way I build them — from first principles to a production cutover. The depth that doesn’t fit in a README, written so it’s useful whether you’re new to the idea or reviewing my work. Everything I publish lands here.

Featured essay

Document-Driven Development (D³): Docs Are the Interface Your AI Works Through

Docs-as-Context Engineering — a document-type-partitioned, frontmatter-governed engineering wiki wired straight into your AI agents, so business rules, architectural decisions, and every fixed bug become durable context instead of tribal memory that evaporates between sessions.

14 min read

Series · 7 parts

Background Jobs From Scratch

From “why your BackgroundService isn’t enough” to a money-moving production cutover — building a job system that’s idempotent, atomically enqueued, dead-lettered, observable, and secure.

  1. 01Why Your `BackgroundService` Isn't Enough — and What a Real Job System Looks LikeA tour of the 2026 options for .NET background work — and why choosing the engine is the easy 20% while the reliability wrapper around it is the real job.12 min read
  2. 02The Worker Host — a Dedicated Service, Not a Thread in Your APIStanding up a standalone Hangfire worker, its own SQL schema, three queues, two servers, and a drain ladder that survives a deploy.14 min read
  3. 03The Job Contract — Idempotency, Kill Switches, and the 'Runs Twice' RuleWhy every background handler must survive running at least twice, and the exact shape — message, runner, binding — that makes that convergence structural.14 min read
  4. 04The Outbox — Why "Enqueue Then Commit" Is a Lie, and How to Fix ItMake the enqueue atomic with the state change by writing it into the same SQL transaction — table, claim SP, and dispatcher included.15 min read
  5. 05When Jobs Fail — Retry Classification, the Dead-Letter Queue, and ResilienceTransient vs permanent, one global retry curve, and a dead-letter table that never lets a death vanish.15 min read
  6. 06Security & Observability — Schema-Write Is RCE, and You Can't Fix What You Can't SeeLeast-privilege SQL, an enqueue allow-list, and the one outbox gauge that tells you the whole pipeline is stalled.15 min read
  7. 07Production Patterns — Async Image Uploads (202 + Poll) and Retiring a Legacy Scheduler Without Double-Paying AnyoneThe UX-visible payoff of the whole scaffold, and the legacy-scheduler cutover war story — a non-idempotent money job — that justifies every part's caution.16 min read

Series · 3 parts

Claude.md Mastery

Treating an agent's context file as a contract, not a manual — how to keep it lean, let it auto-load the right rules per module, and grow it without ever bloating again.

  1. 01Your CLAUDE.md Is Probably Too Big — How I Cut Mine by 78%A 30-minute, mechanical cleanup that cut a 1,014-line CLAUDE.md to 221 — using the three loading mechanisms Anthropic actually built, and the one trick that stops it bloating again.8 min read
  2. 02Nested CLAUDE.md, Deep — When to Split, Where to Put It, and How BigThe highest-leverage, least-used mechanism in Claude Code: directory-scoped context files that auto-load only in their subtree. When to create one, where it goes, how big it should be, and what belongs in root versus nested.11 min read
  3. 03The # Workflow — Growing CLAUDE.md Without Ever Editing ItPre-written rules are guesses; rules you add the moment you hit them are real. The # shortcut lets Claude route a one-line note to the right CLAUDE.md, summarize it, and save it — so the file grows itself, at 100% signal.9 min read