Clean Code

Principles, practices, and workflows for TypeScript developers.

Critical: Reference-First Approach

Always load and consult the reference files before applying any principle or making any recommendation. The references in this skill contain curated, authoritative knowledge from Robert C. Martin's books, adapted for TypeScript. When this skill is active:

1. Read references before responding - For any code quality or professional practice topic, load the relevant rules.md and examples.md files from references/ before giving advice or writing code. Do not rely on general knowledge alone.
2. Reference content overrides internal knowledge - If your general knowledge conflicts with what the reference files state, follow the reference files. They contain the specific rules, thresholds, and patterns this skill enforces.
3. Cite specific rules - When making recommendations, reference the specific rule (e.g., "per references/functions/rules.md Rule 1: Keep Functions Small, 2-5 lines ideal") so the user can trace the guidance back to its source.
4. Use examples from reference files - Prefer the bad/good code examples in references/[topic]/examples.md over generating your own. These examples are curated for TypeScript and demonstrate the exact patterns intended.
5. Follow workflows step-by-step - When executing a task (review, refactoring, TDD, etc.), load the corresponding workflow file and follow each step, loading the reference files each step points to.

Do not skip loading references. Even if you "know" Clean Code principles, the reference files contain specific TypeScript adaptations, thresholds, checklists, and smell catalogs that your general knowledge may not match exactly.

Quick Start

1. For a task: Check guidelines.md → find the right workflow → load it → follow each step (loading referenced files)
2. For reference: Load the specific rules.md and examples.md files relevant to your work → apply them
3. Follow the workflow: Step-by-step process for consistent results — always load the files each step references

Workflows

Step-by-step processes for common tasks:

| Workflow | When to Use | |----------|-------------| | workflows/code-review/workflow.md | Reviewing code for quality | | workflows/pr-review/workflow.md | Reviewing pull requests | | workflows/tdd.md | Test-driven development cycle | | workflows/refactoring/workflow.md | Safe refactoring with tests | | workflows/new-feature.md | Building new functionality | | workflows/bug-fix.md | Fixing bugs properly | | workflows/test-strategy.md | Planning test coverage | | workflows/estimation.md | Estimating tasks (PERT) | | workflows/deadline-negotiation.md | Handling unrealistic deadlines |

Step-File Architecture (Code Review, PR Review, Refactoring)

The code review, PR review, and refactoring workflows use a step-file architecture for context-safe execution:

• Each workflow has a workflow.md entry point that describes steps and loads steps/step-01-init.md
• Each step is a separate file in steps/, loaded sequentially
• Progress is tracked via stepsCompleted array in the output document's YAML frontmatter
• If context is compacted mid-workflow, step-01-init.md detects the existing output and step-01b-continue.md resumes from the last completed step
• Each step loads specific reference files before analysis and cites rules in findings
• The refactoring workflow includes a loop (steps 4-7) for iterative change-test-commit cycles

Reference Categories

Part 1: Code Quality (Clean Code book)

| Category | Files | Purpose | |----------|-------|---------| | naming | 3 | Variable, function, class naming | | functions | 4 | Function design and review | | classes | 3 | Class/module design | | comments | 3 | Comment best practices | | error-handling | 3 | Exception handling | | unit-tests | 3 | Clean test principles | | formatting | 3 | Code layout | | smells | 3 | Code smell catalog (50+) |

Part 2: Professional Practices (Clean Coder book)

| Category | Files | Purpose | |----------|-------|---------| | professionalism | 3 | Professional ethics | | saying-no | 3 | Declining requests | | commitment | 3 | Making promises | | coding-practices | 3 | Daily habits, flow, debugging | | tdd | 3 | TDD workflow and benefits | | practicing | 3 | Deliberate practice | | acceptance-testing | 3 | Requirements as tests | | testing-strategies | 3 | Test pyramid | | time-management | 3 | Meetings, focus | | estimation | 3 | PERT estimation | | pressure | 3 | Working under pressure | | collaboration | 3 | Working with teams |

Key Principles (Summary Only — Always Load Full References)

These are abbreviated reminders. Always load the corresponding reference files for the full rules, thresholds, and examples before applying.

Code Quality

1. Readability → references/formatting/rules.md, references/naming/rules.md
2. Single Responsibility → references/classes/rules.md, references/functions/rules.md
3. Small Units → references/functions/rules.md (Rule 1: 2-5 lines ideal)
4. Meaningful Names → references/naming/rules.md
5. DRY → references/smells/rules.md (G5)
6. Clean Tests → references/unit-tests/rules.md

Professional Practices

1. Take Responsibility → references/professionalism/rules.md
2. Say No → references/saying-no/rules.md
3. Commit Clearly → references/commitment/rules.md
4. Estimates != Commitments → references/estimation/rules.md
5. Stay Clean Under Pressure → references/pressure/rules.md

Guidelines

See guidelines.md for:

• Task → workflow mapping
• Situation → reference file mapping
• Decision tree for common scenarios

Reference Loading Checklist

Before giving any code advice or writing code, verify:

• [ ] Identified which reference categories apply to the current task
• [ ] Loaded the rules.md for each applicable category
• [ ] Loaded examples.md if demonstrating patterns or reviewing code
• [ ] Loaded the relevant workflow/*.md if executing a multi-step task
• [ ] Will cite specific rules/files in recommendations