When I first started building *Stellar Throne*, I never imagined I'd be writing documentation for an AI coworker.
Like most game developers, I began the project with a loose roadmap and a lot of excitement. I wrote systems. I rewrote them. I built tools, UI, asset pipelines—whatever I needed in the moment. But as I started using Claude and ChatGPT as pair programmers and assistants, a new kind of bottleneck emerged: **they didn’t know what the project was about.**
## The Communication Gap
Human developers can browse the repo, skim README files, infer naming patterns, and ask clarifying questions. Claude can’t—at least not yet. Without context, it would hallucinate code that didn’t match the architecture, invent nonexistent files, or follow a style that clashed with mine.
It wasn’t Claude’s fault. It just didn’t have the context.
So I built it.
## What CLAUDE.md Is
**CLAUDE.md** is a living specification file that gives AI tools like Claude the context they need to work effectively within the codebase. It defines:
- 🎯 The **purpose** of the project
- 🧱 The **architecture** and folder structure
- ✍️ The **coding style**, naming conventions, and idioms
- ✅ The **testing philosophy** and where tests live
- 🚧 The **technical constraints** and known trade-offs
- 📐 The **"how" and "why"** of choices I don’t want second-guessed
- ❗️A list of **Do’s and Don’ts** for AI collaborators
It’s not a replacement for human-readable documentation. It’s a bridge between human intention and AI execution.
## Why It Matters
With CLAUDE.md in place, I can now prompt Claude with high-level tasks like:
> “Add a notification system for ground invasions using the existing UI and manager patterns.”
And it will generate something that matches my architecture, fits the style, respects the game’s systems, and integrates cleanly—often with fewer corrections than a junior developer would need.
It’s not magic. It’s **context**.
## The Meta-Magic: Claude Auditing Its Own Manual
Here’s where things get interesting—and a bit recursive.
Once CLAUDE.md was in place, I realized I could use Claude itself to improve the very document that guides it. It’s like asking a new employee to review their own onboarding manual and suggest improvements based on what confused them.
I’d prompt Claude with things like:
> “Review CLAUDE.md and suggest improvements.”
>
> “What rule should I add to CLAUDE.md so you don’t do XYZ?”
The results were enlightening. Claude would point out:
- Implicit conventions I’d forgotten to document
- Edge cases in the architecture I took for granted
- Messaging patterns between managers that seemed obvious to me but weren’t written down
- Testing strategies that had evolved beyond what the documentation described
Each audit session became a feedback loop. Claude would struggle with a task, I’d update CLAUDE.md to clarify the confusion, and the next interaction would be smoother. It wasn’t just documentation anymore—it was a **living contract between human and AI**, refined through actual use.
This meta-approach revealed something profound: the best documentation for AI isn’t written in isolation. It’s forged through collaboration, with the AI itself as both reader and editor. Every stumbling block becomes a documentation opportunity. Every successful task validates what’s working.
The document evolved from a one-way instruction manual into a **two-way communication protocol**—one that gets better every time we use it.
## The Real Purpose
More than anything, CLAUDE.md is about **trust**.
I want to trust that my AI assistant understands the project. I want to trust that it won’t break things I care about. I want to trust that when I ask it to help, we’re speaking the same design language.
That trust doesn’t come from smarter models alone—it comes from better communication. And CLAUDE.md is how I communicate with AI.
It’s documentation with a reader that never gets tired, never forgets, and never stops learning. And in a project that grows more complex by the day, that’s worth its weight in silicon.
