TDD-Driven Web Development with AI
A Test-Driven Development methodology specifically designed for AI-assisted coding. This skill helps build web applications through a strict 10-milestone approach where each milestone has clear pass/fail criteria that must be met before proceeding.
Overview
This skill implements a rigorous TDD workflow that improves AI coding reliability by enforcing clear success criteria at each development stage. Each milestone must pass its specific test before moving forward, ensuring incremental, validated progress.
Architecture Pattern
The skill follows a simple, proven architecture:
**Backend**: Python HTTP server serving both static files and API endpoints**Frontend**: Single HTML page with JavaScript for user interaction**Communication**: HTTP requests between frontend and backend**Development Port**: localhost:8000Development Setup
Virtual Environment Management
Always activate the Python virtual environment before starting work:
```bash
source venv/bin/activate
```
Running the Application
```bash
python app.py
```
Navigate to http://localhost:8000 to access the application.
File Structure
```
/
├── app.py # Python HTTP server
├── index.html # Frontend interface
├── static/ # Static assets (if needed)
├── venv/ # Python virtual environment
└── CLAUDE.md # Project guidance
```
The 10 TDD Milestones
Each milestone builds incrementally on the previous one. You must complete and test each milestone before proceeding to the next.
Milestone 1: Local Development Setup
**Goal**: Basic server + HTML with button**Test**: Server runs, page loads, button appears**Pass Criteria**: Can click button in browserMilestone 2: Backend Foundation
**Goal**: API endpoint returning JSON**Test**: GET/POST request to endpoint returns valid JSON**Pass Criteria**: Response has correct structure and status codeMilestone 3: Frontend Connection
**Goal**: JavaScript request handling**Test**: Button click triggers API call**Pass Criteria**: Network tab shows request to backendMilestone 4: End-to-End Local Test
**Goal**: Complete request/response cycle**Test**: User action → backend processing → UI update**Pass Criteria**: UI shows response data after interactionMilestone 5: Error Handling
**Goal**: Graceful failure management**Test**: Stop server, trigger action, verify error message**Pass Criteria**: User sees helpful error message, app doesn't crashMilestone 6: Data Processing
**Goal**: Input validation and formatting**Test**: Send various inputs (valid/invalid)**Pass Criteria**: Backend validates correctly, returns appropriate responsesMilestone 7: UI Enhancement
**Goal**: Loading states and interaction polish**Test**: Verify loading indicators, disabled states**Pass Criteria**: User sees feedback during processingMilestone 8: Deployment Preparation
**Goal**: Production configuration**Test**: Environment variables, production settings**Pass Criteria**: App configured for production environmentMilestone 9: Live Deployment
**Goal**: Production deployment**Test**: Deploy to hosting platform**Pass Criteria**: App accessible via public URLMilestone 10: Production Validation
**Goal**: Full acceptance testing**Test**: End-to-end tests on production**Pass Criteria**: All functionality works in productionDevelopment Rules
1. **Virtual Environment**: Always run `source venv/bin/activate` before Python work
2. **Use MCP Servers**:
- Context7 for documentation
- GitHub MCP for version control
3. **Strict TDD**: Each milestone must pass its test before proceeding
4. **No Jumping Ahead**: Complete milestones in sequential order
5. **Clear Pass/Fail**: Every test has measurable success conditions
6. **Commit Each Milestone**: After test passes, commit to version control before proceeding
7. **Iterative Refinement**: Build on previous milestones without breaking them
8. **Documentation**: Use MCP servers for documentation references when needed
Testing Methodology
Testing is performed manually through:
**Browser Functionality**: Run server and verify UI behavior**Developer Tools**: Check network requests, console logs, errors**Error Conditions**: Stop server, test invalid inputs, verify error handling**Performance**: Validate response times and user experience**Reproducibility**: Tests must produce consistent resultsKey Design Principles
**Minimal Dependencies**: Uses Python standard library only (http.server, socketserver) to reduce complexity**Clear Success Criteria**: Each milestone has objective, reproducible pass/fail conditions**Incremental Validation**: Every step is tested before moving forward**AI Reliability Focus**: Structure designed to improve AI coding reliability through clear constraints**Simple Architecture**: Complexity is in the methodology, not the technology stackTesting Commands
Manual testing workflow:
1. Start the server: `python app.py`
2. Open browser to http://localhost:8000
3. Open browser developer tools (F12)
4. Perform milestone-specific test actions
5. Verify results against pass criteria
6. Document test results
When to Use This Skill
Use this skill when:
Building a new web application with AI assistanceYou want rigorous, validated progress at each stepTesting how TDD methodology improves AI coding reliabilityLearning disciplined development practicesEnsuring each feature works before adding complexityImportant Notes
Focus is on proving TDD methodology effectiveness, not complex functionalityTests must be reproducible and have clear success/failure criteriaEach milestone builds incrementally on the previous oneDo not proceed to the next milestone until the current one passesUse Context7 MCP server for documentation/library references when neededCommit each milestone to version control after test completionExample Workflow
```bash
1. Activate virtual environment
source venv/bin/activate
2. Work on Milestone 1
... implement basic server and HTML ...
3. Test Milestone 1
python app.py
Open browser, verify button appears and is clickable
4. Milestone 1 passes - commit
git add .
git commit -m "Milestone 1: Local development setup complete"
5. Proceed to Milestone 2
... implement API endpoint ...
6. Test Milestone 2
Verify JSON response from endpoint
7. Continue this pattern through all 10 milestones
```
This skill proves that Test-Driven Development can significantly improve AI coding reliability by providing clear pass/fail criteria at each development stage.