Code Quality Rubric
Relevant source files
The following files were used as context for generating this wiki page:
The Code Quality Rubric defines seven fundamental principles for evaluating code changes within the project. It provides a compact framework for reviewing diffs, challenging implementation decisions, and advising on code quality without addressing unrelated legacy debt.
The rubric integrates into the Production Code and Code Review workflows. While this rubric defines the principles, the production-code skill extends them into implementation procedures, and the CLAUDE.md file maintains the project's hard invariants.
Sources: skills/code-quality/SKILL.md:1-12, skills/production-code/SKILL.md:9-10
The Seven Quality Principles
The rubric focuses on the changed surface of a diff. Reviewers cite concrete proof, contracts, and the diff itself when applying these principles.
1. Minimal Code
This principle ensures changes are as small as possible while remaining correct. You must remove code that is made obsolete by the change. Avoid creating speculative options, one-off wrappers, or pass-through modules.
2. No Duplicated Behavior
Each behavior must be implemented exactly once. You should reuse or extend existing owners of equivalent behavior. Consolidation is only valid if the behavior is genuinely shared rather than just similar.
3. Direct Data and Control Flow
State transitions, I/O, and control flow must be explicit and traceable. Avoid adding unnecessary orchestration, retries, transforms, or hops. Input validation occurs once at the trust boundary.
4. No Fake-Green Escape
Every proof must satisfy the project's canonical mock ban. You must not suppress, swallow, or bypass failures. Correct failures at their source instead of muting them.
5. Cleanup Discipline
Remove all temporary artifacts, dead code created by the change, leaked state, and obsolete branches. Cleanup must be deterministic. Interfaces must prove success, failure, and interruption paths for cleanup or atomicity.
6. Consequence Coverage
Trace the effects of changes on callers, callees, adjacent consumers, and persisted contracts. Stateful edits require proof across the entire combined behavior surface. Coupled updates must be included in the same change.
7. Simple Implementation
The code must be direct and readable. Limit comments to non-obvious decisions and contracts. Use high-signal workflow checks and sharp invariant checks for proof. Use authorities that own semantic rules instead of regexes or syntax parsing.
Sources: skills/code-quality/SKILL.md:14-55
Implementation and Review Workflow
The rubric serves as the basis for both implementing production code and conducting formal reviews.
The diagram shows how the quality principles are applied throughout the lifecycle of a code change, from preflight to the final quality gate and review.
Sources: skills/repo-production-workflow/SKILL.md:38-55, skills/production-code/SKILL.md:21-25
Review Output Structure
When reporting findings, you must categorize them by principle and severity. Each finding includes the location, the violated contract, the smallest possible correction, and the required proof. If no findings exist, you must name any unavailable evidence surfaces.
Sources: skills/code-quality/SKILL.md:65-70
Language-Specific Checks
The rubric includes specific requirements for different programming languages:
| Language | Requirements |
|---|---|
| Python | Retain public-boundary types; validate external input at the boundary; report broad exception swallowing or unjustified type ignores. |
| TypeScript / JS | Narrow untrusted values; reject unsafe any; reject broad casts/suppressions; ensure exhaustive state handling fails closed. |
Sources: skills/code-quality/SKILL.md:57-63
Hard Invariants and Bans
The Code Quality Rubric is reinforced by hard invariants defined in the global project rules. These invariants take precedence and cannot be weakened by other skills.
Mock Ban
Tests and verification must cross the real production interface or seam. Mocks, stubs, fakes, or test-only adapters are not considered valid production proof. If a real seam cannot be driven, you must report a proof gap rather than using a substituted collaborator.
Imaginary-Risk Ban
Theoretical failure modes do not justify adding code, guards, retries, or abstractions. You must demonstrate a real occurrence or a verified mechanism before changing production behavior.
Root-Cause-First Gate
Do not begin a production fix for bugs or regressions until the symptom is reproduced and the source trigger is traced. The fix must target the source cause, not the visible symptom.
Sources: CLAUDE.md:27-49, skills/diagnose/SKILL.md:8-13
Integration with Production Code
The production-code skill extends these principles with specific implementation procedures. Before finalizing any change, you must run a non-mutating quality gate.
PYTHONDONTWRITEBYTECODE=1 python3 "$HOME/.claude/skills/production-code/scripts/code_quality_gate.py" check --repo "$PWD"
Sources: skills/production-code/SKILL.md:21-23
Minimum Implementation Decision
Before implementation, you must resolve ownership:
- Existing Behavior: Verify if the requirement is already provided by an existing interface.
- Responsible Owner: Choose the owner based on the
moduleShapedecision from preflight. - Reuse: Reuse capabilities from the standard library, native platform, or existing dependencies.
- Reduce Bloat: Delete duplication and consolidate owners before adding new code.
Sources: skills/production-code/SKILL.md:47-62
Summary
The Code Quality Rubric ensures that all changes to the codebase are minimal, direct, and verified. By adhering to the seven principles—Minimal Code, No Duplicated Behavior, Direct Flow, No Fake-Green Escape, Cleanup Discipline, Consequence Coverage, and Simple Implementation—the project maintains high standards of locality and leverage while preventing the accumulation of technical debt and speculative complexity.