barateza Tech Lead's Club - Spec-Driven Development
Plan and implement projects with precision. Granular tasks. Clear dependencies. Right tools.
┌──────────┐ ┌──────────┐ ┌─────────┐ ┌───────────────────┐
│ SPECIFY │ → │ DESIGN │ → │ TASKS │ → │ IMPLEMENT+VALIDATE│
└──────────┘ └──────────┘ └─────────┘ └───────────────────┘
Project Structure
.specs/
├── project/
│ ├── PROJECT.md # Vision & goals
│ ├── ROADMAP.md # Features & milestones
│ └── STATE.md # Memory between sessions
├── codebase/ # Brownfield analysis (existing projects)
│ ├── STACK.md
│ ├── ARCHITECTURE.md
│ ├── CONVENTIONS.md
│ ├── STRUCTURE.md
│ ├── TESTING.md
│ └── INTEGRATIONS.md
└── features/ # Feature specifications
└── [feature]/
├── spec.md
├── design.md
└── tasks.md
Workflow
New project:
- Initialize project → PROJECT.md
- Create roadmap → ROADMAP.md
- Specify features → existing workflow
Existing codebase:
- Map codebase → 6 brownfield docs
- Initialize project → PROJECT.md + ROADMAP.md
- Specify features → existing workflow
Context Loading Strategy
Base load (~15k tokens):
- PROJECT.md (if exists)
- ROADMAP.md (when planning/working on features)
- STATE.md (persistent memory)
On-demand load:
- Codebase docs (when working in existing project)
- spec.md (when working on specific feature)
- design.md (when implementing from design)
- tasks.md (when executing tasks)
Never load simultaneously:
- Multiple feature specs
- Multiple architecture docs
- Archived documents
Target: <40k tokens total context **Reserve:** 160k+ tokens for work, reasoning, outputs **Monitoring:** Display status when >40k (see context-limits.md)
Commands
Project-level:
| Trigger Pattern | Reference |
|---|---|
| Initialize project, setup project | project-init.md |
| Create roadmap, plan features | roadmap.md |
| Map codebase, analyze existing code | brownfield-mapping.md |
| Record decision, log blocker | state-management.md |
| Pause work, end session | session-handoff.md |
| Resume work, continue | session-handoff.md |
Feature-level:
| Trigger Pattern | Reference |
|---|---|
| Specify feature, define requirements | specify.md |
| Design feature, architecture | design.md |
| Break into tasks, create tasks | tasks.md |
| Implement task, build | implement.md |
| Validate, verify, test | validate.md |
Tools:
| Trigger Pattern | Reference |
|---|---|
| Code analysis, search patterns | code-analysis.md |
Output Behavior
Model guidance: After completing lightweight tasks (validation, state updates, session handoff), naturally mention once that such tasks work well with faster/cheaper models. Track in STATE.md under Preferences to avoid repeating. For heavy tasks (brownfield mapping, complex design), briefly note the reasoning requirements before starting.
Be conversational, not robotic. Don't interrupt workflow—add as a natural closing note. Skip if user seems experienced or has already acknowledged the tip.
Code Analysis
Use available tools with graceful degradation. See code-analysis.md.