Olivia Keiter Methodology

Spec-driven build methodology for working with Claude

Last updated: May 2026

What this is

The methodology I use to build with Claude. It covers how I scope work, how I document it before code is written, how I run multi-context builds without losing the thread, and how I keep the working relationship with Claude consistent across sessions.

It is open source on purpose. Take what works, leave what doesn’t, adapt it to your own context. Girl bosses don’t gatekeep.

Audience. Anyone who wants to build real things with Claude and feels the gap between “here’s an idea” and “here’s a working version of it.” Solo operators, senior leaders prototyping, developers curious how someone non-engineering structures AI builds. The methodology isn’t locked to a skill level. The honest caveat is that no methodology is.

Scope. How I plan, document, and execute builds with Claude. The shape of the artifacts every build produces. The conventions that keep it consistent across projects.

Out of scope. Anything specific to my web design business, my client work, or any individual project. Those have their own operating docs.

Standing principles

Five principles. Every output, every session, every artifact operates under them.

Build things I give a damn about. The work reflects on me. Every output should feel like it came from someone who cared, not someone trying to close a ticket.
I work with AI. It does not work for me. Claude is a collaborator, not a replacement for thinking. Vague input produces vague output. Gaps in my thinking show up immediately.
Agents recommend, build, and automate as far as possible. Humans push go. Always. Nothing goes out, gets sent, gets posted, gets published, or communicates on my behalf without me reviewing it first.
I’m not a lawyer. When something feels legally adjacent, stop and verify before proceeding. Image licensing, fonts, copyright, anything touching someone else’s intellectual property.
No AI language, ever. If it wouldn’t come out of my mouth in a real conversation, rewrite it.

The hard formatting rule

No em dashes. Ever. Not in instructions, not in drafts, not in copy, not in internal docs. Use a comma, a period, or restructure the sentence. There is no exception.

This rule travels into every CLAUDE.md and every spec. Not implied. Named.

The copy standards travel list

Certain rules survive every context boundary. Project instructions live in the Claude project. Build sessions in VSCode chat see CLAUDE.md and the spec, not the project instructions. That means the rules that matter have to ride along.

The following travel with every build:

No em dashes, ever
No AI language
No contrast framing (“this isn’t X, it’s Y”)
No engagement bait or false suspense (“but here’s the thing”)
No therapy speak (“that sounds really hard,” “let’s unpack that”)
No “Best,” sign-offs. Use “Best wishes” or “Thank you” only.
No corporate or agency tone
Women first in all sign-offs, references, and copy
Fairness travels too. Default to representative examples, don’t assume the reader’s identity, and flag when output reproduces a bias pattern even when individual choices look defensible. Tech writing doesn’t default to a male reader. Business writing doesn’t default to a male founder. Parenting writing doesn’t default to a female parent.
Lead with voices that are typically diminished or silenced. Women, people of color, LGBTQ+ people, and other minority voices and perspectives don’t get treated as the secondary frame, the qualifying example, or the optional inclusion. They lead, they ground the example, they hold the perspective the writing is built around.
US English spelling and conventions
Never invent information. If a detail isn’t confirmed, flag it. Placeholder text with a clear description is acceptable. Making something up is not.
Don’t push to end the conversation. I think out loud and reach my point through the conversation. Stay in it until I end it.

Every CLAUDE.md includes this list verbatim. Every spec references it or reproduces it. An output that violates any of these isn’t done. Quality gate, not preference.

How Claude works with me

Two hard rules govern the working relationship.

Automate, don’t instruct manual clicks. I’m an AI automation leader. If Claude can do the thing, Claude does it. Writing the file, running the command, producing the output, making the edit. That’s the job. Handing me step-by-step manual instructions for something that could be automated is the wrong move. “Click here, drag this code, drop it there” is not a Claude answer.

Manual instructions are only appropriate when the task genuinely requires a human (signing contracts, in-person meetings, phone calls), when Claude doesn’t have system access, or when I specifically ask for manual steps.

Confirm before producing deliverables. Before generating anything that takes real work (markdown files, specs, kickoffs, decision logs, documents, build artifacts, anything beyond a conversational response), Claude confirms it understands the full scope. No jumping ahead because it sounds like the conversation is heading toward a deliverable. Confirm first. Produce second.

Conversational responses don’t need confirmation. Deliverables do. The last step before producing a deliverable is a check-in: here’s what I understand, here’s what I’m about to produce, good to go? Then wait for the green light.

How I think

Out loud. Collaboratively. I reach my point through the conversation, not before it. Reflect back the understood ask before diving in. Ask follow-up questions one at a time. Don’t skip this step unless I flag something as a quick question.

Match the energy. Serious when the work calls for it. Loose when the conversation is loose. Jokes are fine when they fit. I set the tone.

Don’t push to end the conversation. Don’t write “let me know if you have any other questions” or “happy to help further.” I’ll end it when I’m ready.

The three-document system

Every build produces exactly three documents before any code is written. Not two. Three. Non-negotiable.

The three documents answer three questions in sequence:

Why does this exist and why does it work this way? → decision log
What is being built? → spec
How do we build it? → kickoff

A build that skips the decision log loses its reasoning. A build that skips the spec loses its definition of done. A build that skips the kickoff loses its execution plan. All three travel together. All three are markdown. Never .docx.

The decision log

What it is. A plain-language record of how the spec was reached. Anyone should be able to read it and understand the thinking behind the build without needing to read the original conversation that produced it.

What it contains.

The problem being solved. What friction or gap prompted this build, in plain language, not product-speak.
Options considered. The approaches that were on the table and why each was accepted or rejected. Future builders need to know why the road not taken wasn’t taken.
Key decisions made. Each decision: what was decided, what the alternative was, why this choice.
Explicit constraints. What the build will not do in this version and why. The difference between “we ran out of time” and “we made a deliberate choice” matters.
Where this is headed. V2 and V3 signals. Things that came up during the spec conversation that belong in a future version. Captured here so they don’t get lost or pollute the current spec.
Open questions. Anything unresolved at the time the spec was written. If a decision was deferred, name it so it doesn’t get silently assumed later.

Format. Plain prose with section headers. No longer than it needs to be. Goal: a new builder gets the reasoning in under ten minutes.

When to write it. During the spec conversation, not after. As decisions are made, log them. The decision log is also a living document. Architectural pivots or scope shifts mid-build add entries.

The spec

What it is. The complete product definition. What is being built, why, what constraints apply, what done looks like.

What it contains.

Product purpose and positioning
Core principles that govern every feature decision
Full feature set for this version
Voice and tone notes
Technical foundation (stack, architecture, key patterns)
File structure
Definition of done
Copy standards section (reproduces or references the travel list)
What’s explicitly deferred to future versions

Rules.

Every feature has a definition of done.
No vague requirements. If a requirement can’t be checked off, rewrite it until it can.
Deferred features are listed explicitly. “Not in this version” is a decision, not an oversight.
The spec doesn’t contain build instructions. That’s the kickoff’s job.

The kickoff

What it is. The actionable build instructions. Everything Claude needs to execute the build without asking questions.

What it contains.

Full file structure with every file named
Dependencies with versions or “latest”
Component specifications with exact behavior
Data structures and contracts
Explicit stubs for files not built this phase, with a clear comment noting which phase builds them
Phase breakdown for multi-context builds, in a single markdown file with phases labeled
Definition of done (same checklist as the spec)

Rules.

The kickoff must be executable without referring back to the spec.
No vague instructions. Exact values, exact behavior descriptions, exact data formats.
Every file in the file structure gets created. Files not built this phase get stub comments.
The kickoff doesn’t explain why decisions were made. That’s the decision log’s job.

Naming conventions

Decision log: {project-name}-decision-log.md
Spec: {project-name}-spec.md
Kickoff: {project-name}-kickoff.md (single file, contains all phases for multi-context builds)
Handoff notes: phase-{N}-handoff.md
Build notes: BUILDNOTES.md (always uppercase, project root)
CLAUDE.md: always CLAUDE.md (always uppercase, project root)
Project name format: business or project name, hyphen-separated, all lowercase. Matches the GitHub repo and the local folder exactly.

All files are markdown. Never .docx.

CLAUDE.md and how the layers nest

Three layers govern any build session.

Project instructions live in the Claude project. They carry the high-level posture and standing principles that govern every conversation in that project.

CLAUDE.md lives in the build repo root. It carries the same standing principles, copy standards, and operational conventions into the build session, where the project instructions don’t reach. Build sessions in VSCode chat see CLAUDE.md and the spec, not the project instructions. The rules have to ride along.

The spec and kickoff are project-specific. They carry the build’s purpose, scope, and execution plan.

If you adapt this methodology, CLAUDE.md is the document you rewrite first. Everything else flows from it.

Multi-context build pattern

Multi-phase kickoffs are the default for any build that would produce a kickoff longer than a single focused context window. The reason: hitting the context limit mid-build produces incomplete output that’s hard to recover from. Better to phase up front than patch later.

Single file, labeled phases

The kickoff is a single markdown file. Phases are clearly labeled inside it. Not separate files. This is non-negotiable.

Structure:

# {project-name} kickoff

## Overview
[Build context, link to spec, total phase count]

## Phase 1: {phase name}
[Phase 1 content]

### Phase 1 handoff format
[The handoff note phase 1 will produce]

## Phase 2: {phase name}
[Phase 2 content, opens with "Read phase-1-handoff.md before writing any code"]

### Phase 2 handoff format
[etc]

Phase count is determined by scope, not a fixed number. Five phases is a pattern, not a rule.

Phase prompt format

Each phase section contains:

Context summary. What the overall build is and what came before. Two to three sentences.
What you’re building this phase. Explicit scope. Everything in the list gets built. Nothing outside it does.
Relevant specs. Only what this phase needs. Not the full kickoff.
Phase done when. Specific, checkable criteria.
End-of-phase instruction. The handoff note format and filename.

File attach discipline

Each phase specifies which files to attach at the start of the chat session. Attach only those.

Phase 1: the kickoff document and CLAUDE.md.
Phases 2 through N: the kickoff document, the previous phase’s handoff note, and the specific source files this phase will read or modify.

Lean is the goal. Attaching the full project history to every phase is a context budget problem.

The handoff note

Every phase ends with a handoff note. No exceptions. Without it, the next session starts blind.

Format:

# Phase {N} handoff

## What is working
List each working feature. Be specific. "Section reordering works" isn't specific. "Move up and move down write back to source and the site reloads with the change" is.

## What is stubbed or deferred
Each stub with a note on which phase builds it.

## Decisions made that differ from this prompt
Each deviation with the reason. If the prompt said BrowserView and you used webview, say so and explain why. Future phases need to know.

## Files created or modified this phase
Complete file list. No exceptions.

## Known issues
Anything broken or incomplete that the next phase needs to know. Don't carry issues silently. Name them.

Rules:

Written by Claude at the end of the phase, not by me.
Saved as phase-{N}-handoff.md in the project root.
The next phase prompt opens with “Read phase-{N}-handoff.md before writing any code.”
I read the handoff before firing the next phase. If something looks wrong, fix it before proceeding.

The iteration loop

Between phases:

Phase N completes. Claude writes the handoff.
I read the handoff.
I identify: known issues that must be fixed in phase N+1, decisions that differ from the spec needing acknowledgement, anything missing from phase N+1 given what was learned.
I add those items explicitly to the phase N+1 prompt before running it.
Phase N+1 runs with the updated prompt and the handoff note attached.

What to add between phases:

Known issues that will break phase N+1 if not fixed
Architectural decisions from phase N that phase N+1 needs to build on correctly
Scope adjustments where phase N revealed a dependency

What not to add:

New features outside the original spec
Nice-to-haves that came to mind reading the handoff
Full rewrites of the phase prompt

One to three items between phases is typical. Five or more suggests the spec needs revision, not the phase prompt.

Context window management

Phase prompts are self-contained and lean. A phase section approaching 800 lines is a signal to split.

Attach only what the phase needs. Stubs preserve file structure without consuming context. Handoff notes replace accumulated history.

Token budget for a session with a 100k context window:

Phase prompt: 5k to 10k tokens
Attached files: 20k to 40k tokens
Handoff note: 2k tokens
Room for output: 50k+ tokens

Stay well within these limits. Cramming files in to avoid a round trip costs more than it saves.

When a phase is too large

Signs:

Phase section approaching 1000 lines
File attach list more than 10 files
Phase done criteria more than 15 items

Split it. Two clean phases beat one phase that runs out of context.

BUILDNOTES.md

Final artifact of every build. Documents:

What’s working
What’s deferred
Known issues
Suggested next priorities

Written by the build session at the end of the final phase. For single-phase builds, BUILDNOTES.md is the handoff note.

Trivial builds

Some changes are too small to need the full three-document system. A typo fix, a single content swap, a style tweak. These don’t need a decision log or a kickoff. Edit, push, confirm.

The trivial threshold: a single, isolated change that doesn’t touch architecture, doesn’t add a feature, and can be reviewed in one glance. If you’re unsure whether something is trivial, it isn’t. Spec it.

When things go wrong

The build is fighting you

If multiple phases are producing incomplete output or requiring significant corrections, stop. Don’t continue patching. Read the decision log and the spec. The problem is usually one of:

An architectural decision in the spec that doesn’t match reality
A phase that’s too large and needs to be split
A dependency between features that wasn’t accounted for in the phase order

Fix the root cause before continuing. Patching a bad architecture phase by phase produces a bad product.

The architecture needs to change

If a fundamental architectural decision turns out wrong mid-build, stop and assess. Write a new decision log entry documenting what was wrong and what the correct approach is. Update the spec. Rewrite the affected phase sections in the kickoff. Start the affected phases fresh.

Don’t patch a wrong architecture. The cost of rewriting phase prompts is far lower than the cost of maintaining broken code.

A phase runs out of context mid-build

Stop. Don’t continue in the same session.
Ask Claude to write a partial handoff note documenting exactly where it stopped and what’s incomplete.
Add a phase N.5 section to the kickoff that picks up from the partial handoff.
Attach only the files modified in the current phase plus the partial handoff.
Continue from there.

Conflicts between CLAUDE.md, the spec, and a phase prompt

Order of precedence:

The spec wins on what. If the phase prompt contradicts the spec on what’s being built, the spec is right.
CLAUDE.md wins on how. Copy standards, voice rules, operational conventions. If a phase prompt accidentally contradicts CLAUDE.md, CLAUDE.md is right.
The phase prompt wins on this phase’s scope. If the spec includes a feature that’s explicitly deferred to a later phase in the kickoff, the kickoff is right for this phase.

When in doubt, ask. Don’t guess at precedence on a load-bearing call.

Quick reference

Key terms

Decision log. First of the three documents. Plain-language record of why the spec is shaped the way it is. Living document, updated when architectural pivots happen mid-build.
Spec. Second of the three documents. What is being built, what done looks like.
Kickoff. Third of the three documents. How the build executes. For multi-phase builds, contains all phases in a single markdown file.
Phase prompt. A labeled section inside the kickoff covering one phase of a multi-context build.
Handoff note. Written at the end of every phase. Captures what’s working, what’s stubbed, decisions that differ, files modified, known issues.
BUILDNOTES.md. Final artifact of every build.
CLAUDE.md. Lives in the repo root. Carries the standing principles, copy standards, and operational conventions into every build session.

File checklist (every build)

Repo root contains:

CLAUDE.md
{project-name}-decision-log.md
{project-name}-spec.md
{project-name}-kickoff.md
phase-1-handoff.md, phase-2-handoff.md, etc., for multi-phase builds
BUILDNOTES.md

All markdown. Never .docx.

Standing principles (one-liner version)

Build things I give a damn about.
I work with AI. It does not work for me.
Agents recommend, build, and automate. Humans push go.
I’m not a lawyer. Legal-adjacent gets flagged.
No AI language, ever.

Copy standards travel list

No em dashes, ever
No AI language
No contrast framing
No engagement bait or false suspense
No therapy speak
No “Best,” sign-offs (use “Best wishes” or “Thank you”)
No corporate or agency tone
Women first
Fairness travels too (representative examples, don’t assume reader identity, flag bias patterns)
Lead with voices typically diminished or silenced
US English spelling and conventions
Voice matches the project, not a generic template
Never invent information
Don’t push to end the conversation

End of methodology.