shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringAPI key requirement unconfirmed

typescript-clean-code

Clean Code principles, professional practices, and workflows for TypeScript developers. Based on Robert C. Martin's "Clean Code" and "The Clean Coder" books. IMPORTANT: When this skill is active, always load and consult the reference files (rules.md, examples.md) before giving advice or writing code. Reference content takes precedence over general knowledge. Use this skill when: - Writing TypeScript/JavaScript code - Reviewing code or pull requests - Refactoring existing code - Following test-driven development (TDD) - Fixing bugs with proper test coverage - Planning test strategy for features - Estimating tasks accurately - Handling deadlines and commitments professionally - Working effectively with teams

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

Clean Code

The twelve change-shape smells

Shotgun Surgery · Feature Envy · Data Clumps · Long Method · Divergent Change · Duplicated Code · Large Class · Long Parameter List · Primitive Obsession · Message Chains · Dead Code · Speculative Generality

You know each one and its refactoring. The value is the checklist, not the definitions — without the names a diff "looks fine"; with them you find the shape. Run all twelve against any change you review or write.

The smell catalog has four layers

Each examines a different unit, so each sees what the others miss.

| Load | Unit | For | |------|------|-----| | references/smells/tooling.md | the repository | First, in every review. Which smells a linter decides, so those become one "wire this into CI" finding instead of twenty hand-written ones | | references/smells/rules.md | a line, a function | Per-line heuristics (C/E/F/G/N/T), plus the review posture and severity vocabulary that govern all four layers | | references/smells/fowler.md | a modification | The twelve above — detection question, TypeScript remedy, and when NOT to fix for each | | references/smells/typescript.md | a type | TS1-TS10: any leakage, assertion versus validation, exhaustiveness, strictness flags, branded types |

A diff can satisfy every rule in rules.md and still be badly shaped — that is what fowler.md is for. Reviewing a change means all four.

Review posture

Three rules that change output more than any catalog entry. Full text in references/smells/rules.md → "Review posture".

  1. Approve when the change improves code health, not when it is perfect. There is no perfect code, only better code.
  2. A correct finding nobody acts on is a false positive. Scan broadly, report selectively — three actionable findings beat twenty true ones.
  3. Mark polish as ignorable. Conventional Comments labels — issue, suggestion, nitpick, question, praise — with (blocking) / (non-blocking). An author who cannot tell which comments are optional treats all of them as mandatory, or none of them.

A review is done when all four layers have run, every surviving finding carries a label and (for an issue) a fix, and the report states how many findings were cut as unlikely to be acted on.

Contested rules

Three rules in these references are positions with live counter-arguments, marked contested where they appear. Present both sides and prefer the author's demonstrated reasoning over the number:

  • Function length — references/functions/rules.md Rule 1. Detect by "can I name each section?"; the "2-5 lines" figure over-extracts when applied literally.
  • Comments — references/comments/rules.md. Keep rationale, invariants, and non-obvious why; delete restatement and stale comments.
  • G23 polymorphism — references/smells/rules.md. An exhaustive switch over a discriminated union is idiomatic TypeScript, not a smell.

Workflows

Load the workflow.md, then its step files in order. Each step names the references it needs and updates stepsCompleted in the output document's frontmatter, so a compacted context resumes from the last completed step via step-01b-continue.md.

| Workflow | For | |----------|-----| | workflows/code-review/workflow.md | Reviewing code for quality | | workflows/pr-review/workflow.md | Reviewing pull requests | | workflows/refactoring/workflow.md | Safe refactoring with tests (step 3 sweeps all twelve; steps 5-8 loop) | | workflows/tdd.md | Test-driven development cycle | | 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 |

References

references/<topic>/ holds rules.md (the rules), examples.md (curated TypeScript bad/good pairs — prefer these over inventing your own), and knowledge.md (concepts).

Code quality: naming · functions · classes · comments · error-handling · unit-tests · formatting · smells

Professional practice: professionalism · saying-no · commitment · coding-practices · tdd · practicing · acceptance-testing · testing-strategies · time-management · estimation · pressure · collaboration

Load the topic's rules.md before advising on it, and cite the rule you applied — the design problem it names, not the metric that pointed at it. Where a reference contradicts your general knowledge, the reference wins: it carries this skill's TypeScript adaptations and thresholds.

guidelines.md maps symptom → reference file and task → workflow.