The Shift
Sometime in early 2025, I stopped thinking of AI as a coding assistant and started treating it as an architectural partner. The difference is fundamental. An assistant waits for you to ask questions. A partner has context, opinions, and memory. That shift changed how I structure every project.
PLAN.md + CLAUDE.md: The Two-File Contract
Every project I build now starts with two files before any code is written. PLAN.md describes what we're building — the architecture, the data model, the deployment target. CLAUDE.md contains the rules of engagement: conventions, forbidden patterns, preferred libraries, and project-specific instructions that persist across sessions.
This is not documentation for humans. It's a contract with the AI. When Claude Code opens a session, it reads these files and understands the project at a level that would take a new developer days to reach. The result is that every session starts at full speed, not from zero.
> "AI is an architectural partner, not an autocomplete tool."
The Workflow in Practice
A typical development session looks like this:
- I describe a feature in natural language, often referencing a feature plan doc (e.g., docs/features/F39-interactives.md)
- Claude Code reads the plan, the existing codebase, and the CLAUDE.md conventions
- It implements the feature across multiple files, respecting the project's patterns
- I review, adjust, and commit
The key insight is that the quality of the output is directly proportional to the quality of the context. Vague instructions produce vague code. A well-structured PLAN.md with clear architectural decisions produces code that fits the system like a glove.
What I've Learned
After a year of building this way, a few things are clear:
- Convention files are more valuable than type systems for AI-assisted development. Types catch errors; conventions prevent them from being written in the first place.
- Small, focused sessions beat marathon ones. The AI maintains context better, and so do I.
- The architecture you'll be proud of in five years is the one that was obvious to understand on day one. AI amplifies this principle — it builds better code when the architecture is clean and explicit.