# Code Quality

> Concise code-quality rules for implementation and review across the stack.

- Skill: `abivan-tech/code-quality` (Agent Skill)
- Install (CLI): `npx skillmds@latest add abivan-tech/code-quality`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abivan-tech/code-quality/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: See repository LICENSE
- Author: ABIvan-Tech (https://skillmd.com/u/abivan-tech)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/abivan-tech/code-quality

---


# Code Quality & Clean Code

Use this skill for implementation, refactoring, and review when you need practical guidance rather than a textbook.

## Priorities

Apply these in order:

1. **Correctness**
2. **Simplicity**
3. **Consistency with the repo**
4. **Operability** (errors, logs, debuggability)
5. **Performance where it matters**

Do not trade correctness for cleverness.

## Core Rules

### 1. Prefer the smallest safe change

- Fix the root cause, not just the symptom.
- Change only the files and behaviors needed for the task.
- Avoid opportunistic refactors unless they directly reduce risk for the task at hand.

### 2. Reuse existing patterns

- Match the repository's naming, file layout, error-handling style, and testing approach.
- Prefer extending an existing abstraction over inventing a new one.
- If the repo already has two patterns for the same concern, follow the more local one unless there is a strong reason not to.

### 3. Keep control flow obvious

- Prefer flat, readable code over indirection.
- Avoid deep nesting when early returns or small helpers make the path clearer.
- Make state transitions explicit.
- Do not hide business-critical work inside callbacks, decorators, magic hooks, or convenience wrappers unless the repo already standardizes on them.

### 4. One unit, one reason to change

- Functions should do one coherent job.
- Modules should have clear ownership boundaries.
- If one function validates input, writes data, sends notifications, and updates analytics, split the responsibilities unless the repo strongly prefers orchestration in one place.

### 5. Make invalid states hard to represent

- Encode invariants in types, schemas, guards, or data structures when practical.
- Prefer explicit state models over loosely coupled booleans or nullable piles.
- Validate external input at boundaries.

### 6. Be explicit about failures

- Never silently swallow errors.
- Add context when rethrowing or converting errors.
- Use structured logs at meaningful boundaries.
- Return or throw domain-appropriate errors; avoid generic `"something went wrong"` style messages inside the code path.

### 7. Keep comments rare and valuable

- Prefer self-explanatory code first.
- Comment only for invariants, non-obvious tradeoffs, protocol details, or external constraints.
- Remove stale TODO-style comments instead of adding new vague ones.

### 8. Keep configuration boring

- Prefer explicit config over hidden defaults.
- Centralize cross-cutting configuration when the repo already has a convention for it.
- Name feature flags, environment variables, and constants clearly.

## Refactoring Rules

Refactor only when at least one is true:

1. it removes duplication that would otherwise make the current task risky
2. it clarifies ownership or control flow required for the current task
3. it reduces the chance of regression in a touched code path

Do not refactor just because the code can be made "cleaner."

## Review Heuristics

When reviewing or self-checking code, look for:

### Correctness

- missing edge-case handling
- partial success / partial failure paths
- race conditions or ordering assumptions
- broken invariants after updates
- unsafe defaults or silent fallbacks

### Maintainability

- duplicated logic in nearby files
- helpers that hide too much
- misleading names
- functions that mix domain logic and transport/UI concerns
- abstractions that save little but cost a lot

### Safety

- unvalidated external input
- privilege or authorization gaps
- unsafe retries / repeated side effects
- logging of secrets or sensitive data
- lack of timeout / cancellation / cleanup at important boundaries

### Testing

- missing tests for changed behavior
- tests coupled to implementation details instead of behavior
- missing regression coverage for the exact bug or risk being addressed

## Good Defaults by Task Type

### New feature

- add the smallest extension point that fits the existing architecture
- keep the happy path clear
- add validation and test coverage around new behavior

### Bug fix

- reproduce first when possible
- patch the narrowest root cause
- add or update a regression test if the repo has tests

### Refactor

- preserve behavior
- keep changes reviewable
- validate key paths after each structural step

### Review

- prioritize correctness, regressions, and security over style
- do not request abstraction for abstraction's sake

## Anti-Patterns

Avoid these unless the repo explicitly depends on them:

- speculative abstractions
- giant utility modules
- boolean flag state machines with unclear ownership
- catching broad errors and returning defaults silently
- "smart" helper layers that obscure I/O or state changes
- comments that restate the code
- large rewrites when a surgical fix is enough

## Quick Checklist

- [ ] The change follows local repo patterns
- [ ] Ownership and control flow are easy to follow
- [ ] External input is validated at the boundary
- [ ] Errors are explicit and contextual
- [ ] The change is no larger than necessary
- [ ] Tests or verification steps match the real risk
- [ ] No unnecessary abstraction was introduced