What Goes in CLAUDE.md, and What Belongs in an ADR
You read the previous post and pasted the why into CLAUDE.md, and now that paragraph rides along on every task the agent ever runs. The sign belongs there. The reason doesn’t.
Systems Thinking
ADRs for AI-Assisted Codebases: Write Down Why, or the Agent Will Undo It
ADRs were written for the future engineer who asks ‘why is it like this?’ That engineer is now an AI agent, it arrives in minutes instead of years, and it doesn’t ask - it refactors.
When Home Assistant Becomes the Family API
The moment you automate your home, everyone who lives in it becomes a user of a system they never agreed to. Here’s how to design for people who didn’t consent to being users.
Context Is an Architectural Surface
Context isn’t what you paste into the prompt. It’s what the model sees, prioritizes, and is constrained by. That’s not prompting — that’s system design.
Stop Betting on One-Shot: A Practical Workflow for Shipping with LLMs
LLMs don’t ship software. They ship text. You ship software by constraining the problem until text reliably becomes change sets you can trust.
Why AI Still Sucks at Your Job (and Why That Won't Last)
The bottleneck was never intelligence. It was instrumentation. Once we learn to define what systems should do, the execution becomes trivial.