# Clean Code Standards > Core principles and standards for clean code enforcement. Auto-invoked when reviewing code quality, discussing best practices, or planning refactoring work. Use when this capability is needed. - Skill: `tomevault-io/clean-code-standards` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/clean-code-standards` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/clean-code-standards/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/clean-code-standards --- # Clean Code Standards This skill provides the foundational principles enforced by the Church of Clean Code purist agents. ## The Ten Pillars of Clean Code ### 1. Type Safety - No `any` types - use `unknown` with guards - No type assertions (`as`) - use runtime validation - Exhaustive switch statements with `never` checks - Branded types for domain safety ### 2. Git Hygiene - Conventional Commits format required - Atomic commits (one logical change per commit) - No WIP commits on main branches - Clean worktree at session end ### 3. Architecture Boundaries - Domain layer depends on NOTHING - Dependencies flow downward only - No circular dependencies - Repository interfaces in domain, implementations in infrastructure ### 4. Test Coverage - Domain: 90% coverage minimum - Application: 80% coverage minimum - All entities require property tests (fast-check) - No weak assertions (toBeTruthy without context) ### 5. Dead Code Elimination - Zero unused exports - Zero orphaned files - No commented-out code (git remembers) - TODOs older than 3 months must be actioned or deleted ### 6. Naming Clarity - File format: `[name].[component-type].ts` - Booleans: `is/has/should/can/will/did` prefixes - No generic names: `data`, `result`, `temp`, `info` - Collections plural, items singular ### 7. Size Limits - Components: max 350 lines (critical at 500) - Functions: max 40 lines (suspicious), 80 lines (condemned) - Nesting: max 4 levels - No god classes ### 8. Secret Security - Zero secrets in code or git history - Environment variables for all credentials - .gitignore must cover all secret patterns - Rotation required if ever committed ### 9. Dependency Health - Zero known vulnerabilities - No packages >2 major versions behind - No unused dependencies - devDependencies vs dependencies properly separated ### 10. Observability - No empty catch blocks - Structured logging with correlation IDs - All endpoints traced - Health checks for all dependencies ### 11. Accessibility (Universal Readability) - All images have alt text (descriptive or null) - Text contrast: 4.5:1 minimum (3:1 for large text) - No information conveyed by color alone - All interactive elements keyboard accessible - Focus indicators visible (3:1 contrast) - ARIA used correctly (or native HTML preferred) - No keyboard traps ### 12. High-Converting Copy - No "Submit" buttons without context - use specific action verbs - No no-reply email addresses - use monitored addresses - Hero headlines must state a clear benefit - Features must connect to benefits (FAB framework) - Landing pages must follow AIDA/PAS/4Ps structure - SMS messages must be under 160 characters - Error messages must include next steps ### 13. Adaptive UI - No hardcoded `100vw`/`100vh` -- use `%`, `dvh`, container queries - Foldable hinge awareness via viewport segment APIs - Canonical layouts (List-Detail, Feed, Supporting Pane) for wide screens - State preservation across resize, fold, rotate (forms, scroll, navigation) - Focus-visible styles on all interactive elements, no `outline: none` - All images have `srcset` for multi-DPI support, icons are SVG - Touch targets minimum 44x44 CSS pixels - No hover-only interactions -- touch/keyboard alternatives required - Drag-and-drop has visual feedback and keyboard alternative ## When to Invoke Crusades | Situation | Recommended Crusade | |-----------|---------------------| | Before PR merge | `/church:type-crusade`, `/church:test-crusade` | | Architecture review | `/church:arch-crusade` | | Security audit | `/church:secret-crusade --history` | | Dependency update | `/church:dep-crusade` | | Codebase cleanup | `/church:dead-crusade`, `/church:size-crusade` | | New team onboarding | `/church:naming-crusade` | | Production incident | `/church:observability-crusade --illuminate` | | Accessibility compliance | `/church:a11y-crusade` | | WCAG 2.2 audit | `/church:a11y-crusade --write` | | Low conversion rates | `/church:copy-crusade` | | Email deliverability issues | `/church:copy-crusade --scope email` | | Landing page optimization | `/church:copy-crusade --scope landing` | | Foldable/responsive UI audit | `/church:adaptive-crusade` | | Touch target compliance | `/church:adaptive-crusade --concern touch` | | Focus/keyboard accessibility | `/church:adaptive-crusade --concern focus` | --- > Source: [btachinardi/church](https://github.com/btachinardi/church) — distributed by [TomeVault](https://tomevault.io).