161 lines
3.6 KiB
Markdown
161 lines
3.6 KiB
Markdown
---
|
|
sidebar_label: Create Tech Spec
|
|
description: How to create a technical specification using Quick Spec Flow
|
|
---
|
|
|
|
# How to Create a Tech Spec
|
|
|
|
Use the `tech-spec` workflow for Quick Flow projects to go directly from idea to implementation-ready specification.
|
|
|
|
---
|
|
|
|
## When to Use This
|
|
|
|
- Bug fixes and small enhancements
|
|
- Small features with clear scope (1-15 stories)
|
|
- Rapid prototyping
|
|
- Adding to existing brownfield codebase
|
|
- Quick Flow track projects
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- BMad Method installed
|
|
- PM agent or Quick Flow Solo Dev agent available
|
|
- Project directory (can be empty for greenfield)
|
|
|
|
---
|
|
|
|
## Steps
|
|
|
|
### 1. Load the PM Agent
|
|
|
|
Start a fresh chat and load the PM agent (or Quick Flow Solo Dev agent).
|
|
|
|
### 2. Run the Tech Spec Workflow
|
|
|
|
```
|
|
*create-tech-spec
|
|
```
|
|
|
|
Or simply describe what you want to build:
|
|
|
|
```
|
|
I want to fix the login validation bug
|
|
```
|
|
|
|
### 3. Answer Discovery Questions
|
|
|
|
The workflow will ask:
|
|
- What problem are you solving?
|
|
- What's the scope of the change?
|
|
- Any specific constraints?
|
|
|
|
### 4. Review Detected Context
|
|
|
|
For brownfield projects, the agent will:
|
|
- Detect your project stack
|
|
- Analyze existing code patterns
|
|
- Detect test frameworks
|
|
- Ask: "Should I follow these existing conventions?"
|
|
|
|
### 5. Get Your Tech Spec
|
|
|
|
The agent generates a comprehensive tech-spec with ready-to-implement stories.
|
|
|
|
---
|
|
|
|
## What You Get
|
|
|
|
### tech-spec.md
|
|
|
|
- Problem statement and solution
|
|
- Detected framework versions and dependencies
|
|
- Brownfield code patterns (if applicable)
|
|
- Existing test patterns to follow
|
|
- Specific file paths to modify
|
|
- Complete implementation guidance
|
|
|
|
### Story Files
|
|
|
|
For single changes:
|
|
- `story-[slug].md` - Single user story ready for development
|
|
|
|
For small features:
|
|
- `epics.md` - Epic organization
|
|
- `story-[epic-slug]-1.md`, `story-[epic-slug]-2.md`, etc.
|
|
|
|
---
|
|
|
|
## Example: Bug Fix (Single Change)
|
|
|
|
**You:** "I want to fix the login validation bug that allows empty passwords"
|
|
|
|
**Agent:**
|
|
1. Asks clarifying questions about the issue
|
|
2. Detects your Node.js stack (Express 4.18.2, Jest for testing)
|
|
3. Analyzes existing UserService code patterns
|
|
4. Asks: "Should I follow your existing conventions?" → Yes
|
|
5. Generates tech-spec.md with specific file paths
|
|
6. Creates story-login-fix.md
|
|
|
|
**Total time:** 15-30 minutes (mostly implementation)
|
|
|
|
---
|
|
|
|
## Example: Small Feature (Multi-Story)
|
|
|
|
**You:** "I want to add OAuth social login (Google, GitHub)"
|
|
|
|
**Agent:**
|
|
1. Asks about feature scope
|
|
2. Detects your stack (Next.js 13.4, NextAuth.js already installed!)
|
|
3. Analyzes existing auth patterns
|
|
4. Confirms conventions
|
|
5. Generates:
|
|
- tech-spec.md (comprehensive implementation guide)
|
|
- epics.md (OAuth Integration epic)
|
|
- story-oauth-1.md (Backend OAuth setup)
|
|
- story-oauth-2.md (Frontend login buttons)
|
|
|
|
**Total time:** 1-3 hours (mostly implementation)
|
|
|
|
---
|
|
|
|
## Implementing After Tech Spec
|
|
|
|
```bash
|
|
# Single change:
|
|
# Load DEV agent and run dev-story
|
|
|
|
# Multi-story feature:
|
|
# Optional: Load SM agent and run sprint-planning
|
|
# Then: Load DEV agent and run dev-story for each story
|
|
```
|
|
|
|
---
|
|
|
|
## Tips
|
|
|
|
### Be Specific in Discovery
|
|
|
|
- ✅ "Fix email validation in UserService to allow plus-addressing"
|
|
- ❌ "Fix validation bug"
|
|
|
|
### Trust Convention Detection
|
|
|
|
If it detects your patterns correctly, say yes! It's faster than establishing new conventions.
|
|
|
|
### Keep Single Changes Atomic
|
|
|
|
If your "single change" needs 3+ files, it might be a multi-story feature. Let the workflow guide you.
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- [Quick Flow](../../explanation/features/quick-flow.md) - Understanding Quick Spec Flow
|
|
- [Implement Story](./implement-story.md) - After tech spec
|
|
- [Create PRD](./create-prd.md) - For larger projects needing full BMad Method
|