Engineering Standards

Engineering Standards

Comprehensive standards for building production-grade applications with Claude Code, capturing proven patterns for hooks, testing, documentation, quality gates, and monorepo architecture.

When to Use This Skill

• Setting up a new project - Bootstrap with all best practices from day one
• Validating existing projects - Check compliance with standards
• Extracting patterns - Pull proven patterns from mature codebases
• Standardizing practices - Ensure consistency across multiple projects
• Onboarding team members - Reference for engineering expectations

Quick Reference

Validation & Compliance

# Check if project follows standards
python scripts/validate-compliance.py

# Generate detailed compliance report
python scripts/generate-report.py --format markdown --output report.md

# Quick validation
./scripts/check-standards.sh

Bootstrap New Project

# Create new project with all standards
python scripts/bootstrap-project.py \
  --project-name "My Project" \
  --project-type nextjs \
  --output-path ./new-project

# Bootstrap with framework
python scripts/bootstrap-project.py \
  --project-name "My App" \
  --project-type monorepo \
  --framework makerkit \
  --output-path ./my-app

Extract Patterns from Existing Project

# Sync patterns from mature codebase
python scripts/sync-from-project.py \
  --source-project /path/to/project \
  --extract all \
  --update-standards

# Extract specific categories
python scripts/sync-from-project.py \
  --source-project /path/to/project \
  --extract hooks,testing,patterns

Standards Categories

🎣 Hooks & Automation

HOOKS_GUIDE.md - Git hooks and Claude Code hooks

• Pre-commit hooks (<2s target): Format, WIP validation, migration idempotency, RLS validation
• Pre-push hooks (30-60s): Lint, typecheck, lockfile sync, DB validation
• Claude Code hooks: PreToolUse (forbidden patterns), PostToolUse (migration warnings)
• Lefthook configuration: Parallel execution, THOROUGH mode, skip patterns

Key patterns: Migration idempotency (IF NOT EXISTS), version suffix detection, root file blocking

🧪 Testing Standards

TESTING_GUIDE.md - Vitest, Playwright, and Flutter testing

• Vitest configuration: Separate TEST instance, 80% coverage threshold, jsdom environment
• Playwright patterns: Dual-client architecture for RLS testing, auth-based projects
• Flutter testing: Unit tests with Riverpod mocking, widget tests, golden tests
• Test organization: By feature, integration vs unit separation

Key patterns: Dual-client RLS validation, coverage gates, TEST instance isolation

📝 Documentation Standards

DOCUMENTATION_GUIDE.md - WIP files, guides, architecture docs

• Location-based classification: docs/wip/active/, docs/guides/, docs/architecture/
• WIP management: WIP_{gerund}_{YYYY_MM_DD}.md naming, 7-day staleness limit
• Forbidden patterns: Root .md files (except CLAUDE.md, README.md), "deferred" work
• Retention policies: Archive after completion, structured investigation docs

Key patterns: Temporary vs permanent docs, naming conventions, staleness validation

📖 CLAUDE.md Standards

CLAUDE_MD_GUIDE.md - Structure and best practices

• Required sections: Tech Stack, Project Structure, Essential Commands, Critical Rules
• Subdirectory pattern: Focused context per package (apps/web/CLAUDE.md, etc.)
• Integration: Use cortex-doc-standards for generation and validation
• Best practices: Concise, scannable, actionable content

Key patterns: Progressive disclosure, variable substitution, no duplicated context

✅ Quality Gates

QUALITY_GATES_GUIDE.md - Lint, typecheck, format, build

• Lint standards: ESLint rules, oxlint for fast checks, custom plugins (i18n, providers)
• Type checking: TypeScript strict mode, affected packages only
• Formatting: Prettier auto-fix on pre-commit
• Build validation: Production build must succeed before merge

Key patterns: Sequential quality command, caching strategies, parallel execution

🔀 Git Workflow

GIT_WORKFLOW_GUIDE.md - Branches, commits, PRs

• Branch strategy: Worktree-based for features (~/project-worktrees/)
• Branch naming: feat/, fix/, refactor/, docs/
• Commit format: Conventional commits with Claude co-author
• PR workflow: Templates, review requirements, merge strategies

Key patterns: Worktree isolation, co-authoring with Claude, no force push to main

🏗️ Monorepo Standards

MONOREPO_GUIDE.md - Turborepo, pnpm, workspaces

• Package structure: apps/ vs packages/, shared dependencies
• pnpm workspaces: Configuration, workspace protocol, version management
• Turborepo: Build caching, task pipelines, affected packages
• Type generation: Cross-package type references, syncpack for versions

Key patterns: Dependency-aware builds, lockfile discipline, affected optimizations

🔒 Security Standards

SECURITY_GUIDE.md - Secrets, RLS, auth, env vars

• Environment variables: .env.local, 1Password integration, Vercel gotcha (trailing newlines)
• RLS-first pattern: userClient + RLS by default, admin client only with validation
• Migration security: Idempotency validation, SQL injection prevention
• Auth wrappers: withAuth, withAuthParams, withSuperAdmin patterns

Key patterns: Never hardcode secrets, audit logging for admin operations

🎨 Architectural Patterns

PATTERNS_LIBRARY.md - Common architectural patterns

• Service layer: Result pattern (no exceptions), BaseService abstraction
• Server actions: withAuthParams integration, revalidation patterns
• Server vs Client components: When to use each, async params handling
• Data isolation: account_id vs client_id patterns
• N+1 prevention: Batch queries + in-memory aggregation

Key patterns: Result<T, E>, soft delete, RLS-first data access

Common Workflows

Workflow 1: Bootstrap New Project

# 1. Create project with standards
python scripts/bootstrap-project.py \
  --project-name "My New App" \
  --project-type nextjs \
  --output-path ./my-new-app

# 2. Review and customize
cd ./my-new-app
cat CLAUDE.md  # Review and customize project-specific details

# 3. Install dependencies
pnpm install

# 4. Verify setup
pnpm quality  # Should pass all gates

# 5. Start development
pnpm dev

Expected outcome: Fully functional project with hooks, tests, quality gates, and documentation structure.

Workflow 2: Validate Existing Project

# 1. Run validation from project root
python /path/to/engineering-standards/scripts/validate-compliance.py

# 2. Review findings
# Output shows: ✓ passed, ⚠ warnings, ✗ failures

# 3. Generate detailed report
python /path/to/engineering-standards/scripts/generate-report.py \
  --format markdown \
  --output compliance-report.md

# 4. Fix issues (example: version suffixes)
# If found: src/components/user-form-v2.tsx
# Rename to: src/components/user-form.tsx

# 5. Re-validate
python /path/to/engineering-standards/scripts/validate-compliance.py

Expected outcome: 95%+ compliance, clear action items for any gaps.

Workflow 3: Extract Patterns from Mature Project

# 1. Analyze source project
python scripts/sync-from-project.py \
  --source-project /path/to/mature-project \
  --extract all \
  --dry-run

# 2. Review extracted patterns
# Output: New patterns found (hooks, testing, architectural)

# 3. Update standards (with approval)
python scripts/sync-from-project.py \
  --source-project /path/to/mature-project \
  --extract all \
  --update-standards

# 4. Version bump
# Edit SKILL.md: version: "1.0.0" → "1.1.0"
# Update CHANGELOG.md with new patterns

# 5. Sync to other projects
# Use bootstrap or validate workflows in other projects

Expected outcome: Standards updated with proven patterns from production codebases.

Workflow 4: Set Up Project-Specific CLAUDE.md

# 1. Generate using cortex-doc-standards
npx cortex-doc-standards rules init --type nextjs --name "My Project"

# 2. Generate CLAUDE.md
npx cortex-doc-standards generate-claude

# 3. Customize with project-specific patterns
# Add: Tech Stack, Project Structure, Essential Commands

# 4. Validate structure
npx cortex-doc-standards validate --file CLAUDE.md

# 5. Add subdirectory CLAUDE.md files
# Create: apps/web/CLAUDE.md, packages/ui/CLAUDE.md
# Focus each on package-specific patterns

Expected outcome: Comprehensive CLAUDE.md with proper structure and project context.

Integration with cortex-doc-standards

This skill references the cortex-doc-standards package for CLAUDE.md generation and validation, rather than duplicating its logic:

Using cortex-doc-standards

# Install
npm install -D @akson/cortex-doc-standards

# Initialize configuration
npx cortex-doc-standards rules init \
  --type nextjs \
  --name "Project Name"

# Generate CLAUDE.md from rules
npx cortex-doc-standards generate-claude

# Validate existing CLAUDE.md
npx cortex-doc-standards validate --file CLAUDE.md

Integration Points

• Bootstrap script: Calls cortex-doc-standards generate-claude during setup
• Validation script: Uses cortex-doc-standards validate for CLAUDE.md checks
• CLAUDE_MD_GUIDE.md: Documents structure and best practices (not generation logic)

Benefits: Single source of truth for CLAUDE.md validation, focused scope separation.

Configuration

Standards behavior is configured in config/rules-config.json:

{
  "hooks": {
    "pre_commit_timeout_seconds": 2,
    "pre_push_timeout_seconds": 60,
    "require_idempotent_migrations": true
  },
  "testing": {
    "coverage_threshold": 80,
    "require_separate_test_instance": true
  },
  "documentation": {
    "wip_staleness_days": 7,
    "block_root_md_files": true
  },
  "quality": {
    "require_strict_typescript": true,
    "require_prettier": true
  },
  "security": {
    "require_rls_first": true,
    "require_env_example": true
  }
}

Project-specific variables are in config/project-variables.json:

{
  "project_name": "{{PROJECT_NAME}}",
  "project_type": "{{PROJECT_TYPE}}",
  "framework": "{{FRAMEWORK}}",
  "package_manager": "pnpm"
}

Validation Scripts

validate-compliance.py

Checks 30+ validations across 8 categories:

1. Hooks presence: lefthook.yml, .claude/settings.json
2. Documentation structure: CLAUDE.md, docs/ directories
3. Testing configuration: Vitest/Playwright configs, coverage thresholds
4. Quality gates: ESLint, TypeScript strict mode, Prettier
5. Git configuration: .gitignore, branch protections
6. Security: .env.local.example, no hardcoded secrets
7. Naming conventions: kebab-case, no version suffixes
8. Migration standards: IF NOT EXISTS, idempotency

Exit codes: 0=full compliance, 1=warnings, 2=critical failures

bootstrap-project.py

20+ setup steps:

• Create directory structure (apps/, packages/, docs/)
• Copy templates with variable substitution
• Generate configurations (package.json, tsconfig.json, .gitignore)
• Initialize git and install lefthook
• Generate cortex-doc-standards config
• Create placeholder documentation

Exit codes: 0=success, 1=error

sync-from-project.py

Pattern extraction workflow:

1. Analyze source project (hooks, testing, patterns)
2. Compare with current standards
3. Update standards with new patterns (with approval)
4. Generate change report with version bump recommendation

Exit codes: 0=success, 1=no changes, 2=error

generate-report.py

Compliance reporting with:

• Executive summary (compliance %, grade A-F)
• Category-by-category breakdown
• Detailed findings and recommendations
• Historical comparison (if previous reports exist)

Formats: Markdown, JSON, HTML

Success Criteria

A well-configured project following these standards should:

✅ Pre-commit hooks run in < 2 seconds (format, validation, idempotency checks) ✅ Pre-push hooks run in < 60 seconds (lint, typecheck, lockfile validation) ✅ Test coverage is ≥ 80% (branches, functions, lines, statements) ✅ Migrations are idempotent (all use IF NOT EXISTS / IF EXISTS patterns) ✅ No version suffixes (-v2, -new, -enhanced, -updated, -unified) ✅ Documentation follows structure (WIP files properly located, no root .md files) ✅ Quality gates pass (lint, typecheck, format, build succeed) ✅ Security practices followed (RLS-first, no hardcoded secrets, env example exists) ✅ CLAUDE.md is comprehensive (required sections, subdirectory files for packages) ✅ Git workflow is clean (conventional commits, co-authoring, no force push to main)

Troubleshooting

Version History

See CHANGELOG.md for detailed version history.

Current Version: 1.0.0 (2026-01-13)

Related Resources

Detailed Guides (Progressive Disclosure)

• HOOKS_GUIDE.md - Pre-commit, pre-push, Claude Code hooks
• TESTING_GUIDE.md - Vitest, Playwright, Flutter testing
• CLAUDE_MD_GUIDE.md - CLAUDE.md structure and best practices
• QUALITY_GATES_GUIDE.md - Lint, typecheck, format, build
• GIT_WORKFLOW_GUIDE.md - Branches, commits, PRs
• DOCUMENTATION_GUIDE.md - WIP files, guides, architecture
• MONOREPO_GUIDE.md - Turborepo, pnpm workspaces
• SECURITY_GUIDE.md - Secrets, RLS, auth, env vars
• PATTERNS_LIBRARY.md - Architectural patterns

External Tools

• cortex-doc-standards - CLAUDE.md validation
• Lefthook - Fast git hooks
• Turborepo - Monorepo build system
• Vitest - Testing framework
• Playwright - E2E testing

Related Skills

• ai-skill-manager - Manage and sync Claude Code skills
• database-migration-manager - Database migrations and RLS
• flutter-development - Flutter mobile app patterns
• cicd-pipeline - GitHub Actions and deployment

Last Updated: 2026-01-13 Version: 1.0.0 Maintainer: Engineering Team