ai-fastify-template AGENTS.md

AI Coding Guidelines for ai-fastify-template

🚨 CRITICAL: Zero CI Failures Guaranteed

Four-Layer Defense System prevents any CI failures:

1. Immediate Feedback (Claude Code hooks):
   • Automatic: Validates on every file edit (<2s)
   • Shows errors/warnings inline during AI sessions
   • Auto-formats code and provides contextual alerts
2. During Development:
   • Manual: pnpm ai:quick (run frequently, <5s)
   • Automatic: pnpm ai:watch (continuous validation on file save)
3. Before Commit: Pre-commit hooks (automatic, ~30s)
4. Before Push: Pre-push validation (mandatory, matches CI exactly)

You CANNOT push code that will fail CI - multiple layers ensure quality.

Development validation pipeline:

# Manual validation
pnpm ai:quick          # Fast feedback during coding (~5s): lint + type-check (Nx cached)
pnpm ai:check          # Standard validation (~30s): + graph validation
pnpm ai:compliance     # Full validation (~3min): + tests + build + mutation testing + security
pnpm ai:mutation       # Run mutation testing directly (focused on business logic)

# Test configuration validation (CRITICAL)
pnpm test:config:verify    # Full validation: property comparison + test execution
pnpm test:config:quick     # Fast validation for pre-push hooks

# Continuous validation (runs on file save)
pnpm ai:watch          # Watch all files, run ai:quick on changes
pnpm dev:watch         # Watch all files, run affected lint+type-check

# Nx affected commands - only run on changed packages
pnpm affected:lint     # Lint only changed packages
pnpm affected:test     # Test only changed packages
pnpm affected:build    # Build only changed packages
pnpm affected:all      # Run all tasks on changed packages

Fix issues immediately:

pnpm lint:fix          # Auto-fix formatting and linting

Key Rule: The pre-push hook automatically runs pnpm ci:check - you literally cannot push failing code.

Quick Start Essentials