main (always releasable)
├── feature/us-123-recommendation-api (lifespan: 1-2 days)
├── feature/us-124-websocket-updates (lifespan: 1-2 days)
└── fix/recommendation-null-check (lifespan: 4 hours)

// src/config/feature-flags.ts
export const FEATURE_FLAGS = {
  RECOMMENDATION_V2: process.env.FEATURE_RECOMMENDATION_V2 === 'true',
  WEBSOCKET_REAL_TIME: process.env.FEATURE_WEBSOCKET === 'true',
} as const;

// Usage in component
function HomePage() {
  return (
    <div>
      {FEATURE_FLAGS.RECOMMENDATION_V2 && <RecommendationSection />}
      <ProductList />
    </div>
  );
}

# Recommended workflow
git checkout -b feature/us-123-recommendation-api
# Develop with Claude (multiple small commits)
git commit -m "feat(recommendation): add purchase history query"
git commit -m "test(recommendation): add unit tests for recommendation service"
git commit -m "feat(recommendation): add recommendation API endpoint"
# Create PR → CI passes → Code review → Merge

type(scope): description

[optional body]

[optional footer(s)]

feat(recommendation): add purchase history based product recommendations

- Implement collaborative filtering algorithm
- Add RecommendationService with top-10 product selection
- Exclude already purchased products from recommendations

Closes #123

# Install conventional-changelog
npm install --save-dev @commitlint/cli @commitlint/config-conventional
npm install --save-dev conventional-changelog-cli

# .commitlintrc.json
{
  "extends": ["@commitlint/config-conventional"]
}

# package.json scripts
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
    "release": "standard-version"
  }
}

# Changelog

## [1.3.0] - 2026-03-17

### Features

- **recommendation:** add purchase history based product recommendations

### Bug Fixes

- **cart:** fix quantity update when adding duplicate items

### Performance

- **recommendation:** add Redis caching for recommendation results

# .github/workflows/ai-code-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get PR diff
        id: diff
        run: |
          git diff origin/main...HEAD > pr_diff.txt
          echo "diff_size=$(wc -l < pr_diff.txt)" >> $GITHUB_OUTPUT

      - name: AI Review with Claude API
        if: steps.diff.outputs.diff_size < 1000
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          node scripts/ai-review.js

# Set via GitHub CLI
gh api repos/OWNER/REPO/branches/main/protection \
--method PUT \
--field required_status_checks='{"strict":true,"contexts":["ci/build","ci/test","ci/lint"]}' \
--field enforce_admins=true \
--field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
--field restrictions=null

# .github/CODEOWNERS
# Core architecture files
/src/core/ @senior-dev @tech-lead
/src/domain/ @domain-expert

# Security related
/src/auth/ @security-team
*.env* @security-team

# CI/CD config
/.github/ @devops-team
/docker/ @devops-team

# .github/workflows/ci-cd.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  NODE_VERSION: '20'
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  # ─── CI Stage ────────────────────────────────────────

  lint:
    name: Lint & Format Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run format:check

  type-check:
    name: TypeScript Type Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run type-check

  test-unit:
    name: Unit Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run test:unit -- --coverage
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          flags: unit

  test-integration:
    name: Integration Tests
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: testpassword
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
      redis:
        image: redis:7
        ports:
          - 6379:6379
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run test:integration
        env:
          DATABASE_URL: postgresql://postgres:testpassword@localhost:5432/testdb
          REDIS_URL: redis://localhost:6379

  security-scan:
    name: Security Scan
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          scan-ref: '.'
          format: 'sarif'
          output: 'trivy-results.sarif'
      - name: Upload Trivy scan results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: 'trivy-results.sarif'
      - name: npm audit
        run: npm audit --audit-level=high

  mutation-test:
    name: Mutation Testing
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npx stryker run
      - name: Comment mutation score on PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = JSON.parse(fs.readFileSync('reports/mutation/mutation.json'));
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Mutation Score: ${report.metrics.mutationScore.toFixed(1)}%`
            });

  # ─── CD Stage (main branch only) ──────────────────

  build-image:
    name: Build & Push Docker Image
    runs-on: ubuntu-latest
    needs: [lint, type-check, test-unit, test-integration, security-scan]
    if: github.ref == 'refs/heads/main'
    outputs:
      image-digest: ${{ steps.build.outputs.digest }}
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build and push
        id: build
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

  deploy-staging:
    name: Deploy to Staging
    runs-on: ubuntu-latest
    needs: [build-image]
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Kubernetes Staging
        run: |
          kubectl set image deployment/app \
            app=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build-image.outputs.image-digest }} \
            --namespace=staging
          kubectl rollout status deployment/app --namespace=staging

  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: [deploy-staging]
    environment:
      name: production
      url: https://myapp.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Production
        run: |
          kubectl set image deployment/app \
            app=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build-image.outputs.image-digest }} \
            --namespace=production
          kubectl rollout status deployment/app --namespace=production

.claude/
  commands/
    commit.md
    pr-description.md
    test.md
    review.md
    docs.md
    refactor.md
    security-check.md
    changelog.md

# commit

Analyzes staged changes and generates a commit message following the Conventional Commits specification.

## Rules

- Use feat/fix/docs/style/refactor/test/chore/perf types
- scope is the affected module/component (optional)
- Subject: under 50 chars, present tense, lowercase first letter
- Body: explain what and why was changed
- Add BREAKING CHANGE in footer if applicable

## Output format

# pr-description

Analyzes changes in the current branch and generates a PR description.

## Output format

### Summary of Changes

[1-3 line summary]

### Work Done

- [ ] Implementation item 1
- [ ] Implementation item 2

### How to Test

1. Step-by-step testing instructions

### Screenshots (if UI changes)

[Add screenshots here]

### Related Issues

Closes #issue-number

### Checklist

- [ ] Unit tests written
- [ ] Integration tests passing
- [ ] CLAUDE.md rules followed
- [ ] Documentation updated (if needed)

# test

Generates comprehensive tests for the selected file or function.

## Includes

1. Unit tests (Jest/Vitest)
   - Happy path cases
   - Edge cases (boundary values, null, undefined)
   - Error cases
2. Mock setup
3. Property-based tests (for complex business logic)

## Rules

- Follow test coverage goals in CLAUDE.md
- Use AAA pattern (Arrange/Act/Assert)
- Use async/await for async tests

# review

Performs an in-depth code review on current changes or specified files.

## Review Checklist

### Code Quality

- [ ] SOLID principles compliance
- [ ] DRY principle (no duplicate code)
- [ ] Single responsibility for functions/classes
- [ ] Naming conventions (per CLAUDE.md)

### Security

- [ ] SQL injection risk
- [ ] XSS vulnerabilities
- [ ] Sensitive data exposure (secrets, PII)
- [ ] Authentication/authorization validation

### Performance

- [ ] N+1 query problems
- [ ] Unnecessary re-renders
- [ ] Memory leak risks

### Testing

- [ ] Sufficient test coverage
- [ ] Edge case coverage

## Output Format

For each issue: [Critical/Major/Minor] description + improved code example

# refactor

Generates refactoring suggestions for selected code.

## Analysis Criteria

1. Extract Method: Split long functions into meaningful functions
2. Extract Class: Separate classes violating Single Responsibility
3. Replace Conditional with Polymorphism: Remove if/else chains
4. Introduce Parameter Object: Functions with 3+ parameters
5. Remove Duplicate Code: Consolidate duplicated logic

## Output Format

- Explanation of problems in original code
- Refactored code
- Reason for change
- Additional considerations

# docs

Generates documentation for selected code.

## Generated Items

1. JSDoc/TSDoc comments
2. README.md (module or function description)
3. API documentation (OpenAPI/Swagger format)

## Rules

- Include code examples
- Explain parameter types and meanings
- Describe return values
- Document exception cases

// eslint.config.js (ESLint v9 flat config)
import js from '@eslint/js'
import typescript from '@typescript-eslint/eslint-plugin'
import tsParser from '@typescript-eslint/parser'
import prettier from 'eslint-config-prettier'
import importPlugin from 'eslint-plugin-import'
import sonarjs from 'eslint-plugin-sonarjs'

export default [
  js.configs.recommended,
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: './tsconfig.json',
      },
    },
    plugins: {
      '@typescript-eslint': typescript,
      import: importPlugin,
      sonarjs: sonarjs,
    },
    rules: {
      // TypeScript rules
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/strict-null-checks': 'error',
      '@typescript-eslint/no-unused-vars': 'error',
      '@typescript-eslint/explicit-function-return-type': 'warn',

      // Complexity limits
      complexity: ['error', 10],
      'max-lines-per-function': ['warn', 30],
      'max-depth': ['error', 3],

      // SonarJS code quality
      'sonarjs/no-duplicate-string': 'warn',
      'sonarjs/cognitive-complexity': ['error', 15],
      'sonarjs/no-identical-functions': 'error',

      // Import ordering
      'import/order': [
        'error',
        {
          groups: ['builtin', 'external', 'internal', 'parent', 'sibling'],
          'newlines-between': 'always',
        },
      ],
    },
  },
  prettier,
]

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

# .github/workflows/sonarqube.yml
name: SonarQube Analysis

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  sonar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run test:unit -- --coverage
      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        with:
          args: >
            -Dsonar.projectKey=my-project
            -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info
            -Dsonar.qualitygate.wait=true

sonar.projectKey=my-ecommerce-platform
sonar.sources=src
sonar.tests=src
sonar.test.inclusions=**/*.spec.ts,**/*.test.ts
sonar.coverage.exclusions=**/*.spec.ts,**/*.test.ts,**/index.ts

// src/config/feature-flags.ts
import { z } from 'zod'

const featureFlagSchema = z.object({
  RECOMMENDATION_V2: z.boolean().default(false),
  WEBSOCKET_REAL_TIME: z.boolean().default(false),
  NEW_CHECKOUT_FLOW: z.boolean().default(false),
  AI_SEARCH: z.boolean().default(false),
})

function loadFeatureFlags() {
  return featureFlagSchema.parse({
    RECOMMENDATION_V2: process.env.FEATURE_RECOMMENDATION_V2 === 'true',
    WEBSOCKET_REAL_TIME: process.env.FEATURE_WEBSOCKET === 'true',
    NEW_CHECKOUT_FLOW: process.env.FEATURE_NEW_CHECKOUT === 'true',
    AI_SEARCH: process.env.FEATURE_AI_SEARCH === 'true',
  })
}

export const FEATURES = loadFeatureFlags()

src/
  modules/
    user/          # Team member A owns
      domain/
      application/
      infrastructure/
      presentation/
    product/       # Team member B owns
    order/         # Team member C owns
    recommendation/ # Team member D owns
  shared/          # Shared code (minimize changes)
    utils/
    types/
    errors/

A merge conflict occurred. Analyze both changes and suggest the correct merge:

<<<<<<< HEAD (my changes)
[paste code]
=======
[paste their code]
>>>>>>> feature/recommendation

Identify the intent of both changes and generate a merged result that preserves both.

# Technical Debt Review Prompt (at Sprint end)

Analyze the following codebase and identify technical debt:
[list of changed files]

Analysis items:

1. Duplicate code (DRY violations)
2. Excessive complexity (cyclomatic complexity over 10)
3. Unnecessary abstraction layers
4. Inconsistent error handling
5. Areas with low test coverage

For each item:

- Location (file, line)
- Severity (Critical/Major/Minor)
- Estimated refactoring time
- Recommended approach

# Allocate 20% of every Sprint to resolving technical debt

# GitHub Issues label strategy
labels:
  - name: tech-debt
    color: '#e4e669'
    description: Technical debt issue
  - name: ai-generated
    color: '#7c3aed'
    description: AI-generated code needs review
  - name: needs-refactor
    color: '#f97316'
    description: Needs refactoring