This skill should be used when the user asks to "write clean code", "apply clean code principles", "follow SOLID principles", "apply GRASP patterns", "improve code quality", "naming conventions", "single responsibility", "DRY", "coupling", "cohesion", "readable code", "maintainable code", "separation of concerns", "dependency injection", or mentions clean code, design principles, or code quality. Also trigger during implementation tasks when quality matters — not only when explicitly asked. Also loaded by the /atdd and /refactor commands.
From devnpx claudepluginhub jordyvanvorselen/claude-marketplace --plugin devThis skill uses the workspace's default tool permissions.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Guides idea refinement into designs: explores context, asks questions one-by-one, proposes approaches, presents sections for approval, writes/review specs before coding.
Apply SOLID, GRASP, and other design principles as you write code. Your primary goal is to produce code that humans can understand and modify with confidence.
Write code for humans first, computers second. Every piece of code you write will be read many more times than it is written. Optimise for clarity and simplicity above all else.
Functions should be small. Aim for 5-15 lines as a guideline, but focus on doing exactly one thing well. If you can meaningfully name what a function does without using "and" or "or", it's probably the right size.
Modules should be small. Each module should have a clear, single responsibility. If you struggle to describe what a module does in one sentence, it's too big.
Classes should be small. Measure by responsibilities, not lines. A class with many methods but one clear purpose is better than a small class doing multiple things.
Names should reveal intent. A reader should understand what a variable holds, what a function does, or what a class represents just from its name.
Avoid abbreviations unless they're universally understood in the domain. customerRepository beats custRepo.
Use verbs for functions that perform actions, nouns for classes and modules, and descriptive names for variables that indicate their content and purpose.
Functions should do one thing, do it well, and do it only. If a function does multiple things, extract them into separate functions.
Functions should operate at a single level of abstraction. Don't mix high-level policy with low-level detail in the same function.
Prefer fewer arguments. Zero is ideal, one or two is common, three should be rare. If you need more, consider whether the arguments should be grouped into a concept of their own.
Avoid side effects. A function named checkPassword should not also initialise a session. If side effects are necessary, make them explicit in the name.
Prefer pure functions where possible. Given the same inputs, they return the same outputs and change nothing outside themselves.
Prefer exceptions over error codes. Exceptions separate the happy path from error handling, making both clearer.
Don't return null. Return empty collections, optionals, or use the null object pattern instead.
Fail fast. Validate inputs early and reject invalid states immediately rather than propagating them through the system.
Write error messages for the humans who will read them. Include context about what went wrong and ideally what might fix it.
The best comment is code that doesn't need one. Before writing a comment, ask whether you could make the code itself clearer.
When comments are necessary, explain why, not what. The code shows what happens; comments should explain decisions and intent.
Keep comments close to the code they describe and maintain them alongside that code. Outdated comments are worse than no comments.
Single Responsibility Principle: A class or module should have one, and only one, reason to change. If you can think of multiple actors who might request changes to a piece of code, it has multiple responsibilities.
Open/Closed Principle: Code should be open for extension but closed for modification. Design systems that can gain new behaviour by adding new code, not changing existing code.
Liskov Substitution Principle: Subtypes must be substitutable for their base types. If code works with a base class, it should work correctly with any derived class without knowing the difference.
Interface Segregation Principle: Clients should not be forced to depend on methods they don't use. Prefer many small, specific interfaces over one large general-purpose interface.
Dependency Inversion Principle: High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details; details should depend on abstractions.
Information Expert: Assign responsibility to the class that has the information needed to fulfil it.
Creator: Assign class B the responsibility to create instances of class A if B contains A, closely uses A, has the initialising data for A, or records instances of A.
Controller: Assign responsibility for handling system events to a class representing the overall system, a use case scenario, or something that represents the work being done.
Low Coupling: Assign responsibilities so that coupling remains low. Classes should have minimal dependencies on other classes.
High Cohesion: Assign responsibilities so that cohesion remains high. Keep related functionality together and unrelated functionality separate.
Polymorphism: When behaviour varies by type, assign responsibility for the behaviour to the types for which it varies, using polymorphic operations.
Pure Fabrication: When the information expert principle would result in poor cohesion or coupling, create an artificial class that doesn't represent a domain concept.
Indirection: Assign responsibility to an intermediate object to mediate between components to reduce direct coupling.
Protected Variations: Identify points of predicted variation and create a stable interface around them.
Separation of Concerns: Divide your program into distinct sections, each addressing a separate concern. Business logic should know nothing of the user interface. Data access should be independent of business rules.
Modularity: Structure your system as a collection of independent modules with well-defined interfaces. Each module should be understandable in isolation.
Composition Over Inheritance: Build complex behaviour by combining simple objects rather than inheriting from parent classes. Inheritance creates tight coupling and rigid hierarchies.
Law of Demeter: A method should only call methods on itself, its parameters, objects it creates, and its direct components. Don't reach through objects to talk to their parts.
Tell, Don't Ask: Instead of asking an object for data and acting on it, tell the object what to do. Let objects make their own decisions using their own data.
Command-Query Separation: Functions should either do something (command) or return something (query), but not both. Asking a question should not change the answer.
KISS (Keep It Simple, Stupid): The simplest solution that works is usually the best. Complexity is a cost that must be justified by proportional benefit.
YAGNI (You Aren't Gonna Need It): Don't add functionality until you need it. Predicted future requirements are often wrong, and unused code is a maintenance burden.
DRY (Don't Repeat Yourself): Every piece of knowledge should have a single, authoritative representation in your system. But be careful: not all similar-looking code is true duplication.
Principle of Least Astonishment: Code should behave the way its readers expect. If something looks like a getter, it should not have side effects. If something is named "save", it should save.
Immutability: Prefer data that cannot be changed after creation. Immutable data is easier to reason about, share safely between threads, and test.
Pure Functions: Strive for functions that depend only on their inputs and produce only their outputs. They have no side effects and always return the same result for the same inputs.
Referential Transparency: An expression should be replaceable with its value without changing the program's behaviour. This is a natural consequence of pure functions.
Function Composition: Build complex operations by combining simple functions. Small, focused functions become building blocks for larger behaviours.
Declarative Over Imperative: Where possible, describe what you want rather than how to achieve it. Prefer map, filter, and reduce over manual loops when they express intent more clearly.
Higher-Order Functions: Use functions that take functions as arguments or return functions. They enable powerful abstractions and code reuse.
Encapsulation: Hide internal details and expose only what's necessary. Objects should control access to their own state and reveal behaviour, not data.
Abstraction: Model essential features without including background details. Provide only the interface clients need, hiding complexity behind it.
Polymorphism: Allow objects of different types to be treated uniformly through a common interface. This enables extensibility without modifying existing code.
Information Hiding: The internal workings of a module should be private to that module. Other modules should interact through a public interface that can remain stable even when internals change.
Low Coupling: Minimise dependencies between modules. When one module changes, it should affect as few other modules as possible.
High Cohesion: Keep related code together. Everything in a module should relate to its central purpose.
Connascence: Understand the types and strengths of coupling. Prefer weaker forms (name connascence) over stronger forms (execution order connascence, value connascence).
Dependency Injection: Pass dependencies into objects rather than having objects create or look up their own dependencies. This makes code more testable and flexible.
Inversion of Control: Rather than your code calling framework code, framework code calls your code. Don't call us, we'll call you.
Stable Dependencies Principle: Depend in the direction of stability. Modules that change frequently should depend on modules that change rarely.
Stable Abstractions Principle: Abstractions should be stable. The more stable a module, the more abstract it should be.
Postel's Law (Robustness Principle): Be conservative in what you send, be liberal in what you accept. But be careful not to silently accept invalid data.
Fail Fast: When something goes wrong, fail immediately and clearly rather than propagating errors through the system.
Defensive Programming: Don't trust inputs from outside your module. Validate at boundaries and assume data might be malformed or malicious.
Principle of Least Privilege: Code should have only the permissions it needs to do its job, no more.
Write code that reads like well-written prose. A function should tell a story that's easy to follow.
Use whitespace deliberately. Group related statements and separate unrelated ones.
Keep the flow linear where possible. Avoid deep nesting by returning early, using guard clauses, or extracting nested logic into separate functions.
Design for testability from the start. Code that's hard to test is usually too coupled or doing too much.
Every public function should be testable in isolation. If it requires elaborate setup, consider whether it's doing too much or has hidden dependencies.
Side effects should be pushed to the edges of the system. Business logic should be pure and easy to test without mocking.
Boy Scout Rule: Leave the code better than you found it. Each time you touch code, improve it a little.
Optimise for reading over writing. Code is read far more often than it's written, so invest in clarity.
Make changes easy by making them small. If a change requires touching many files, consider whether the design could better localise changes.
Before writing, understand the problem fully. Clarify requirements and edge cases before implementing.
Start with the smallest possible working solution. Add complexity only when you have evidence it's needed.
Refactor continuously. As understanding grows, let the code evolve to reflect that understanding.
When you find yourself repeating code, ask whether you have a concept that deserves a name. The duplication might be revealing a missing abstraction.
When a function grows beyond a comfortable size, look for paragraphs within it. Each paragraph probably deserves to be its own function.
When a class grows responsibilities, look for clusters of methods that work together. They might be a separate class waiting to emerge.
When faced with a complex condition, extract it into a well-named function or variable that explains what you're checking for.
Write small, focused modules. Write small, focused classes. Write small, focused functions. Each should do one thing well and have a clear name that says what it does.
Separate concerns ruthlessly. Keep coupling low and cohesion high. Depend on abstractions, not details. Prefer composition to inheritance.
Make your code easy to read, easy to change, and easy to test. When in doubt, choose the simpler solution.
Remember: code is communication. Write code that your future self and your colleagues will thank you for.