Code Quality Standards

What It Does

Production-grade code quality standards for AI coding agents, with universal principles applicable across 19 languages and TypeScript-first depth where agent mistakes are most common. Every change your agent makes is held to the same bar a senior engineer would set — no hacks, no scope creep, no silent failures.

Core Standards

No Hacks — Absolute
If the only path forward is a workaround, the skill stops and explains why, describes the proper fix, and records the debt as a // TECH DEBT: comment or ticket — not buried in a commit message.

4-Level Priority System

1. No Hacks (absolute)
2. Agent Behaviour Rules — no scope creep, flag fragility after every change
3. Correctness tiebreaker — runtime errors in touched code are always in scope
4. Core Values — Correctness > Clarity > Maintainability > Doing it right

Universal Principles
Constants over magic numbers, meaningful names, smart comments, SRP, DRY, encapsulation, tests that encode intent (not snapshots), and conformance to existing style.

Language Coverage

Python · TypeScript · Go · Rust · Java · Kotlin · C# · Swift · C/C++ · PHP · Ruby · Dart · Haskell · Scala · Elixir · R · Julia · Lua · Shell · SQL · Terraform · Bicep · CloudFormation

Key Features

• Language-agnostic pitfalls with worked code examples (dead code after early returns, O(n²) loop guards, validator narrower than the type, nondeterministic sync)
• TypeScript-specific depth: != null vs !== null for optional fields, literal union validators, JSDoc requirements for every public export, V8 coverage gap patterns
• Multi-stack security checklist: npm audit, pip-audit, cargo audit, govulncheck, semgrep, gitleaks — with explicit failure vs. vulnerability distinction
• Merge unblock criteria: upgrade + clean scan, or written false-positive documentation — verbal acknowledgment insufficient
• Commit message format: Conventional Commits with tie-breaker priority order when types overlap
• Throwaway-script mode: clear Yes/No table for which sections apply when the user explicitly scopes code as non-production

Reference Files Included

• clean-code.md — universal principles with examples
• language-specific-tools.md — per-language linters, audit tools, doc formats, test runners + SQL and IaC tooling
• security-checklist.md — expanded review checklist
• coverage-gaps.md — TypeScript/c8/V8 false negative patterns with fixes
• karpathy-guidelines.md — 10 anti-LLM-pitfall guidelines

When It Triggers

Writing new features · code review before merging · refactoring · debugging · auditing a codebase — even if you don't explicitly ask for a "code review".

Documentation workflow

• Context7: use proactively for third-party library/API documentation, setup flows, configuration details, and code-generation grounding when it is available.
• Astro Docs MCP: if the task is Astro-specific, use it first for Astro APIs, imports, integrations, configuration, and version-specific behavior when it is available.
• Official live web sources via search/fetch: still use these for freshness-sensitive public facts such as latest versions, release dates, migration notes, deprecations, current package status, and recently changed documentation.
• Fallback order: MCP docs first for structured reference; official live web sources via search/fetch second for freshness; the repo’s local docs, code, and tests for project-specific behavior.