gh-cskiro-claudex-analysis-tools/skills/codebase-auditor/reference/best_practices_2025.md

Modern SDLC Best Practices (2024-25)

This document outlines industry-standard software development lifecycle best practices based on 2024-25 research and modern engineering standards.

Table of Contents

1. Development Workflow
2. Testing Strategy
3. Security (DevSecOps)
4. Code Quality
5. Performance
6. Documentation
7. DevOps & CI/CD
8. DORA Metrics
9. Developer Experience
10. Accessibility

---

Development Workflow

Version Control (Git)

Branching Strategy:

• Main/master branch is always deployable
• Feature branches for new work: feature/{component-name}
• Bugfix branches: bugfix/{issue-number}
• Release branches for production releases
• No direct commits to main (use pull requests)

Commit Messages:

• Follow Conventional Commits format
• Structure: type(scope): description
• Types: feat, fix, docs, style, refactor, test, chore
• Example: feat(auth): add OAuth2 social login

Code Review:

• All changes require peer review
• Use pull request templates
• Automated checks must pass before merge
• Review within 24 hours for team velocity
• Focus on logic, security, and maintainability

Test-Driven Development (TDD)

RED-GREEN-REFACTOR Cycle:

1. RED: Write failing test first
2. GREEN: Write minimum code to pass
3. REFACTOR: Improve code quality while tests pass

Benefits:

• Better design through testability
• Documentation through tests
• Confidence to refactor
• Fewer regression bugs

---

Testing Strategy

Testing Trophy (Kent C. Dodds)

Philosophy: "Write tests. Not too many. Mostly integration."

Distribution:

• Integration Tests (70%): User workflows and component interaction

  • Test real user behavior
  • Test multiple units working together
  • Higher confidence than unit tests
  • Example: User registration flow end-to-end

• Unit Tests (20%): Complex business logic only

  • Pure functions
  • Complex algorithms
  • Edge cases and error handling
  • Example: Tax calculation logic

• E2E Tests (10%): Critical user journeys

  • Full stack, production-like environment
  • Happy path scenarios
  • Critical business flows
  • Example: Complete purchase flow

What NOT to Test (Brittle Patterns)

Avoid:

• Emoji presence in UI elements
• Exact number of DOM elements
• Specific element ordering (unless critical)
• API call counts (unless performance critical)
• CSS class names and styling
• Implementation details over user behavior
• Private methods/functions
• Third-party library internals

What to Prioritize (User-Focused)

Prioritize:

• User workflows and interactions
• Business logic and calculations
• Data accuracy and processing
• Error handling and edge cases
• Performance within acceptable limits
• Accessibility compliance (WCAG 2.1 AA)
• Security boundaries

Semantic Queries (React Testing Library)

Priority Order:

1. getByRole() - Most preferred (accessibility-first)
2. getByLabelText() - Form elements
3. getByPlaceholderText() - Inputs without labels
4. getByText() - User-visible content
5. getByDisplayValue() - Form current values
6. getByAltText() - Images
7. getByTitle() - Title attributes
8. getByTestId() - Last resort only

Coverage Targets

Minimum Requirements:

• Overall coverage: 80%
• Critical paths: 100% (auth, payment, data processing)
• Branch coverage: 75%
• Function coverage: 90%

Tools:

• Jest/Vitest for unit & integration tests
• Cypress/Playwright for E2E tests
• Istanbul/c8 for coverage reporting

---

Security (DevSecOps)

Shift-Left Security

Principle: Integrate security into every development stage, not as an afterthought.

Cost Multiplier:

• Fix in design: 1x cost
• Fix in development: 5x cost
• Fix in testing: 10x cost
• Fix in production: 30x cost

OWASP Top 10 (2024)

1. Broken Access Control: Enforce authorization checks on every request
2. Cryptographic Failures: Use TLS, encrypt PII, avoid weak algorithms
3. Injection: Validate input, use prepared statements, sanitize output
4. Insecure Design: Threat modeling, secure design patterns
5. Security Misconfiguration: Harden defaults, disable unnecessary features
6. Vulnerable Components: Keep dependencies updated, scan for CVEs
7. Authentication Failures: MFA, rate limiting, secure session management
8. Software Integrity Failures: Verify integrity with signatures, SRI
9. Security Logging: Log security events, monitor for anomalies
10. SSRF: Validate URLs, whitelist allowed domains

Dependency Management

Best Practices:

• Run npm audit / yarn audit weekly
• Update dependencies monthly
• Use Dependabot/Renovate for automated updates
• Pin dependency versions in production
• Check licenses for compliance
• Monitor CVE databases

Secrets Management

Rules:

• NEVER commit secrets to version control
• Use environment variables for configuration
• Use secret management tools (Vault, AWS Secrets Manager)
• Rotate secrets regularly
• Scan git history for leaked secrets
• Use .env.example for documentation, not .env

---

Code Quality

Complexity Metrics

Cyclomatic Complexity:

• 1-10: Simple, easy to test
• 11-20: Moderate, consider refactoring
• 21-50: High, should refactor
• 50+: Very high, must refactor

Tool: ESLint complexity rule, SonarQube

Code Duplication

Thresholds:

• < 5%: Excellent
• 5-10%: Acceptable
• 10-20%: Needs attention
• > 20%: Critical issue

DRY Principle: Don't Repeat Yourself

• Extract common code into functions/modules
• Use design patterns (Template Method, Strategy)
• Balance DRY with readability

Code Smells

Common Smells:

• God Object: Too many responsibilities
• Feature Envy: Too much coupling to other classes
• Long Method: > 50 lines
• Long Parameter List: > 4 parameters
• Dead Code: Unused code
• Magic Numbers: Hard-coded values
• Primitive Obsession: Overuse of primitives vs objects

Refactoring Techniques:

• Extract Method
• Extract Class
• Introduce Parameter Object
• Replace Magic Number with Constant
• Remove Dead Code

Static Analysis

Tools:

• SonarQube: Comprehensive code quality platform
• ESLint: JavaScript/TypeScript linting
• Prettier: Code formatting
• TypeScript: Type checking in strict mode
• Checkmarx: Security-focused analysis

---

Performance

Build Performance

Targets:

• Build time: < 2 minutes
• Hot reload: < 200ms
• First build: < 5 minutes

Optimization:

• Use build caching
• Parallelize builds
• Tree-shaking
• Code splitting
• Lazy loading

Runtime Performance

Web Vitals (Core):

• LCP (Largest Contentful Paint): < 2.5s
• FID (First Input Delay): < 100ms
• CLS (Cumulative Layout Shift): < 0.1

API Performance:

• P50: < 100ms
• P95: < 500ms
• P99: < 1000ms

Optimization Techniques:

• Caching (Redis, CDN)
• Database indexing
• Query optimization
• Compression (gzip, Brotli)
• Image optimization (WebP, lazy loading)
• Code splitting and lazy loading

Bundle Size

Targets:

• Initial bundle: < 200KB (gzipped)
• Total JavaScript: < 500KB (gzipped)
• Images optimized: < 200KB each

Tools:

• webpack-bundle-analyzer
• Lighthouse
• Chrome DevTools Performance tab

---

Documentation

Code Documentation

JSDoc/TSDoc:

• Document all public APIs
• Include examples for complex functions
• Document parameters, return types, exceptions

Example:

/**
 * Calculates the total price including tax and discounts.
 *
 * @param items - Array of cart items
 * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
 * @param discountCode - Optional discount code
 * @returns Total price with tax and discounts applied
 * @throws {InvalidDiscountError} If discount code is invalid
 *
 * @example
 * const total = calculateTotal(items, 0.08, 'SUMMER20');
 */
function calculateTotal(items: CartItem[], taxRate: number, discountCode?: string): number {
  // ...
}

Project Documentation

Essential Files:

• README.md: Project overview, setup instructions, quick start
• CONTRIBUTING.md: How to contribute, coding standards, PR process
• CODE_OF_CONDUCT.md: Community guidelines
• CHANGELOG.md: Version history and changes
• LICENSE: Legal license information
• ARCHITECTURE.md: High-level architecture overview
• ADRs (Architecture Decision Records): Document important decisions

---

DevOps & CI/CD

Continuous Integration

Requirements:

• Automated testing on every commit
• Build verification
• Code quality checks (linting, formatting)
• Security scanning
• Fast feedback (< 10 minutes)

Pipeline Stages:

1. Lint & Format Check
2. Unit Tests
3. Integration Tests
4. Security Scan
5. Build Artifacts
6. Deploy to Staging
7. E2E Tests
8. Deploy to Production (with approval)

Continuous Deployment

Strategies:

• Blue-Green: Two identical environments, switch traffic
• Canary: Gradual rollout to subset of users
• Rolling: Update instances incrementally
• Feature Flags: Control feature visibility without deployment

Rollback:

• Automated rollback on failure detection
• Keep last 3-5 versions deployable
• Database migrations reversible
• Monitor key metrics post-deployment

Infrastructure as Code

Tools:

• Terraform, CloudFormation, Pulumi
• Ansible, Chef, Puppet
• Docker, Kubernetes

Benefits:

• Version-controlled infrastructure
• Reproducible environments
• Disaster recovery
• Automated provisioning

---

DORA Metrics

Four Key Metrics (DevOps Research and Assessment):

1. Deployment Frequency

How often code is deployed to production

• Elite: Multiple times per day
• High: Once per day to once per week
• Medium: Once per week to once per month
• Low: Less than once per month

2. Lead Time for Changes

Time from commit to production

• Elite: Less than 1 hour
• High: 1 day to 1 week
• Medium: 1 week to 1 month
• Low: More than 1 month

3. Change Failure Rate

Percentage of deployments causing failures

• Elite: < 1%
• High: 1-5%
• Medium: 5-15%
• Low: > 15%

4. Time to Restore Service

Time to recover from production incident

• Elite: < 1 hour
• High: < 1 day
• Medium: 1 day to 1 week
• Low: > 1 week

Tracking: Use CI/CD tools, APM (Application Performance Monitoring), incident management systems

---

Developer Experience

Why It Matters

Statistics:

• 83% of engineers experience burnout
• Developer experience is the strongest predictor of delivery capability
• Happy developers are 2x more productive

Key Factors

Fast Feedback Loops:

• Quick build times
• Fast test execution
• Immediate linting/formatting feedback
• Hot module reloading

Good Tooling:

• Modern IDE with autocomplete
• Debuggers and profilers
• Automated code reviews
• Documentation generators

Clear Standards:

• Coding style guides
• Architecture documentation
• Onboarding guides
• Runbooks for common tasks

Psychological Safety:

• Blameless post-mortems
• Encourage experimentation
• Celebrate learning from failure
• Mentorship programs

---

Accessibility

WCAG 2.1 Level AA Compliance

Four Principles (POUR):

1. Perceivable: Information must be presentable to users

   • Alt text for images
   • Captions for videos
   • Color contrast ratios

2. Operable: UI components must be operable

   • Keyboard navigation
   • Sufficient time to read content
   • No seizure-inducing content

3. Understandable: Information must be understandable

   • Readable text
   • Predictable behavior
   • Input assistance (error messages)

4. Robust: Content must be robust across technologies

   • Valid HTML
   • ARIA attributes
   • Cross-browser compatibility

Testing Tools

Automated:

• axe DevTools
• Lighthouse
• WAVE
• Pa11y

Manual:

• Keyboard navigation testing
• Screen reader testing (NVDA, JAWS, VoiceOver)
• Color contrast checkers
• Zoom testing (200%+)

---

Modern Trends (2024-25)

AI-Assisted Development

Tools:

• GitHub Copilot
• ChatGPT / Claude
• Tabnine
• Amazon CodeWhisperer

Best Practices:

• Review all AI-generated code
• Write tests for AI code
• Understand before committing
• Train team on effective prompting

Platform Engineering

Concept: Internal developer platforms to improve developer experience

Components:

• Self-service infrastructure
• Golden paths (templates)
• Developer portals
• Observability dashboards

Observability (vs Monitoring)

Three Pillars:

1. Logs: What happened
2. Metrics: Quantitative data
3. Traces: Request flow through system

Tools:

• Datadog, New Relic, Grafana
• OpenTelemetry for standardization
• Distributed tracing (Jaeger, Zipkin)

---

Industry Benchmarks (2024-25)

Code Quality

• Tech debt ratio: < 5%
• Duplication: < 5%
• Test coverage: > 80%
• Build time: < 2 minutes

Security

• CVE remediation: < 30 days
• Security training: Quarterly
• Penetration testing: Annually

Performance

• Page load: < 3 seconds
• API response: P95 < 500ms
• Uptime: 99.9%+

Team Metrics

• Pull request review time: < 24 hours
• Deployment frequency: Daily+
• Incident MTTR: < 1 hour
• Developer onboarding: < 1 week

---

References:

• DORA State of DevOps Report 2024
• OWASP Top 10 (2024 Edition)
• WCAG 2.1 Guidelines
• Kent C. Dodds Testing Trophy
• SonarQube Quality Gates
• Google Web Vitals

Last Updated: 2024-25 Version: 1.0