Code Quality Principles

Code Quality Principles

Use this skill to keep every code modification simple, maintainable, readable, and sustainable. Evaluate every feature, refactor, bug fix, and review through YAGNI, DRY, and KISS before changing code.

These principles take precedence over premature optimization, speculative architecture, and unnecessary cleverness.

Required Workflow

Before writing or reviewing code:

1. Identify the exact current requirement.
2. Check YAGNI: remove anything not required for that requirement.
3. Check DRY: consolidate duplicated knowledge, not merely repeated lines.
4. Check KISS: choose the simplest correct design with the fewest moving parts.
5. Respect the existing architecture unless the user explicitly requests a redesign.
6. Keep edits scoped to the current task.

If a proposed addition would not change the requested behavior when removed, do not implement it.

YAGNI

Only implement what is required to solve the current problem.

Do not:

• Implement features for future use.
• Create abstractions without at least two or three concrete current use cases.
• Add extension points, plugin systems, interfaces, or generic layers unless they solve an existing requirement.
• Introduce speculative architecture.
• Add unnecessary configuration.
• Add unused parameters.
• Add placeholder implementations.
• Add empty classes or methods intended for future development.
• Add feature flags for functionality that does not yet exist.
• Create utilities before there is demonstrated need.

Ask before coding:

• Is this required today?
• Does the current task explicitly require this?
• Will removing this code change the requested functionality?

If the answer is no, do not implement it.

DRY

Keep each piece of business knowledge in one authoritative place.

Eliminate duplicated:

• Business logic.
• Validation.
• Calculations.
• Constants.
• Configuration.
• Algorithms.
• Repeated SQL, API logic, conditionals, regexes, and error handling when they encode the same business rule.

Exception: do not create abstractions merely to remove a few repeated lines. Small, localized duplication is preferable to unnecessary complexity. Prefer duplication over a poor abstraction.

KISS

Prefer the simplest correct solution.

Prefer:

• Simple functions.
• Small modules.
• Explicit logic.
• Readable names.
• Predictable control flow.
• Low cognitive complexity.
• Clear data flow.

Avoid:

• Clever code.
• Deep inheritance.
• Over-engineering.
• Excessive design patterns.
• Deeply nested conditionals.
• Excessive indirection.
• Unnecessary metaprogramming.
• Unnecessary generics.
• Overly generic implementations.

Optimize for readability before cleverness.

Implementation Checklist

Before writing code, evaluate necessity:

• Is every new file necessary?
• Is every new dependency necessary?
• Is every new abstraction necessary?
• Is every new configuration necessary?
• Is every new interface necessary?

If not, remove it.

Search for true duplication:

• Repeated functions.
• Repeated validation.
• Repeated SQL.
• Repeated API calls.
• Repeated business rules.
• Repeated regexes.
• Repeated constants.
• Repeated error handling.

If true duplication exists, consolidate it appropriately without introducing a heavier abstraction than the duplication warrants.

Choose the implementation with:

• Fewer moving parts.
• Fewer dependencies.
• Fewer files.
• Fewer abstractions.
• Lower cognitive complexity.
• Easier debugging.
• Easier testing.

Refactoring Guidelines

When refactoring, improve readability, naming, cohesion, separation of concerns, maintainability, and consistency.

Avoid:

• Changing architecture unnecessarily.
• Introducing new frameworks.
• Changing public APIs without reason.
• Rewriting working code for stylistic preference alone.
• Refactoring unrelated parts of the project while working on the current task.

Architecture Awareness

Respect the existing architecture. Improve the current codebase; do not redesign it unless explicitly requested.

Avoid introducing new architectural patterns, dependency injection frameworks, state management systems, design patterns, build systems, or libraries unless the current requirement justifies them.

Code Review Rules

During review, identify YAGNI violations:

• Unused methods, classes, interfaces, dependencies, speculative code, unjustified future-proofing, dead code, and unreachable code.

Identify DRY violations:

• Duplicated business rules, validation, SQL, API logic, conditionals, and constants.

Identify KISS violations:

• Unnecessary abstractions, unnecessary polymorphism, deeply nested logic, excessive callbacks, long functions, long classes, unclear naming, unnecessary indirection, and overly generic implementations.

Lead review responses with concrete findings. Include file and line references when available, and explain the simpler alternative.

Decision Hierarchy

When multiple solutions exist, prefer the one that:

1. Solves the current problem completely.
2. Introduces the fewest concepts.
3. Requires the least amount of code.
4. Is easiest to understand for a new developer.
5. Has the lowest maintenance cost.
6. Preserves the existing architecture.
7. Minimizes future complexity.

Forbidden Behaviors

Do not:

• Optimize code without evidence of a performance bottleneck.
• Create reusable systems without demonstrated reuse.
• Introduce new libraries to solve trivial problems.
• Replace stable code simply because another approach is more elegant.
• Refactor unrelated parts of the project while working on the current task.
• Increase architectural complexity without measurable benefits.

Expected Behavior

Every implementation should leave the codebase simpler or at least no more complex than before. Continuously question whether new code is truly necessary, whether existing logic can be reused responsibly, and whether the final solution is the simplest one that fully satisfies the current requirement without sacrificing readability or maintainability.