mirror of
https://github.com/basicmachines-co/basic-memory
synced 2026-06-21 13:47:35 +00:00
Paul Hernandez
a1d7792bdb
Signed-off-by: phernandez <paul@basicmachines.co> Signed-off-by: Paul Hernandez <60959+phernandez@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Drew Cain <groksrc@users.noreply.github.com>
157 lines
6.2 KiB
Markdown
157 lines
6.2 KiB
Markdown
---
|
|
title: 'SPEC-1: Specification-Driven Development Process'
|
|
type: spec
|
|
permalink: specs/spec-1-specification-driven-development-process
|
|
tags:
|
|
- process
|
|
- specification
|
|
- development
|
|
- meta
|
|
---
|
|
|
|
# SPEC-1: Specification-Driven Development Process
|
|
|
|
## Why
|
|
We're implementing specification-driven development to solve the complexity and circular refactoring issues in our web development process.
|
|
Instead of getting lost in framework details and type gymnastics, we start with clear specifications that drive implementation.
|
|
|
|
The default approach of adhoc development with AI agents tends to result in:
|
|
- Circular refactoring cycles
|
|
- Fighting framework complexity
|
|
- Lost context between sessions
|
|
- Unclear requirements and scope
|
|
|
|
## What
|
|
This spec defines our process for using basic-memory as the specification engine to build basic-memory-cloud.
|
|
We're creating a recursive development pattern where basic-memory manages the specs that drive the development of basic-memory-cloud.
|
|
|
|
**Affected Areas:**
|
|
- All future component development
|
|
- Architecture decisions
|
|
- Agent collaboration workflows
|
|
- Knowledge management and context preservation
|
|
|
|
## How (High Level)
|
|
|
|
### Specification Structure
|
|
|
|
Name: Spec names should be numbered sequentially, followed by a description eg. `SPEC-X - Simple Description.md`.
|
|
See: [[Spec-2: Slash Commands Reference]]
|
|
|
|
Every spec is a complete thought containing:
|
|
- **Why**: The reasoning and problem being solved
|
|
- **What**: What is affected or changed
|
|
- **How**: High-level approach to implementation
|
|
- **How to Evaluate**: Testing/validation procedure
|
|
- Additional context as needed
|
|
|
|
### Living Specification Format
|
|
|
|
Specifications are **living documents** that evolve throughout implementation:
|
|
|
|
**Progress Tracking:**
|
|
- **Completed items**: Use ✅ checkmark emoji for implemented features
|
|
- **Pending items**: Use `- [ ]` GitHub-style checkboxes for remaining tasks
|
|
- **In-progress items**: Use `- [x]` when work is actively underway
|
|
|
|
**Status Philosophy:**
|
|
- **Avoid static status headers** like "COMPLETE" or "IN PROGRESS" that become stale
|
|
- **Use checklists within content** to show granular implementation progress
|
|
- **Keep specs informative** while providing clear progress visibility
|
|
- **Update continuously** as understanding and implementation evolve
|
|
|
|
**Example Format:**
|
|
```markdown
|
|
### ComponentName
|
|
- ✅ Basic functionality implemented
|
|
- ✅ Props and events defined
|
|
- - [ ] Add sorting controls
|
|
- - [ ] Improve accessibility
|
|
- - [x] Currently implementing responsive design
|
|
```
|
|
|
|
This creates **git-friendly progress tracking** where `[ ]` easily becomes `[x]` or ✅ when completed, and specs remain valuable throughout the development lifecycle.
|
|
|
|
|
|
## Claude Code
|
|
|
|
We will leverage Claude Code capabilities to make the process semi-automated.
|
|
|
|
- Slash commands: define repeatable steps in the process (create spec, implement, review, etc)
|
|
- Agents: define roles to carry out instructions (front end developer, baskend developer, etc)
|
|
- MCP tools: enable agents to implement specs via actions (write code, test, etc)
|
|
|
|
### Workflow
|
|
1. **Create**: Write spec as complete thought in `/specs` folder
|
|
2. **Discuss**: Iterate and refine through agent collaboration
|
|
3. **Implement**: Hand spec to appropriate specialist agent
|
|
4. **Validate**: Review implementation against spec criteria
|
|
5. **Document**: Update spec with learnings and decisions
|
|
|
|
### Slash Commands
|
|
|
|
Claude slash commands are used to manage the flow.
|
|
These are simple instructions to help make the process uniform.
|
|
They can be updated and refined as needed.
|
|
|
|
- `/spec create [name]` - Create new specification
|
|
- `/spec status` - Show current spec states
|
|
- `/spec implement [name]` - Hand to appropriate agent
|
|
- `/spec review [name]` - Validate implementation
|
|
|
|
### Agent Orchestration
|
|
|
|
Agents are defined with clear roles, for instance:
|
|
|
|
- **system-architect**: Creates high-level specs, ADRs, architectural decisions
|
|
- **vue-developer**: Component specs, UI patterns, frontend architecture
|
|
- **python-developer**: Implementation specs, technical details, backend logic
|
|
-
|
|
- Each agent reads/updates specs through basic-memory tools.
|
|
|
|
## How to Evaluate
|
|
|
|
### Success Criteria
|
|
- Specs provide clear, actionable guidance for implementation
|
|
- Reduced circular refactoring and scope creep
|
|
- Persistent context across development sessions
|
|
- Clean separation between "what/why" and implementation details
|
|
- Specs record a history of what happened and why for historical context
|
|
|
|
### Testing Procedure
|
|
1. Create a spec for an existing problematic component
|
|
2. Have an agent implement following only the spec
|
|
3. Compare result quality and development speed vs. ad-hoc approach
|
|
4. Measure context preservation across sessions
|
|
5. Evaluate spec clarity and completeness
|
|
|
|
### Metrics
|
|
- Time from spec to working implementation
|
|
- Number of refactoring cycles required
|
|
- Agent understanding of requirements
|
|
- Spec reusability for similar components
|
|
|
|
## Notes
|
|
- Start simple: specs are just complete thoughts, not heavy processes
|
|
- Use basic-memory's knowledge graph to link specs, decisions, components
|
|
- Let the process evolve naturally based on what works
|
|
- Focus on solving the actual problem: Manage complexity in development
|
|
|
|
## Observations
|
|
|
|
- [problem] Web development without clear goals and documentation circular refactoring cycles #complexity
|
|
- [solution] Specification-driven development reduces scope creep and context loss #process-improvement
|
|
- [pattern] basic-memory as specification engine creates recursive development loop #meta-development
|
|
- [workflow] Five-step process: Create → Discuss → Implement → Validate → Document #methodology
|
|
- [tool] Slash commands provide uniform process automation #automation
|
|
- [agent-pattern] Three specialized agents handle different implementation domains #specialization
|
|
- [success-metric] Time from spec to working implementation measures process efficiency #measurement
|
|
- [learning] Process should evolve naturally based on what works in practice #adaptation
|
|
- [format] Living specifications use checklists for progress tracking instead of static status headers #documentation
|
|
- [evolution] Specs evolve throughout implementation maintaining value as working documents #continuous-improvement
|
|
|
|
## Relations
|
|
|
|
- spec [[Spec-2: Slash Commands Reference]]
|
|
- spec [[Spec-3: Agent Definitions]]
|