forked from cardosofelipe/fast-next-template
docs(workflow): enforce stack verification as mandatory step
- Added "Stack Verification" section to CLAUDE.md with detailed steps. - Updated WORKFLOW.md to mandate running the full stack before marking work as complete. - Prevents issues where high test coverage masks application startup failures.
This commit is contained in:
31
CLAUDE.md
31
CLAUDE.md
@@ -83,6 +83,37 @@ docs/
|
||||
3. **Testing Required**: All code must be tested, aim for >90% coverage
|
||||
4. **Code Review**: Must pass multi-agent review before merge
|
||||
5. **No Direct Commits**: Never commit directly to `main` or `dev`
|
||||
6. **Stack Verification**: ALWAYS run the full stack before considering work done (see below)
|
||||
|
||||
### CRITICAL: Stack Verification Before Merge
|
||||
|
||||
**This is NON-NEGOTIABLE. A feature with 100% test coverage that crashes on startup is WORTHLESS.**
|
||||
|
||||
Before considering ANY issue complete:
|
||||
|
||||
```bash
|
||||
# 1. Start the dev stack
|
||||
make dev
|
||||
|
||||
# 2. Wait for backend to be healthy, check logs
|
||||
docker compose -f docker-compose.dev.yml logs backend --tail=100
|
||||
|
||||
# 3. Start frontend
|
||||
cd frontend && npm run dev
|
||||
|
||||
# 4. Verify both are running without errors
|
||||
```
|
||||
|
||||
**The issue is NOT done if:**
|
||||
- Backend crashes on startup (import errors, missing dependencies)
|
||||
- Frontend fails to compile or render
|
||||
- Health checks fail
|
||||
- Any error appears in logs
|
||||
|
||||
**Why this matters:**
|
||||
- Tests run in isolation and may pass despite broken imports
|
||||
- Docker builds cache layers and may hide dependency issues
|
||||
- A single `ModuleNotFoundError` renders all test coverage meaningless
|
||||
|
||||
### Common Commands
|
||||
|
||||
|
||||
@@ -214,9 +214,9 @@ test(frontend): add unit tests for ProjectDashboard
|
||||
|
||||
---
|
||||
|
||||
## Phase 2+ Implementation Workflow
|
||||
## Rigorous Implementation Workflow
|
||||
|
||||
**For complex infrastructure issues (Phase 2 MCP, core systems), follow this rigorous process:**
|
||||
**This workflow applies to ALL feature implementations. Follow this process rigorously:**
|
||||
|
||||
### 1. Branch Setup
|
||||
```bash
|
||||
@@ -257,12 +257,42 @@ Before closing an issue, perform deep review from multiple angles:
|
||||
|
||||
**No stone unturned. No sloppy results. No unreviewed work.**
|
||||
|
||||
### 5. Final Validation
|
||||
### 5. Stack Verification (CRITICAL - NON-NEGOTIABLE)
|
||||
|
||||
**ALWAYS run the full stack and verify it boots correctly before considering ANY work done.**
|
||||
|
||||
```bash
|
||||
# Start the full development stack
|
||||
make dev
|
||||
|
||||
# Check backend logs for startup errors
|
||||
docker compose -f docker-compose.dev.yml logs backend --tail=100
|
||||
|
||||
# Start frontend separately
|
||||
cd frontend && npm run dev
|
||||
|
||||
# Check frontend console for errors
|
||||
```
|
||||
|
||||
**A feature is NOT complete if:**
|
||||
- The stack doesn't boot
|
||||
- There are import errors in logs
|
||||
- Health checks fail
|
||||
- Any component crashes on startup
|
||||
|
||||
**This rule exists because:**
|
||||
- Tests can pass but the application won't start (import errors, missing deps)
|
||||
- 90% test coverage is worthless if the app crashes on boot
|
||||
- Docker builds can mask local issues
|
||||
|
||||
### 6. Final Validation Checklist
|
||||
- [ ] All tests pass (unit, integration, E2E)
|
||||
- [ ] Type checking passes
|
||||
- [ ] Linting passes
|
||||
- [ ] **Stack boots successfully** (backend + frontend)
|
||||
- [ ] **Logs show no errors**
|
||||
- [ ] Coverage meets threshold (>90% backend, >90% frontend)
|
||||
- [ ] Documentation updated
|
||||
- [ ] Coverage meets threshold
|
||||
- [ ] Issue checklist 100% complete
|
||||
- [ ] Multi-agent review passed
|
||||
|
||||
|
||||
Reference in New Issue
Block a user