The Claude Code Project Template That Closes the Loop: PRD → Plan → Build → Validate → Track¶

Most people use Claude Code like a chat window: type a request, accept the diff, repeat until it works or breaks. That's fine for a one-off script. For a real project it falls apart fast — the agent forgets decisions, rebuilds things it already built, and you lose track of what's actually done.

The fix isn't a smarter model. It's a project structure that gives the agent memory, process, and guardrails. I found a template that nails this: code-template — a Claude Code starter that defines the full coding loop with 5 files and 3 slash commands. This post walks through how it works and why each piece earns its place.

Credit: the template's structure and workflow originate from the Claude Code Agentic RAG Masterclass by The AI Automators. code-template is my working copy of it.

The Full Loop at a Glance¶

The template turns "chat with an AI" into a repeatable engineering cycle:

┌──────────┐    ┌─────────┐    ┌──────────────────┐    ┌──────────┐    ┌─────────────┐
│  PRD.md  │───▶│  /plan  │───▶│  .agent/plans/   │───▶│  /build  │───▶│  Validate   │
│ the goal │    │         │    │ 1.auth-setup.md  │    │          │    │ tests + MCP │
└──────────┘    └─────────┘    └──────────────────┘    └──────────┘    └──────┬──────┘
                                                                              │
                     ┌────────────────────────────────────────────────────────┘
                     ▼
              ┌─────────────┐
              │ PROGRESS.md │──── next session: /onboard reads this and picks up where you left off
              └─────────────┘

Every artifact is a markdown file in git. The agent's memory isn't the chat history — it's the repo. Kill the session, come back tomorrow, run /onboard, and Claude knows exactly where you are.

The 5 Files That Run the Show¶

PRD.md — define the goal before any code exists¶

The template's PRD isn't a corporate spec. It's tight and machine-readable: what we're building, target users, an explicit in-scope / out-of-scope list, the stack as a table, and hard constraints.

The out-of-scope list is the underrated part. Agents love to gold-plate. This PRD says it plainly:

### Out of Scope
- ❌ Knowledge graphs / GraphRAG
- ❌ Multi-tenant admin features
- ❌ Data connectors (Google Drive, SFTP, APIs, webhooks)
- ❌ Admin UI (config via env vars)

Every "no" in the PRD is a feature Claude won't waste tokens building. When the agent reads "❌ Admin UI" it stops suggesting one.

The PRD also breaks the project into 8 modules, each small enough to plan and build in one cycle. That's deliberate — more on sizing below.

CLAUDE.md — the rules of engagement¶

CLAUDE.md loads into every session automatically. The template uses it for three things:

1. Hard technical rules. Not vibes — testable constraints:

- No LangChain, no LangGraph - raw SDK calls only
- All tables need Row-Level Security - users only see their own data
- Stream chat responses via SSE
- Python backend must use a `venv` virtual environment

2. Engineering principles that target real agent failure modes. This is the best section in the repo. Four principles, each one a known way AI coding goes wrong:

My favorite line: "Every changed line should trace directly to the user's request." That's a code review standard, written down where the agent reads it every session.

3. Planning conventions. Plans go in .agent/plans/, named {sequence}.{plan-name}.md, and — critically — every task in a plan must include at least one validation test. A plan step isn't "add auth"; it's "add auth → verify: login with test user returns a session token."

PROGRESS.md — state that survives the session¶

A plain checklist with a three-state convention:

- [ ] = Not started
- [-] = In progress
- [x] = Completed

Claude reads it to know where you are and updates it as it completes work. This file is what makes multi-day projects possible — without it, every new session starts with "so, where were we?"

The 3 Slash Commands¶

Slash commands live in .claude/commands/ as markdown files. Each one is a reusable prompt with a defined process.

/onboard — start every session here¶

Scans the repo (git ls-files), reads CLAUDE.md + PRD.md + PROGRESS.md, checks git status and the last 10 commits, then summarizes: what the project does, how it's organized, current module, recent activity. Thirty seconds and the agent has full context — no re-explaining.

/plan [feature] — think first, save the thinking¶

/plan module 2 document ingestion

The command forces a sequence: gather context → surface assumptions and tradeoffs (ask if multiple interpretations exist) → draft the plan → save it to .agent/plans/2.document-ingestion.md.

Each plan gets a complexity indicator at the top:

• ✅ Simple — single-pass executable, low risk
• ⚠️ Medium — may need iteration
• 🔴 Complex — break into sub-plans before executing

That last rule is the key insight: if the agent rates its own plan 🔴, it's not allowed to execute it. It has to decompose first. This is self-assessment as a circuit breaker against the most common agentic failure — biting off more than one context window can chew.

/build [plan-file] — execute with the receipt attached¶

/build .agent/plans/2.document-ingestion.md

The build command's process: read the entire plan → execute tasks in order → run the validation steps and fix issues before proceeding → update PROGRESS.md → report what was done, including any deviations from the plan and why.

Validation isn't an afterthought bolted on at the end — it was baked into the plan when /plan wrote it. Build just cashes the checks.

The Guardrails Nobody Talks About¶

Two more files make the loop safe to run with acceptEdits mode (auto-approve file edits):

.claude/settings.json pre-approves the boring stuff and blocks the dangerous stuff:

{
  "permissions": {
    "allow": ["Bash(npm install:*)", "Bash(git commit:*)", "Bash(uv:*)"],
    "deny":  ["Bash(sudo:*)", "Bash(rm -rf:*)", "Read(**/.env)", "Read(~/.ssh/**)"],
    "ask":   ["Bash(git push:*)"],
    "defaultMode": "acceptEdits"
  }
}

Three details worth stealing:

• Deny Read(**/.env) — the agent can never leak your API keys into context (or a commit)
• git push is "ask" — local commits flow freely, but nothing leaves your machine without a human click
• rm -rf and sudo denied outright — the two commands with no undo

.mcp.json wires in Playwright MCP, so "validate" can mean actually open the browser and click through the flow, not just "the code compiles." CLAUDE.md's development flow explicitly says: "Use browser testing where applicable via an appropriate MCP."

Key Findings: Why This Template Works¶

Beyond the mechanics, four design decisions make this template better than most starters I've seen.

1. Plans are artifacts, not chat messages¶

When a plan lives in .agent/plans/3.record-manager.md, you can review it before building, diff it after, and point a fresh session at it. Chat-based plans die with the session. File-based plans are restartable and reviewable — that's the difference between a prompt and a process.

2. Validation is defined at plan time, not build time¶

Asking "how will we verify this?" after building invites rationalization — the agent grades its own homework. This template requires the test to be written into the plan before any code exists. It's TDD thinking applied at the workflow level.

3. The module sizing is the real curriculum¶

The PRD splits an agentic RAG app into 8 modules, each one plan + one build session. That sizing teaches you the most transferable skill in agentic coding: scoping work to fit a context window. Too big and the agent loses the plot mid-build; too small and you're micromanaging. One module ≈ one clean loop is the sweet spot.

4. It even scripts the hard architectural decision¶

Between Modules 1 and 2, the PRD forces a genuine fork: keep OpenAI's managed Responses API or rip it out for provider-agnostic Chat Completions. It presents both options in a pros/cons table and then says the quiet part out loud:

"This is a lesson in steering Claude Code: you need to clearly communicate your decision and guide the AI to implement it correctly."

The human owns decisions; the agent owns implementation. The template doesn't just say that — it engineers a moment where you have to practice it.

One Extension I'd Add: A Validation Folder¶

The template embeds validation inside each plan. For bigger projects, I'd go one step further — mirror .agent/plans/ with .agent/validations/:

.agent/
├── plans/
│   └── 2.document-ingestion.md
└── validations/
    └── 2.document-ingestion.md   # checklist + actual test output, filled in by /build

Add one line to build.md: "After validation, write the results — commands run, output, pass/fail per task — to .agent/validations/{same-name}.md before updating PROGRESS.md."

Now you have an audit trail: the plan said what would prove it works, the validation file shows it did. When something breaks in Module 6, you can check whether Module 2's checks actually passed or were quietly skipped.

Adopt This in Your Own Project Today¶

You don't need the RAG app — the loop transfers to anything. Checklist:

• Write a PRD.md with explicit in-scope and out-of-scope lists
• Write a CLAUDE.md with hard rules + the four engineering principles
• Create .agent/plans/ and define the {sequence}.{name}.md convention
• Create PROGRESS.md with [ ] / [-] / [x] states
• Add /onboard, /plan, /build to .claude/commands/
• Lock down .claude/settings.json — deny .env reads, ask on git push
• Add an MCP for real validation (Playwright for web apps)
• Size your work into modules that fit one plan/build cycle

Or just clone it:

git clone https://github.com/pkhamdee/code-template.git my-project
cd my-project
claude
# then: /onboard

Summary¶

The loop: PRD.md defines the goal → /plan writes a plan with per-task validation tests into .agent/plans/ → /build executes the plan, runs the validations, and updates PROGRESS.md → /onboard restores full context next session.

The rules that make it work:

The pattern behind all of it: don't make the agent smarter — make the project legible. Goal in one file, rules in another, plans and progress in git. Any session, any day, the agent can read its way back to full context and keep going. That's the full loop.

Discussion

Have thoughts on this post? Share them below — questions, corrections, or your own experience are all welcome.