Most engineers write CLAUDE.md like a README. They put their stack, a few preferences, maybe a note about testing. The agent reads it and proceeds to write code shaped by its training data rather than their codebase. The file exists. It doesn't do much. The problem is category. A README describes a project. A specification constrains behavior. This post covers three dimensions of getting it right: how to structure the file across a real directory hierarchy, how to write rules the agent actually follows instead of weighs, and how to keep the file current as the codebase evolves.

The engineers who stand the test of time aren't the ones who chased every new thing, they're the ones who knew what was worth chasing. Every field has a surface and a foundation. The ones who only ever work the surface stay busy but never quite arrive anywhere. The ones who go deep find that the fundamentals they learned ten years ago are still paying interest today. That's not nostalgia. That's how engineering actually compounds ... not by accumulating tools, but by developing the judgment to know which problems are new and which ones just look that way.

You don't need new mental models to start a business. You need to recognize the ones your codebase already gave you, and the one place where they'll betray you.

Stop writing N+1 update loops. Learn how `update_all`, `update_columns`, and safe, batched SQL can drastically improve your Rails app's performance.

Every system operates on assumptions. Some are explicit—enforced by types, schemas, and validation. But the dangerous ones are implicit: "events are ordered," "usernames are lowercase," "this array is sorted." These invisible boundaries work perfectly until someone crosses them. Then a service that ran flawlessly for months suddenly explodes on "valid" data. The bug isn't in your logic—it's in the gap between what your system claims to accept and what it actually handles. Good architecture closes this gap by making boundaries impossible to cross incorrectly, not just expensive to cross incorrectly.

No platitudes, no theory. Just the exact system, templates, and tools I use to turn daily development work into a searchable knowledge base and high-quality blog posts.

Go beyond basic reliability. This is a complete operational manual for your Rails outbox, covering the four critical metrics, production-grade processor design with Sentry, forensic runbooks, and the anti-patterns that lead to silent failures.

Implicit state is a breeding ground for bugs. We'll refactor a typical Rails model to use a production-ready state machine, covering migrations, race conditions, testing, and audit trails to make your code safer and easier to reason about.

The app/services directory starts with good intentions but often decays into a junk drawer. We'll diagnose the symptoms of a service directory in crisis and explore how patterns like Form Objects, Commands, and Query Objects can restore clarity and maintainability to your Rails app.

Move beyond hardcoded strings and build a scalable, version-controlled, and testable prompt management system in Rails to manage your AI prompts like professional software.