Welcome to the comprehensive development practices documentation. This guide complements the main development guide (CLAUDE.md) and contributing guide.
All practices align with our core development philosophy:
BDD → ATDD → TDD → Red → Green → Refactor
Emphasizing:
- Behavior-driven development with Gherkin feature files
- Functional programming principles (pure functions, immutability, composition)
- Test-first approach with comprehensive coverage
- Clean architecture with DDD patterns
- Continuous improvement and learning
Before diving into individual practices, understand how they work together through strategic patterns:
Three interdependent capabilities required for CD excellence:
- Continuous Delivery - Deploy software safely and frequently
- Architecture - Design that enables independent deployment
- Product & Process - Organizational structure for rapid value delivery
Implement these 6 foundational practices first for maximum impact:
- Version Control (7 dependents)
- Deterministic Tests (9 dependents)
- Automated Testing (11 dependents)
- Build Automation (9 dependents)
- Infrastructure Automation (6 dependents)
- Configuration Management (5 dependents)
Key insight: These deliver ~70% of CD capability with only ~40% of effort.
52-week timeline across 5 phases:
- Foundation (Week 0-8) - Version control, testing, CI basics, team alignment
- Core Automation (Week 8-20) - Comprehensive testing, artifacts, infrastructure
- Architecture & Process (Week 20-32) - Modularity, BDD, deployment safety
- Advanced Capabilities (Week 32-44) - On-demand deployment, advanced testing
- Optimization (Week 44-52) - Data-driven development, analytics, excellence
Focus: Writing clean, maintainable, functional code
Key Practices:
- Pure functions with no side effects
- Immutability using Object.freeze
- Function composition with pipe/compose
- Declarative programming over imperative
- No classes - functional approach only
Quick Start: Review CLAUDE.md Functional Programming section
Focus: Comprehensive test coverage following the testing pyramid
Coverage Targets:
- Domain layer: 95-100% (enforced)
- Application layer: 85-95%
- Infrastructure layer: 75-85%
- UI components: 70-80%
Testing Stack:
- Unit/Integration: Vitest + @testing-library/svelte
- E2E: Playwright
- Test data: Builder pattern in
/tests/utils/builders.js
Key Practices:
- Deterministic Tests - Foundation of trunk-based development
- Unit, integration, and E2E testing strategies
- Test data builders and fixtures
- Mocking and test isolation
Critical Dependency Chain:
Trunk-based Development → Deterministic Tests → (Behavior + Tooling) → Testable Acceptance Criteria → BDD
Quick Start: See TESTING-GUIDE.md and Deterministic Tests.
Related Agents: Test Quality Reviewer
Focus: Version control best practices and collaboration
Key Practices:
- Conventional commits (enforced by commitlint)
- Feature branches with descriptive names
- Pre-commit hooks with lint-staged
- Pull request reviews required
- Clean, atomic commits
Quick Start: See CONTRIBUTING.md for commit message format.
Focus: Continuous integration and deployment automation
Current Setup:
- GitHub Actions for CI
- Automated testing on every push
- Static site deployment via Netlify
- File-based data architecture (no database required)
Quick Start: See RELEASE-WORKFLOW.md for release process.
Focus: Application security and data protection
Key Practices:
- Input validation using value objects
- File-based data architecture (no SQL injection vectors)
- Secure handling of user input
- npm audit in CI pipeline
- OWASP Top 10 awareness
Quick Start: Review data validation in FILE-BASED-DATA.md
Focus: Building inclusive, accessible applications
Key Practices:
- Semantic HTML first
- ARIA attributes when necessary (sparingly)
- Keyboard navigation support
- Screen reader testing
- Color contrast compliance (WCAG 2.1 AA)
Quick Start: Use data-testid for elements and test with getByRole queries.
Related Agents: Tailwind Expert includes accessibility checks.
Focus: Optimizing application speed and efficiency
Key Practices:
- Code splitting by route (automatic with SvelteKit)
- Lazy loading components with dynamic imports
- Bundle size monitoring
- Static site generation for optimal performance
- Core Web Vitals tracking
Quick Start: Use Vite's bundle analyzer to identify large dependencies.
Focus: Writing effective code and feature documentation
Key Practices:
- Gherkin feature files in
/featuresdirectory - Living documentation aligned with implementation
- JSDoc for public APIs
- README files for major directories
- Inline comments explaining "why" not "what"
Quick Start: See CLAUDE.md BDD section for feature file examples.
Related Agents: BDD Expert reviews feature documentation.
Focus: System design and architectural patterns
Current Architecture:
- Hexagonal architecture (Domain, Application, Infrastructure)
- Domain-Driven Design with value objects and entities
- Repository pattern for data access (file-based)
- Functional core, imperative shell
- No framework dependencies in domain layer
Quick Start: Review DATA-STRUCTURE.md and FILE-BASED-DATA.md.
Related Agents: DDD Expert
- Read CLAUDE.md for complete development workflow
- Review CONTRIBUTING.md and COMMIT-CONVENTIONS.md for Git practices
- Study TESTING-GUIDE.md for testing approach
- Set up local environment with
npm installandnpm run dev
- Refer to TESTING-GUIDE.md when writing tests
- Use Test Quality Reviewer agent before committing
- Follow BDD Expert agent for feature files
- Consult DDD Expert agent for domain modeling
- Verify all tests pass (unit, integration, E2E)
- Check test coverage meets targets by layer
- Ensure feature files align with implementation
- Validate functional programming patterns (no classes, immutability)
- Run expert agents for automated review
┌─────────────────────────────────────────────────────────────┐
│ PHASE 1: BDD (Feature Definition) │
├─────────────────────────────────────────────────────────────┤
│ 1. Write Gherkin feature file in /features │
│ 2. → RUN BDD EXPERT AGENT for review │
│ 3. Apply recommendations and refine scenarios │
│ 4. Review with stakeholders │
│ 5. → RUN DDD EXPERT AGENT for domain modeling │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ PHASE 2: ATDD (Acceptance Tests) │
├─────────────────────────────────────────────────────────────┤
│ 1. Convert Gherkin scenarios to Playwright E2E tests │
│ 2. Write failing E2E tests in /tests/e2e │
│ 3. → RUN TEST QUALITY REVIEWER AGENT │
│ 4. Refactor tests based on feedback │
│ 5. Ensure accessibility requirements covered │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ PHASE 3: TDD (Unit/Integration Tests) │
├─────────────────────────────────────────────────────────────┤
│ 1. Write failing unit tests in /tests/unit │
│ 2. Implement domain models with pure functions │
│ 3. → RUN TEST QUALITY REVIEWER AGENT │
│ 4. Refactor using functional patterns │
│ 5. Ensure all tests pass and coverage targets met │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ PHASE 4: Implementation │
├─────────────────────────────────────────────────────────────┤
│ 1. Implement UI components (Svelte) │
│ 2. Implement application services │
│ 3. Implement infrastructure (file repositories) │
│ 4. → RUN TAILWIND EXPERT AGENT for styling │
│ 5. Optimize performance and accessibility │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ PHASE 5: Review & Merge │
├─────────────────────────────────────────────────────────────┤
│ 1. Run linting: npm run lint │
│ 2. Run tests: npm test │
│ 3. Run E2E tests: npm run test:e2e │
│ 4. Create PR with descriptive title │
│ 5. Address code review feedback │
│ 6. Merge when all checks pass │
└─────────────────────────────────────────────────────────────┘
| When you need... | Consult... |
|---|---|
| To understand development workflow | CLAUDE.md |
| To write tests | TESTING-GUIDE.md |
| To make a commit | CONTRIBUTING.md |
| To understand release process | RELEASE-WORKFLOW.md |
| To understand data architecture | FILE-BASED-DATA.md |
| To understand domain model | DATA-STRUCTURE.md |
| To review feature files | BDD Expert Agent |
| To review tests | Test Quality Reviewer Agent |
| To model domain | DDD Expert Agent |
| To style components | Tailwind Expert Agent |
Based on comprehensive project analysis, here are the priority improvements identified:
- Error Handling Strategy - Create centralized error classes and handling utilities
- Logging and Monitoring - Implement structured logging with levels
- Environment Configuration - Add validation for required environment variables
- Security Documentation - Create SECURITY.md with vulnerability disclosure
- Performance Monitoring - Add Lighthouse CI and Core Web Vitals tracking
- Code Review Guidelines - Create PR template and review checklist
- Dependency Management - Configure Dependabot for automated updates
- Developer Experience - Add VS Code workspace settings and .nvmrc
- Data Management - Document data file update procedures and validation
Full Gap Analysis: See /docs/research/project-gap-analysis.md (if created by analyst agent)
This project uses specialized expert agents to ensure quality at each stage of development:
Use for: Reviewing Gherkin feature files When: After creating or updating feature files Run: Via Claude Code Task tool
Use for: Domain modeling and bounded context identification When: During initial feature planning and domain design Run: Via Claude Code Task tool
Use for: Reviewing unit, integration, and E2E tests When: After writing or updating test files Run: Via Claude Code Task tool
Use for: Reviewing Tailwind usage and responsive design When: During component styling and layout design Run: Via Claude Code Task tool
See: CLAUDE.md Expert Agents section for detailed workflows
Found a better practice? Want to improve documentation?
- Follow CONTRIBUTING.md commit conventions
- Ensure examples use functional programming (no classes)
- Include tests where applicable
- Link related agents if relevant
- Update this README if adding new practice categories
- CLAUDE.md - Main development guide with BDD/ATDD/TDD workflow
- TESTING-GUIDE.md - Comprehensive testing practices
- CONTRIBUTING.md - Contributor guidelines and Git workflow
- FILE-BASED-DATA.md - File-based data architecture
- DATA-STRUCTURE.md - Domain model and data structures
- RELEASE-WORKFLOW.md - Release process and automation
- COMMIT-CONVENTIONS.md - Commit message format
- Expert Agents - AI-powered code review agents
The following research documents informed these practices:
- Svelte/SvelteKit Best Practices - Latest 2024-2025 practices (created by research agent)
- Project Gap Analysis - Comprehensive analysis of missing practices (created by analyst agent)
- Documentation Structure Design - Scalable practices organization (created by coder agent)
- Testing Practices Documentation - Complete testing guide (created by tester agent)
Last Updated: 2025-10-18 Version: 1.0.0
This is a living document. If you find:
- Missing practices or gaps in coverage
- Outdated information or incorrect examples
- Better approaches or more efficient patterns
- Areas needing clarification
Please open an issue or submit a PR following CONTRIBUTING.md!