vibe-coding-docs

Documentation Architecture

TLDR

Before writing code, generate a set of foundation documents. These are AI’s memory — without them, every session starts from zero and every conversation drifts.

The documents should be generated by Claude (in the same brainstorming conversation) and reviewed by you. Takes 1-2 hours including review. Pays back immediately.

The Foundation Documents

Document Purpose Update Frequency
README.md What we’re building, current phase, tech stack Per phase
ARCHITECTURE.md System design, DB schema, components, API design When structure changes
.clinerules / CLAUDE.md Quality rules, testing standards, prohibited behaviors Rarely (but enforce strictly)
LEARNINGS.md Running log of solutions and gotchas During every task
SPRINT_RULES.md How to size sprints, write tasks, handle discovered work Once (at project start)
TASK_TEMPLATE.md Format for individual task specifications Never
Sprint Plan Task index, execution order, dependencies Per sprint
Task Specs Detailed spec per task (one file each) Never (each is used once)

AI reads the first four before every task. They provide the context that chat history can’t.

Why ARCHITECTURE.md Is Critical

The old version of this methodology had five lightweight docs. Experience showed that’s not enough — you need a proper architecture document with actual schemas, not just descriptions.

## Database Schema

### users
| Column | Type | Constraints |
|--------|------|-------------|
| id | UUID | PK |
| email | VARCHAR(255) | UNIQUE, NOT NULL |
| password_hash | VARCHAR(255) | NOT NULL |
| role | ENUM('user','admin') | DEFAULT 'user' |
| created_at | TIMESTAMP | DEFAULT NOW() |

When AI reads this, it writes correct queries and migrations the first time. Without it, AI guesses at column names and types, and you spend hours debugging schema mismatches.

What ARCHITECTURE.md should contain:

See the VH Conference Toolkit for a real example of what this looks like in practice.

Why .clinerules / CLAUDE.md Is Iron-Clad

This is your quality contract. It must include:

Mandatory reading list — files AI must read before every task

Quality standards that are non-negotiable:

Development workflow rules:

Architecture rules:

Prohibited behaviors:

When to ask the human — security decisions, architectural changes, ambiguous requirements, anything destructive

The difference between a mediocre AI-built project and a good one is almost entirely in this file.

Sprint Plans and Task Specs

This is what separates “tell AI to build something” from “give AI a clear spec and let it execute.”

Sprint plan: Index of tasks, execution order, dependencies, definition of done.

Task specs: Individual documents (one per task) with:

When Cline or Claude Code reads a task spec + ARCHITECTURE.md + .clinerules, it has everything it needs. No clarifying questions. Just execution.

Example from a real project (VH Conference Toolkit):

dev-docs/sprints/sprint-01-initial-setup/
├── SPRINT-EH-001-PLAN.md          # Sprint plan with 12 tasks
├── BACKLOG-TASK-EH.1.md           # Project bootstrap
├── BACKLOG-TASK-EH.2.md           # Public layout
├── BACKLOG-TASK-EH.3.md           # Auth system
├── ...
└── BACKLOG-TASK-EH.12.md          # Polish & smoke tests

Creating These Quickly

After brainstorming (in the same Claude conversation):

Based on everything we've discussed, generate the foundational
documents for this project:

1. README.md
2. ARCHITECTURE.md (with full database schemas)
3. LEARNINGS.md (empty template)
4. .clinerules (iron-clad quality rules)
5. SPRINT_RULES.md
6. TASK_TEMPLATE.md
7. Sprint 1 plan with task index
8. Individual task specs for each Sprint 1 task

Also generate any foundational code files that should exist
from the start (configs, schema files, .env.example, etc.)

Review everything Claude generates. Push back on:

How AI Uses These

Every new task session:

  1. AI reads .clinerules / CLAUDE.md → “These are my rules. Tests are mandatory. Plan first.”
  2. AI reads ARCHITECTURE.md → “Here’s the schema, here are the patterns, here’s how auth works.”
  3. AI reads README.md → “We’re building X, currently in MVP phase.”
  4. AI reads the sprint plan → “Task 3 is next, depends on Task 2 being done.”
  5. AI reads the task spec → “Here’s exactly what to build, which files to touch, acceptance criteria.”
  6. AI checks LEARNINGS.md → “Oh, there’s a gotcha about this library.”

This is why documentation-first works. You’re building AI’s memory.

Don’t Overdo It, But Don’t Under-Do It Either

Too little (old mistake):

Too much:

Just right:

Next: The Cline Workflow — How to actually execute tasks.