Software Engineering Workflow
Implements software products from requirements and design artifacts with iterative development loops.
Prerequisites
Before starting, ensure you have:
- •Product requirements (user stories, acceptance criteria)
- •Technical requirements (NFRs, constraints)
- •Architecture design (component diagrams, data models)
- •Interface contracts (API specs, CLI syntax)
If missing, run product-development skill first.
Role Boundaries
| Activity | Claude | User |
|---|---|---|
| Scaffold code | ✅ Creates structure, stubs | Reviews structure |
| Write tests | ✅ Implements test cases | Reviews coverage |
| Implement code | ✅ Writes implementation | Reviews, approves |
| Debug failures | ✅ Analyzes, proposes fixes | Confirms direction |
| Approval gates | ✅ Shows status, asks | Approves / requests changes |
Iteration Limits
| Loop | Max Iterations | Escalation |
|---|---|---|
| Test coverage review | 3 | "Coverage target may be unrealistic" |
| Red-Green-Refactor | 5 per component | "Component may need redesign" |
| Fix-Retest (simulation) | 3 | "Architecture may have fundamental issues" |
Escalation options: (A) Accept current state, (B) Reduce scope, (C) Return to product-development for redesign
Artifacts Location
Implementation outputs go to project root (alongside planning):
code
project/
├── planning/ # From product-development
├── src/ # Phase 1: scaffolding
│ └── {modules}/
├── tests/ # Phase 2: test files
│ ├── unit/
│ ├── integration/
│ └── e2e/
├── flake.nix # From nix-devenv
├── Containerfile # From podman-deploy
├── .github/workflows/ # From github-actions-ci
└── docs/ # From sphinx-docs
Workflow Overview
code
┌─────────────────────────────────────────────────────────────────┐ │ SOFTWARE ENGINEERING │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Phase 1: Code Scaffolding ──────────────────→ User Approval │ │ │ │ │ ┌──────────┘ │ │ ▼ │ │ Phase 2: Test Development ←────── Review Loop ──→ User Approval│ │ │ ▲ │ │ │ │ │ │ ▼ │ │ │ Phase 3: Implementation ───────────────────────→ User Approval │ │ │ ▲ │ │ │ │ │ │ └─── Red/Green/Refactor Loop │ │ │ │ Phase 4: Simulation Testing (if needed) ────→ User Approval │ │ │ ▲ │ │ │ │ │ │ └─── Fix/Retest Loop │ │ │ └─────────────────────────────────────────────────────────────────┘
Companion Skills
| Task | Skill | When |
|---|---|---|
| Create diagrams | diagrams-kroki | Architecture visualization |
| Setup environment | nix-devenv | Before scaffolding |
| Container builds | podman-deploy | Deployment prep |
| CI/CD pipelines | github-actions-ci | After implementation |
| Documentation | sphinx-docs | Throughout |
| Complexity scoring | dynamic-tasks | For iteration planning |
Phase 1: Code Scaffolding
Goal: Create project structure matching architecture design.
Checklist
code
Scaffolding: - [ ] Project directory structure created - [ ] Module/package stubs with signatures - [ ] Configuration files (env, build, lint) - [ ] Dependency management setup - [ ] Development environment working
Activities
- •Create directory structure matching component diagram
- •Stub out modules with interfaces (no implementation)
- •Setup build tooling (Makefile, justfile, package.json)
- •Configure linting/formatting rules
- •Verify environment builds without errors
Approval Gate
markdown
## Phase 1 Complete: Code Scaffolding **Structure Created**: - [X] /cmd/app/main.go - [X] /internal/service/... - [X] /pkg/api/... **Build Status**: ✅ Compiles **Lint Status**: ✅ Passes **Do you approve? Any structure changes needed?**
Phase 2: Test Development
Goal: Write tests before implementation (TDD).
Test Pyramid
code
╱╲
╱ ╲ E2E Tests (few)
╱────╲ - User journey validation
╱ ╲
╱────────╲ Integration Tests (some)
╱ ╲ - API contracts, DB interactions
╱────────────╲
╱ ╲ Unit Tests (many)
╱────────────────╲ - Business logic, edge cases
Review Loop
code
┌─────────────────────────────────────────┐ │ TEST REVIEW LOOP │ ├─────────────────────────────────────────┤ │ │ │ Write Tests ──→ Review Coverage │ │ ▲ │ │ │ │ ▼ │ │ │ Gaps Found? │ │ │ ╱ ╲ │ │ │ Yes No │ │ │ ╱ ╲ │ │ └───────╱ ╲───→ Done │ │ │ └─────────────────────────────────────────┘
Test Categories
| Category | Tests For | Coverage Target |
|---|---|---|
| Unit | Business logic, utilities | >80% |
| Integration | APIs, database, services | Key paths |
| Contract | API request/response | All endpoints |
| E2E | User flows | Critical paths |
Checklist
code
Test Development: - [ ] Unit tests for each component - [ ] Integration tests for interfaces - [ ] Contract tests for APIs - [ ] E2E tests for critical user flows - [ ] All tests failing (red) - not implemented yet - [ ] Test coverage report generated
Approval Gate
markdown
## Phase 2 Complete: Test Development **Test Summary**: | Type | Count | Status | |------|-------|--------| | Unit | X | 🔴 Failing (expected) | | Integration | X | 🔴 Failing (expected) | | E2E | X | 🔴 Failing (expected) | **Coverage Targets**: - Unit: X% target - Critical paths: All covered **Do you approve? Any test cases missing?**
Phase 3: Implementation
Goal: Make all tests pass with clean code.
Red-Green-Refactor Loop
code
┌─────────────────────────────────────────┐ │ RED-GREEN-REFACTOR LOOP │ ├─────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ │ ▼ │ │ │ RED ────→ GREEN ────→ REFACTOR ─┘ │ │ (test (make it (make it │ │ fails) pass) clean) │ │ │ │ Repeat for each component │ │ │ └─────────────────────────────────────────┘
Implementation Order
- •Core domain logic (no dependencies)
- •Data layer (repositories, models)
- •Service layer (business operations)
- •API/Interface layer (handlers, CLI)
- •Integration points (external services)
Per-Component Checklist
code
Component: [Name]
- [ ] Tests exist and are red
- [ ] Implementation complete
- [ ] Tests green
- [ ] Code reviewed for:
- [ ] No hardcoded values
- [ ] Error handling
- [ ] Logging
- [ ] No security issues
- [ ] Refactored for clarity
Iteration Pattern
For each component:
markdown
### Implementing: [Component Name] **Current Status**: 🔴 X tests failing **Implementation**: [Code changes here] **After Implementation**: 🟢 All tests passing **Refactoring needed?** | Issue | Action | |-------|--------| | [Issue] | [Refactor] | **Ready to proceed to next component?**
Approval Gate
markdown
## Phase 3 Progress: Implementation **Component Status**: | Component | Tests | Status | |-----------|-------|--------| | Domain | 15/15 | 🟢 | | Repository | 8/8 | 🟢 | | Service | 12/12 | 🟢 | | API | 10/10 | 🟡 In Progress | **Overall**: 35/45 tests passing (78%) **Continue with next component?**
Phase 4: Simulation Testing
Goal: Validate system under realistic conditions.
When Required
- • Distributed system with multiple services
- • High-throughput requirements (>100 req/s)
- • Complex state machines
- • Critical failure handling needed
- • External dependency interactions
If none apply: Skip with justification.
Fix-Retest Loop
code
┌─────────────────────────────────────────┐ │ FIX-RETEST LOOP │ ├─────────────────────────────────────────┤ │ │ │ Run Simulation ──→ Issues Found? │ │ ▲ │ │ │ │ Yes │ No │ │ │ ▼ ╲ │ │ │ Fix Issues ╲ │ │ │ │ ╲ │ │ └──────────────────┘ → Done │ │ │ └─────────────────────────────────────────┘
Test Types
| Type | Purpose | Tools |
|---|---|---|
| Load | Throughput limits | k6, Artillery |
| Chaos | Failure handling | toxiproxy, scripts |
| State | Complex transitions | Custom harness |
| Soak | Memory leaks, degradation | k6 (long run) |
Checklist
code
Simulation Testing: - [ ] Load test baseline established - [ ] Peak load tested - [ ] Failure scenarios validated - [ ] Recovery verified - [ ] Performance baseline documented
Approval Gate
markdown
## Phase 4 Complete: Simulation Testing **Results Summary**: | Test | Target | Actual | Status | |------|--------|--------|--------| | Max throughput | >100 req/s | 150 req/s | ✅ | | p95 latency | <200ms | 180ms | ✅ | | Recovery time | <30s | 25s | ✅ | **Issues Found & Fixed**: | Issue | Resolution | |-------|------------| | [Issue] | [Fix] | **Production Ready?**
Completion
markdown
## Software Engineering Complete **Final Status**: - [ ] All code scaffolded - [ ] All tests written and passing - [ ] All components implemented - [ ] Simulation testing complete (or skipped with justification) - [ ] Documentation updated - [ ] Ready for deployment **Artifacts Produced**: - Source code in repository - Test suite (X tests) - CI pipeline configured - Documentation generated **Next Steps**: - Deploy to staging (use `podman-deploy` skill) - Setup CI/CD (use `github-actions-ci` skill)
Interaction Style
- •Iterate: Use loops, don't assume first attempt is final
- •Test First: Always write tests before implementation
- •Small Steps: One component at a time
- •Verify Often: Run tests after each change
- •Approval Gates: Wait for user approval between phases