The problem nobody tells you about
An AI agent is brilliant and amnesiac. Every session it woke up knowing nothing about my codebase — the conventions, the traps, the decisions already made. It would relearn, guess, and sometimes confidently do the wrong thing. Ninety percent of "AI coding disappointment" I've seen comes down to this, and the fix is unglamorous: you have to build the context infrastructure yourself.
The skill system
I built a custom Claude Code skill set that loads the project's conventions on demand.
/brief is a one-shot session kickoff — the agent gets the architecture, active
constraints, and current priorities in one command instead of re-reading 200 lines of
instructions. /audit-seeds checks all 33 seed scripts for idempotency violations.
/validate-component verifies component props against their schemas before
anything lands. /diff-astro compares the Drupal render and the Astro render of
the same component, because parity drift is how headless sites rot. /improve
captures durable session learnings into a memory store, so the system compounds.
The repo onboards itself. Any agent — or any engineer — is oriented in one command. That's the test of whether your context infrastructure is real.
Guardrails, because agents are confident when they're wrong
- Validation in front of everything. Component props schemas, seed idempotency audits, and an SEO parity suite that gates releases. Agents move fast; gates make fast safe.
- Hard rules enforced by the harness. Rules like "never skip verification" and "rotate leaked secrets at source" run as hooks the runtime executes. Discipline that lives in tooling survives; discipline that lives in memory doesn't.
- Watchdog-first debugging. Before any file spelunking, read the Drupal log: one
drush watchdog:showreplaces ten misdirected greps. I taught the agent this habit and it changed the economics of every debugging session — human or machine. - Memory-driven context. A curated index of ~30 durable project notes; the agent loads the two that matter for the task at hand. Context is a budget. Spend it like one.
A failure, because those are the real lessons
Drupal's Single Directory Components accept two input source types that look interchangeable
and aren't — mix js.* and sdc.* component inputs and you get a
runtime InvalidComponentInputsPropSourceException in production. An agent walked
straight into it, confidently. That failure became a rule the agent now loads at session
start, and it generalized into the operating pattern: every agent mistake becomes a
guardrail. The system gets safer the longer it runs. Most teams do the opposite —
they let the same mistake happen quietly forever.
The judgment part
Deterministic first. Before I reach for the model, I ask whether a 30-line Python script solves this once and forever.
Mirroring a redirect table, batch-transforming markup, sweeping a content tree for missing alt text — that's pattern matching, and pattern matching doesn't need a frontier model. It needs a script that runs free, forever, deterministically. The model gets the work that actually requires reasoning. This one habit is the difference between AI adoption that compounds and AI adoption that shows up as a shocking API bill and no velocity.
Why this matters to a team
I built this as one engineer, which means the scaffolding — skills, runbooks, gates, memory — is the transferable part. It's also teachable: before this I spent a year as a corporate trainer, on-site at AT&T, Verizon, and Chase, getting rooms of skeptical engineers to adopt tools they didn't ask for. AI adoption is that same job. The technology got better; the human problem didn't change.
Practice areas: agentic development workflows, Claude Code, custom agent skills, prompt and context engineering, LLM guardrails and validation gates, AI developer productivity, deterministic automation in Python / Bash / PHP.