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
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
Prohibited behaviors:
- No skipping tests
- No scope creep
- No untyped code
- No secrets in code
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.
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, weak rules ("try to test" → "tests are mandatory"), oversized sprints (more than 12 tasks for 2 weeks), and task specs that are too vague to execute without questions.
How AI Uses These
Every new task session:
- AI reads
.clinerules→ "These are my rules. Tests are mandatory. Plan first." - AI reads
ARCHITECTURE.md→ "Here's the schema, here are the patterns, here's how auth works." - AI reads
README.md→ "We're building X, currently in MVP phase." - AI reads the sprint plan → "Task 3 is next, depends on Task 2 being done."
- AI reads the task spec → "Here's exactly what to build, which files to touch, acceptance criteria."
- AI checks
LEARNINGS.md→ "Oh, there's a gotcha about this library."
This is why documentation-first works. You're building AI's memory.
The Right Amount of Documentation
Too little: 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.