The Architecture of Building With AI: PLAN.md, CLAUDE.md, and the System That Builds Itself

The Problem Most People Hit

Here’s how most AI projects go. You start a conversation. You describe what you want. The AI builds something great. You iterate for twenty minutes, maybe an hour. Then the context window fills up, the session ends, and when you come back… the AI has forgotten everything. Your project goals, your design decisions, the conventions you spent an hour establishing. Gone.

So you start over. You re-explain the project. You re-state the constraints. By the third or fourth session, you realize you’re spending more time catching the AI up than actually building.

This is the wall most AI-built projects hit. Not a lack of capability. A lack of memory.

And it’s the difference between two fundamentally different approaches to building with AI. Vibe coding is describing what you want and hoping for the best. It works brilliantly for getting started. But the moment a project grows beyond a single session, you need something more deliberate. You need agentic coding: systems that sustain themselves across sessions, across context resets, across the inevitable gaps in AI memory.

This post is about how I built that system for this site. Two plain-text files and a structured interview that turned Claude Code from a brilliant-but-forgetful assistant into a persistent build partner.

Plan Mode: The Interview That Defines Everything

Every feature on this site starts the same way. Before a single line of code gets written, I ask Claude Code to enter Plan Mode.

Plan Mode is a structured scoping process. Instead of jumping straight to “build me a blog,” it forces a conversation about scope. What are we building? What framework are we using? What constraints exist? Who is the audience? What does “done” look like?

Think of it like the discovery phase at the start of a consulting engagement. You wouldn’t walk into a client meeting and start executing without understanding the problem first. Plan Mode is that meeting.

Here’s what happens in practice. I tell Claude Code I want to add, say, a glossary to the site. Instead of immediately generating code, Plan Mode asks questions: How should terms be stored? Should they have individual pages? What metadata do they need? How do they connect to blog posts? What does the URL structure look like?

By the time the interview is done, there’s a clear plan that both sides agree on. Only then does building begin.

This isn’t unique to Claude Code. Lovable has a similar planning flow. Cursor’s Composer mode walks through requirements before generating. Windsurf’s Cascade does the same. The specific tool matters less than the principle: scope before you build.

What most people skip is this step. They type “build me a website” and wonder why the result doesn’t match their vision. The interview is the most important part of the process. It’s prompt engineering at the project level, not the message level.

PLAN.md: Persistent Memory Beyond the Context Window

Once Plan Mode produces a plan, that plan needs to live somewhere the AI can find it next session. That’s PLAN.md.

PLAN.md is a Markdown file that sits in the root of my project. It contains everything Claude Code needs to understand this project at the start of any session:

What the project is and why it exists
What’s been built (completed phases, with one-line summaries)
What’s in progress (active phases, with full detail)
What’s next (future phases, with enough detail to understand scope)
Architecture decisions already made (framework, hosting, DNS, design tokens)
What’s been consciously deferred (and why)

When Claude Code starts a new session, it reads PLAN.md. Instantly, it knows this is an Astro site, not React. It knows the color scheme is navy and gold. It knows the blog uses content collections. It knows which features are done and which are next. No re-explaining. No drift.

This is project memory in its simplest form. Different tools solve this differently. Cursor has memory banks. SpecStory records entire sessions. Some developers use README files or wikis. The format doesn’t matter as much as the principle: your AI needs a way to remember decisions, not just conversations.

And the word “decisions” is key here. PLAN.md doesn’t record every conversation I’ve had with Claude Code. It records the outcomes. “We chose Astro over Next.js because we want static HTML output.” “We deploy to Vercel with auto-deploys from GitHub.” “Blog posts use this frontmatter format.” These are the things that prevent drift. They’re the institutional knowledge of the project.

CLAUDE.md: Operating Instructions That Compound

If PLAN.md is what the project is, CLAUDE.md is how to work on it.

CLAUDE.md is a system prompt that lives inside the project. It tells Claude Code the rules, conventions, and workflows to follow every time it touches the codebase. Here are some of the things this site’s CLAUDE.md defines:

Linking strategy: Every technical term links to its glossary page. External links only live on glossary pages, never in blog posts. This is a deliberate information architecture choice.
Blog tone: Conversational, no em dashes, technical details woven naturally, written for someone who is smart but has never opened a terminal.
Commit rules: Never auto-commit. Complete a meaningful unit of work, then pause and explain what was done.
Content workflow: Three paths to a published post (build audit, rough draft, prompt-driven), each with clear steps.
Glossary conventions: Every term gets “How It’s Used on This Site” with real on-site examples. Tool entries include a “Try It” section with the external link.

This is where the compounding happens. Every rule in CLAUDE.md is a decision I only had to make once. The first time I decided that blog posts should link to glossary pages instead of external sites, I wrote it in CLAUDE.md. Now Claude Code does it automatically. The first time I decided that commit messages should be suggested but never auto-executed, I wrote it down. Now it’s the default behavior.

This pattern exists across tools. Cursor uses .cursorrules files. Windsurf uses rules files. GitHub Copilot has custom instructions. The concept is the same: a persistent configuration that shapes how the AI behaves on your specific project. The difference between a generic AI assistant and one that feels like it knows your project is usually just a well-written system prompt.

And here’s the insight most people miss: CLAUDE.md isn’t just instructions. It’s automation. When it says “automatically identify technical terms and create glossary entries,” that’s not a reminder for me. It’s an instruction that makes Claude Code do the work. Every blog post I write automatically produces new glossary terms. Every glossary term automatically includes on-site examples. The system does the tedious work so I can focus on the thinking.

The Self-Referential Loop

This is where it gets interesting.

PLAN.md says: “Build The Vibe-Coder’s Dictionary.” So I build the glossary. CLAUDE.md says: “Link every technical term to its glossary page.” So every blog post I write links to glossary terms. Some of those terms don’t exist yet, so CLAUDE.md says: “If a glossary entry doesn’t exist, create it in the same session.” So writing a blog post generates new glossary terms. Those glossary terms include “How It’s Used on This Site” sections that link back to blog posts and project pages. Those project pages link to blog posts. Those blog posts link to glossary terms.

The system feeds itself.

Write one blog post, and six new glossary terms appear. Those terms link to the blog post. The blog post links to project pages. The project pages link to more blog posts. Every piece of content creates connections to other content, and every connection creates a reason for a visitor (or a search engine) to go deeper.

This is context engineering in practice. Not just managing what the AI sees in a single session, but designing a system where output becomes input for the next cycle. The glossary makes blog posts better. Blog posts make the glossary bigger. A bigger glossary makes future blog posts easier to write because more terms already have pages.

It’s the same principle behind compound interest, but for content. And it’s all governed by two plain-text files.

What I Haven’t Built Yet

I want to be honest about where this system is today versus where it’s going. Some of this is real and working. Some of it is aspirational.

What’s working now:

PLAN.md and CLAUDE.md keep Claude Code aligned across sessions
Blog posts automatically generate glossary terms
Cross-linking between posts, terms, and project pages is systematic
The build log on the project page tracks every phase

What’s planned but not built:

Hover tooltips. Right now, glossary links are regular text links. Eventually, hovering over a linked term will show the definition inline, so readers don’t have to navigate away from the post they’re reading.
Automated term detection. Right now, CLAUDE.md tells Claude Code to identify technical terms. Eventually this could be a build-time plugin that automatically detects unlnked terms and flags them.
Memory across tools. PLAN.md works great for Claude Code, but there’s no unified memory layer that works across Claude Code, Cursor, and other tools simultaneously. Each tool has its own memory system, and they don’t talk to each other yet.
RAG integration. The glossary could feed into a retrieval system so the AI automatically finds relevant definitions when writing new content, instead of relying on CLAUDE.md instructions.

Each of these is a future post and a future build session. The architecture is designed to accommodate them. That’s the point of building in phases: each phase adds capability without requiring a rewrite of what came before.

Why This Matters If You’re Not an Engineer

Here’s the thing. Nothing I just described requires you to know how to code.

PLAN.md is a document. It’s written in plain language. It describes a project, its goals, what’s been done, and what’s next. If you can write a project brief, you can write a PLAN.md.

CLAUDE.md is a set of rules. It’s written in plain language. It describes how the AI should behave, what conventions to follow, what tone to use. If you can write a style guide or an employee handbook, you can write a CLAUDE.md.

Plan Mode is a conversation. The AI asks questions. You answer them. If you’ve ever been through a discovery session with a consultant, you already know how this works.

The shift from vibe coding to agentic coding isn’t about learning a programming language. It’s about learning to think architecturally. Defining scope before building. Creating systems that remember decisions. Setting conventions that compound over time. That’s business thinking applied to software.

There is a parable about this. “For which of you, desiring to build a tower, does not first sit down and count the cost, whether he has enough to complete it?” (Luke 14:28). Jesus was talking about discipleship, not software. But the principle is the same: the person who plans before building finishes what they start. The person who jumps in without counting the cost ends up with an abandoned foundation. Plan Mode, PLAN.md, CLAUDE.md, all of it is just counting the cost before you build.

The tools handle the code. You handle the architecture. And honestly, the architecture is the harder part, the part that most developers undervalue and most business people are already good at.

How to Set This Up Yourself

If you want to try this approach, here’s where to start:

Start with Plan Mode. Whatever AI tool you’re using, don’t jump straight to “build me a thing.” Ask it to interview you first. Define the scope, the audience, the constraints. Get specific about what “done” looks like.
Capture the plan in a file. Create a PLAN.md (or whatever your tool calls it) in your project root. Record what the project is, what’s been built, what decisions have been made, and what’s next. Update it at the end of each session, not during.
Write your operating instructions. Create a CLAUDE.md (or .cursorrules, or whatever your tool uses). Define your conventions: file organization, naming patterns, tone, linking rules, commit behavior. Every decision you put here is a decision you never have to make again.
Build the self-referential logic. This is optional but powerful. If you have a glossary, a blog, project pages, or any recurring content type, set up rules that connect them automatically. “Every blog post links to relevant glossary terms.” “Every glossary term mentions where it’s used on the site.” “Every project gets a companion blog post.” The connections are what make the system compound.
Work in phases. Don’t try to build everything at once. Pick one feature, scope it, build it, document it, move on. Each phase teaches you something and adds capability for the next one.

The tools are evolving fast. Six months from now, the specific files and formats might look different. But the principles won’t change: scope before you build, create persistent memory, define conventions that automate your preferences, and design systems where output feeds back into input.

If you’re trying to figure this stuff out, feel free to reach out. I’m building all of this in public for a reason.

Where This Post Fits

This is the second entry in the build log for this site. The first post covered the migration from Lovable to Astro. The third post documented building The Vibe-Coder’s Dictionary. Each one is a layer on top of the last, and each one was built using the system described here.

The architecture came first. Then the tools. Then the content. Then more architecture to support more content. It’s turtles all the way down, and that’s exactly the point.

What makes any of this worth doing is not the system itself. Systems are impressive until they are not. What makes it worth doing is whether the system serves something that matters. AI can build faster than any of us imagined. The question that endures is not “how fast can you ship?” It is “are you building on rock or sand?” (Matthew 7:24-27). The tools will change. The frameworks will change. The answer to that question will not.