Skip to content

documentation-architecture.md

Latest commit

 

History

History
197 lines (145 loc) · 6.65 KB

documentation-architecture.md

File metadata and controls

197 lines (145 loc) · 6.65 KB
title Documentation Architecture
description The documents that make AI-assisted development work

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:

  • System overview with a simple diagram
  • Database schema (every table, every column, types, constraints)
  • Entity relationships
  • Route/page architecture
  • Component hierarchy
  • Auth flow
  • API design conventions and key endpoints
  • Deployment architecture
  • Key technical decisions with rationale

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:

  • Unit tests for every piece of business logic
  • Smoke test after every change
  • Browser testing for UI work
  • Error handling (no silent failures)
  • Heavy commenting on business logic
  • Docstrings on every function

Development workflow rules:

  • Plan mode before act mode, always
  • One task at a time (no side quests)
  • Commit working code only
  • Update docs after every task

Architecture rules:

  • Follow existing patterns
  • No new dependencies without approval
  • Use import aliases
  • Database changes need migrations

Prohibited behaviors:

  • No skipping tests
  • No scope creep
  • No untyped code
  • No secrets in code

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:

  • Context (why this task exists)
  • Requirements (numbered, testable)
  • Technical approach (specific files, patterns to follow)
  • Acceptance criteria (checkboxes)

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:

  • Vague schemas ("flexible data structure" → give me column names)
  • Weak rules ("try to test" → "tests are mandatory")
  • Oversized sprints (>12 tasks for 2 weeks)
  • Task specs that are too vague to execute without questions

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):

  • 5 documents at 30 lines each
  • No real schemas
  • Vague rules
  • No task specs

Too much:

  • 20 documents nobody reads
  • 200-line templates
  • Detailed specs for features you haven't committed to

Just right:

  • Foundation docs with real detail (schemas, rules, patterns)
  • Sprint plans with clear task specs
  • Updated as the project evolves
  • Everything a developer (human or AI) needs to start working, nothing more

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