I'm not a trained developer. I've got 30 years of IT under my belt and somewhere along the way I started building apps with AI. Lots of them. Over 70 GitHub repos in about a year.
For a while I was pure vibes. Describe the thing, let Claude Code run, see what happens. It works! Right up until it doesn't.
You know the feeling, three hours in and the AI has made seventeen decisions you didn't ask for, the scope has quietly doubled, and you're staring at code you don't fully understand trying to figure out why the thing it built isn't the thing you wanted.
I found a fix. It's not sexy. It's a document.
The PRD
PRD stands for Product Requirements Document. Sounds corporate. Isn't.
It's just you writing down, before a single line of code gets written, what you're actually building. What it does. What it doesn't do. What "done" looks like.
Mine have a pretty consistent structure:
- What it is, two or three sentences, plain English
- Must-Haves, the things without which it doesn't ship
- Nice-to-Haves, the things that can wait
- Non-Goals, explicitly what this thing will never do
- MVP Milestones, numbered, small, shippable checkpoints
- Stack, exact tech choices, decided upfront
- Risks, the stuff most likely to blow up
That last one is underrated. Writing down "the audio pipeline on iOS has a 60-second session limit" before you start means Claude Code gets told about it upfront, not after it's already built something that breaks because of it.
The CLAUDE.md
The PRD is for you. CLAUDE.md is for your AI.
It lives in the project root and it's the first thing Claude Code reads when it picks up your project. Think of it as the standing orders. It covers:
- The tech stack in a table (exact packages, exact versions)
- Code stubs for anything complicated or easy to get wrong
- A Gotchas list, things that will bite you if not addressed early
- A Scope Guard, one line that says "do not add features not in this file"
- A Build Checklist, the steps to verify the thing actually works
That Scope Guard line is doing more work than it looks like. Without it, AI assistants are genuinely trying to be helpful, so they'll add things. Error handling you didn't ask for. A feature that seemed related. A refactor of something that was fine. The CLAUDE.md tells it: no. Build what's here.
The workflow
- I write the PRD. Usually with Claude's help in chat, I describe the app, it helps me think through edge cases and structure.
- I turn that into a CLAUDE.md, adding stack details, gotchas, and stubs.
- I hand it to Claude Code with: "Read CLAUDE.md. Build Milestone 1 only."
- We go milestone by milestone.
That's it.
The whole thing takes maybe an hour before any code runs. But I've stopped having days where I throw away half a build because it went in the wrong direction. I've stopped getting AI hallucinations about my own app's structure. I've stopped arguing with the model about scope.
Why it works
AI coding assistants are powerful but they're stateless. Every session they start fresh. Without a document that says exactly what this thing is and how it should be built, they're making it up as they go, and so are you.
The PRD and CLAUDE.md aren't about process for process's sake. They're about giving the model (and yourself) a fixed point to return to. A north star the conversation can't drift away from.
I ship more, I throw away less, and when I come back to a project after two weeks I'm not re-explaining everything from scratch.
Write the doc first. Then vibe.
I build local-first apps under the Axly's Customs banner, no telemetry, no subscriptions, built for people who'd rather own their tools. More of this kind of thing lives at axly.com/blog.