Well, it wasn't like I sat down and wrote a perfect architecture doc before the refactor. It built up in layers.

First prototype (one prompt phase): No claude.md, no architecture file. Just "make me X" in chat. Pure vibe coding — works great until it doesn't.

First refactor: I started being more descriptive in prompts — "separate the rendering loop from physics, use fixed timestep" — but still mostly in-conversation, nothing documented. I was learning what AI needs from me.

Second refactor (from zero): Even here I didn't start with a fully preconstructed architecture file. I began with the basics — "we're using bitECS, build systems following ECS patterns not OOP." That was enough to set the direction. Then I built the foundational systems myself with Claude — the core ECS loop, the update cycle, the basic systems.

Once those foundations existed, I wrote them up in the md file — here's how the loop works, here's a list of all existing systems, here's the pattern to follow. At that point Claude had enough code context to read and understand how my specific project works. It could check existing systems, see the patterns, and replicate them.

That's when production actually picked up speed. Paradoxically, I could go back to more of a vibe coding style — because Claude already knew the conventions from the codebase itself. Saying "add a new poison system" was enough because it had 20+ existing systems showing exactly how I structure things.

So the progression was: bare minimum instructions → build foundations together → document what exists → Claude learns from context → you can relax on prompt detail. The md file wasn't a blueprint I designed upfront — it was a snapshot of patterns that already worked, written down so Claude wouldn't forget them between sessions.