Spec-Driven Development with Claude: Building a Starter CLAUDE.md

Most developers using AI coding assistants start every session the same way: explain the project, re-state the constraints, hope the model remembers what matters. It works for small tasks. It falls apart at scale.

There is a better approach. Instead of treating the AI as a conversational partner you brief each time, treat it as an engineer who reads a spec before writing a line of code.

That is the idea behind a spec-driven CLAUDE.md — a protocol file that lives in your repository and governs how Claude operates on your project.

The Problem with Ad-Hoc Prompting

When you work with an AI assistant without structure, certain failure modes repeat themselves:

Context amnesia. Every new session starts from zero. Architectural decisions made yesterday are forgotten today.
Premature implementation. The model jumps to code before understanding the problem. You get a working solution to the wrong question.
Silent assumption-making. Missing requirements get filled in with plausible defaults rather than clarifying questions.
Drift. Over multiple sessions, the project slowly deviates from its original design because there is no source of truth the model checks against.

These are not AI problems. They are process problems. The same failures happen on human teams without specs, design docs, or architectural decision records. The fix is the same too: write it down, make it authoritative, and enforce it.

What a CLAUDE.md Protocol Looks Like

A CLAUDE.md file sits at the root of your repository. Claude reads it automatically at the start of every session. Think of it as a combination of a project charter, coding standards document, and operating manual — compressed into a single file the AI follows as law.

Here is the structure we use at ArcticLayer:

Core Principles

The file opens with non-negotiable rules:

1. Design before implementation.
2. Ask high-leverage clarification questions.
3. Never assume missing requirements.
4. Prefer simple, scalable architecture.
5. Optimize for performance and security.
6. Favor static systems over runtime complexity when possible.
7. Maintain architectural memory.

These are not suggestions. They are constraints. The protocol explicitly blocks Claude from jumping into code, overriding prior decisions silently, or generating large implementations without approval.

Mandatory Development Phases

This is where the real discipline lives. Every piece of work must pass through four phases in order:

Phase 1 — Context Audit. Claude analyzes the repository structure, identifies the stack, hosting, build system, deployment strategy, and constraints. It produces observations, risks, gaps, and clarifying questions. No code. Waits for approval.

Phase 2 — System Design. Architecture, data flow, trust boundaries, failure model, trade-offs. Still no code. Waits for approval.

Phase 3 — Implementation Plan. File structure changes, environment variables, CI/CD changes, edge cases. Still no code. Waits for approval.

Phase 4 — Implementation. Only after three rounds of approval does Claude write production code.

This phased approach eliminates the most expensive category of AI-generated waste: well-written code that solves the wrong problem.

Architectural Memory

Projects evolve. Requirements shift. Decisions get made and their reasoning fades. The protocol addresses this with a structured memory system — a set of markdown files that Claude reads and updates as the project changes:

project.md — Purpose, success criteria, constraints, non-goals
requirements.md — Functional and non-functional requirements, acceptance criteria
architecture.md — System overview, components, data flow, trust boundaries, failure model
decisions.md — An architectural decision log with context, alternatives, and consequences
changelog.md — What changed, what broke, how to migrate

When any of these aspects change, Claude updates the relevant files, appends to the decision log, and explicitly states that memory has been updated. No decision gets lost between sessions.

Enforcement

What makes this different from a guidelines document that gets ignored? The protocol includes an enforcement clause:

If user asks for implementation without approved design:

Respond:
"Per CLAUDE.md protocol, system design approval required
before implementation."

Claude will refuse to write code until the design phases are complete. This is not a limitation — it is the entire point. The protocol prevents the most common failure mode in AI-assisted development: moving fast in the wrong direction.

A Real Example: Project Initialization

Here is how this plays out in practice. Say you are starting a new project — an Astro website that automatically displays projects from your GitHub organization. You drop a first_question.md into the repo with the project idea and constraints:

Project idea:
I want my Astro website to automatically display projects
from my GitHub organization repositories. It should work
whether repositories are private or public. The system must
be secure and performance-first. I do not want runtime API calls.

Constraints:
- Hosting: Cloudflare Pages
- Performance expectation: Fully static output
- Security: No tokens exposed
- Longevity: Long-term internal infrastructure

Instead of immediately scaffolding components, Claude enters Project Initialization Mode. It asks high-impact discovery questions: Does the system need to scale beyond the current scope? Is vendor neutrality required? Should it work if repositories become private? Is cost optimization more important than performance?

Only after answers are collected does Claude generate draft project.md and requirements.md files. You review, approve, and then the architecture and decision logs follow. By the time code is written, everyone — human and AI — agrees on what is being built and why.

Programming Principles as Defaults

The protocol also embeds sensible programming defaults that apply across projects:

Use the latest stable language version
Follow DRY principles
Do not over-engineer
Only add high-value comments
Prefer native packages over third-party dependencies

For Python projects specifically, it defines logging standards, config management patterns, dependency tooling (uv, pyproject.toml), testing conventions (pytest with parametrize), and project structure (src/ for source, tests/ alongside). For Docker, it mandates compose files, local volume mounts, official images, and multi-stage builds.

These are not arbitrary opinions. They are the accumulated cost of learning the same lessons repeatedly across projects. Encoding them in CLAUDE.md means you learn them once and never pay for the same mistake again.

Why This Matters

The spec-driven approach changes the economics of AI-assisted development in three ways:

Reduced rework. The phased approval process catches misunderstandings before they become hundreds of lines of code that need to be thrown away.

Persistent context. The memory system means session two picks up exactly where session one left off. No re-explaining. No context loss.

Scalable collaboration. The protocol works the same whether you are a solo developer or a team. Anyone can read the decision log and understand not just what was built, but why.

Getting Started

You can adopt this approach incrementally:

Start with core principles. Drop a CLAUDE.md in your repo with five to seven rules that matter most for your project.
Add phases. Introduce the four-phase workflow for any feature that touches more than a few files.
Build memory. Create the /claude/ directory and start populating project.md. The rest will grow organically as decisions get made.
Enforce it. Add the enforcement clause. Let Claude push back when you try to skip the process. That friction is a feature.

The goal is not to slow down development. It is to stop building the wrong thing fast.

The full starter template is available on GitHub: arcticlayer/claude_prompt. Fork it, adapt it to your stack, and start building with discipline.

Want to see this protocol in action or build something similar for your team? Get in touch.