dev-skills

Appearance

Namecode-design
DescriptionCode design principles that need human judgment, not lint: intention-revealing names, abstraction levels, where new code belongs. Automatically invoke when naming, adding to, or restructuring code.

Code Design ​

Design-quality rules for code that needs human judgment to apply, not a linter to enforce.

How this differs from code-style ​

Code Style covers mechanical rules: indentation, line length, single quotes, trailing commas, no-var. Every rule there has a corresponding AST or line check in code-style/lint/. The workflow is "run the linter, fix one problem, repeat."

code-design covers judgment rules: naming, abstraction levels, function decomposition, where to draw module boundaries, where new code goes. No linter catches processData vs sumPositiveAmounts, or "this body mixes altitudes." A human has to read the code and decide whether it reads as prose or as syntax.

The two skills are complementary, not overlapping: code-style answers "is this formatted correctly?", code-design answers "is this written well?"

Topics ​

  • Code Placement: Put new code where it belongs, next to its relatives and inside the structure it extends, not at the bottom of the file or in a bolted-on special case. Use when adding code to an existing file.
  • Intention-Revealing Code: Names that reveal intent at the call site and contents that reveal intent at the read site, so code reads as prose, not syntax. Use when naming or restructuring functions, or reviewing low-level code.

See also ​

  • Code Style: Mechanical, lint-enforced formatting rules. Sibling skill; apply both.
  • Refactoring: The verified-steps method to apply when restructuring code toward better design.
  • Writing: The same "reveal intent, not mechanism" principle applied to prose, and the rule for integrating new information instead of appending it.