clean-code
Skill0 starsChanged 4 days agoMITView on GitHub
Clean Code a nivel de función y archivo: nombres, funciones pequeñas, manejo de errores, comentarios y catálogo de code smells → refactor, con detector heurístico. Úsala al limpiar, refactorizar o revisar la legibilidad de código frontend o backend, o al escribir código nuevo que deba quedar mantenible.
123 other projects use a version of this.
Adopted by
Most recently taken up by
- AtilaMedeiros/skillstheir own version, first seen Nov 16, 2026
- Ayobami6/skillstheir own version, first seen Nov 16, 2026
- travissmithv1/claude-skillstheir own version, first seen Nov 16, 2026
- kiaramaldonado/my-favorite-claude-skillstheir own version, first seen Nov 16, 2026
- Ajustor/claude-skillstheir own version, first seen Nov 16, 2026
- Ivan-propio/claude-skillstheir own version, first seen Nov 16, 2026
Used with
Projects with it also use intelligent-routing, nextjs-react-expert and 9 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
SKB3002Skillintelligent-routing
Automatic agent selection and intelligent task routing. Analyzes user requests and automatically selects the best specialist agent(s) without requiring explicit user mentions.
Also in 5 projects that use this
SKB3002Skillnextjs-react-expert
React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations.
Also in 3 projects that use this
xfstudioSkillbash-pro
Master of defensive Bash scripting for production automation, CI/CD
Also in 4 projects that use this
xfstudioSkillcode-refactoring-tech-debt
You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create acti
Also in 4 projects that use this
flying-diceSkillclean-code-review
Multi-agent clean code audit — each principle gets its own agent
Also in 3 projects that use this
goca-seSkillbatch-operations
Apply a change safely across many files — refactors touching more than 5 files, library or API migrations, project-wide renames of symbols/imports/paths, or adding boilerplate to many files. Use when "do it all at once" risks context overflow or silent failures.
Also in 3 projects that use this
- +4 more from xfstudio
Other versions123 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 123
- superplanehq/superplane★ 10ksame name
- vudovn/ag-kit★ 8.2ksame name
- vudovn/antigravity-kit★ 8.2ksame name
- Openpanel-dev/openpanel★ 7.3ksame name
- ciembor/agent-rules-books★ 2.8ksame name
- wondelai/skills★ 2.7ksame name
- decebals/claude-code-java★ 763same name
- operately/operately★ 618same name
- liza-mas/liza★ 418same name
- Mindrally/skills★ 275same name
113 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- git-cleanupSkill
- skill-creatorSkill
- astro-architectureSkill
- monorepo-architectureSkill
- nestjs-architectureSkill
- nextjs-architectureSkill
- react-native-architectureSkill
- gh-cliSkill
- git-cleanupSkill
- backend-best-practicesSkill
- code-quality-reviewSkill
- design-patternsSkill
- frontend-best-practicesSkill
- solid-principlesSkill
- tdd-workflowSkill
- ssh-connectSkill
- ts-import-organizerSkill
- idd-applySkill
- idd-exploreSkill
- idd-planSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 116 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 77
No mezcles refactor con cambios de comportamiento.
- Very specific: line 100
No tragues errores (catch {} o catch (e) { console.log(e) } y seguir).
- Very specific: line 103
No uses null/undefined como señal de error ambigua.
- Very specific: line 119
No derives en estado lo que puedes calcular en el render.
- Distinctive: line 124
No mezcles en una misma función consultas SQL, reglas de negocio y formateo de respuesta.
“Common” is measured: kept by at least 6 in 10 of the 116 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Clean Code
🎯 Propósito
Hacer que el código sea fácil de leer, cambiar y probar, a nivel de función y archivo: nombres, tamaño y forma de las funciones, manejo de errores, comentarios y duplicación. Ofrece un proceso seguro para refactorizar (comportamiento intacto, pasos pequeños, tests entre pasos) y un detector heurístico que acelera encontrar dónde mirar.
Fuera de alcance: el diseño de clases y módulos (SOLID), la elección de patrones de diseño y la arquitectura de carpetas. Si el problema real está ahí, dilo en el reporte en lugar de forzarlo con refactors locales.
⚡ Cuándo Activar esta Skill
- El usuario pide limpiar, refactorizar o "mejorar" código, o dice que es difícil de leer o mantener.
- Se pide una revisión de código centrada en legibilidad y mantenibilidad.
- Se escribe código nuevo y el usuario quiere que siga buenas prácticas.
- Antes de añadir una feature a una función que ya es larga o confusa (preparar el terreno).
📋 Flujo de Trabajo Paso a Paso
1. Delimitar el alcance y el modo
- Modo revisión (solo informe): el usuario pide revisar, opinar o "qué mejorarías". No edites archivos.
- Modo refactor: el usuario pide limpiar o refactorizar. Edita, pero solo dentro del alcance pedido (los archivos o funciones nombrados).
- Modo escritura: código nuevo. Aplica las reglas de la sección "Reglas de Clean Code" desde el principio.
Lee primero las convenciones del proyecto: linter y formatter (eslint, biome, prettier), tsconfig estricto o no, estilo de nombres y de errores existente. Las convenciones del proyecto ganan a las reglas genéricas de esta skill.
2. Red de seguridad (modo refactor)
Un refactor cambia la estructura sin cambiar el comportamiento, y eso solo se puede afirmar si hay tests.
- Localiza los tests que cubren el código y ejecútalos. Anota el resultado de partida.
- Si no hay tests, escribe tests de caracterización que fijen el comportamiento actual (entradas representativas, bordes y errores) antes de tocar nada. Si la skill
tdd-workflowestá instalada, sigue su Flujo C. - Si escribir tests no es viable, avisa del riesgo y limita el refactor a transformaciones mecánicas seguras (renombrar, extraer variable o función, guard clauses).
3. Detectar candidatos
node <skill-dir>/scripts/detect-smells.mjs <archivos o carpetas><skill-dir> es el directorio que contiene este SKILL.md; ejecútalo desde la raíz del proyecto. Señala funciones largas, anidamiento profundo, demasiados parámetros, archivos largos, números mágicos, ternarios anidados y TODO/FIXME (--json para salida estructurada; umbrales configurables con --max-lines, --max-depth, --max-params, --max-file-lines). Solo analiza JS/TS; en otros lenguajes, revisa a mano con el mismo catálogo.
El script da señales, no veredictos. Después lee el código y busca los smells que ninguna métrica detecta: nombres engañosos, abstracciones mezcladas, efectos ocultos, errores silenciados. Usa el catálogo de smells.
4. Priorizar
Ordena los hallazgos por impacto, no por cantidad:
- Riesgo de corrección: errores tragados, estados mutables compartidos, efectos secundarios ocultos,
nullsin comprobar. - Comprensión: nombres engañosos, funciones que hacen varias cosas, condicionales complejos, niveles de abstracción mezclados.
- Duplicación con riesgo de divergencia: la misma regla de negocio copiada en varios sitios.
- Cosmética: lo que el formatter o el linter ya resuelven. No lo reportes como hallazgo si hay herramienta para ello; sugiere ejecutarla.
5. Refactorizar en pasos pequeños (modo refactor)
- Aplica una transformación cada vez del catálogo de refactorings y ejecuta los tests tras cada una (o tras cada grupo pequeño y mecánico).
- No mezcles refactor con cambios de comportamiento. Si encuentras un bug, no lo corrijas en silencio: repórtalo y pregunta, o corrígelo en un paso separado y declarado, con su test.
- Mantén la API pública (nombres exportados, firmas, rutas) salvo que el usuario lo pida. Si un cambio la afecta, avísalo antes.
- Para cuando el código sea claro. No extraigas abstracciones "por si acaso".
6. Reportar
Usa el formato de la sección "Reporte". En modo revisión, cada hallazgo lleva su ubicación archivo:línea, el smell, por qué importa en este código y el refactor concreto sugerido (con un fragmento antes/después solo cuando aporte).
📏 Reglas de Clean Code
Nombres
- Revelan intención y dominio:
overdueInvoices, nolist2nidata. Booleanos como pregunta:isExpired,hasAccess,canRetry. - Funciones con verbo (
calculateTotal,sendInvoice), clases y tipos con sustantivo. Un concepto, una palabra en todo el código (no mezclarfetch,getyretrievepara lo mismo). - La longitud del nombre crece con el alcance:
ivale en un bucle de tres líneas; un export necesita un nombre completo.
Funciones
- Hacen una sola cosa en un solo nivel de abstracción. Si puedes extraer un trozo con un nombre que no sea una paráfrasis del código, la función hacía más de una cosa.
- Pocas líneas y poco anidamiento: usa guard clauses y returns tempranos en lugar de
ifanidados. - Pocos parámetros (≤ 3). Más allá, agrupa en un objeto con nombre (
{ from, to, currency }). Evita los parámetros booleanos que cambian el comportamiento (render(true)): separa en dos funciones o usa una opción con nombre. - Separa comandos de consultas: una función que devuelve un valor no debería además modificar estado de forma inesperada.
- Sin efectos secundarios ocultos: si
getUser()también escribe en caché o en analytics, el nombre miente.
Errores
- No tragues errores (
catch {}ocatch (e) { console.log(e) }y seguir). Manéjalos, añade contexto y relanza, o deja que suban. - Falla pronto con errores específicos del dominio (
InvoiceAlreadyPaidError) en lugar deError('error')o códigos mágicos de retorno. - Valida la entrada en los bordes (controladores, formularios, adaptadores) y confía en los tipos dentro del núcleo.
- No uses
null/undefinedcomo señal de error ambigua; usa una excepción, un tipoResulto un valor opcional explícito según la convención del proyecto.
Comentarios
- El código explica el qué; el comentario, el porqué (una decisión, una restricción externa, un workaround con enlace al issue).
- Borra el código comentado (git lo recuerda) y los comentarios que repiten el código.
- Un comentario que explica un bloque suele pedir extraer ese bloque a una función con ese nombre.
Datos y expresiones
- Sustituye números y cadenas mágicas por constantes con nombre o enums (
FREE_SHIPPING_THRESHOLD). - Prefiere inmutabilidad:
const, copias (map,filter, spread) en lugar de mutar argumentos. - Ternarios solo simples; si se anidan, usa
if/switch, un mapa de búsqueda o una función. - Condiciones complejas → variable o función con nombre (
const isEligibleForRefund = ...). - Duplicación: aplica la regla de tres. Dos copias pueden ser coincidencia; a la tercera, extrae. Duplicar es más barato que una abstracción equivocada.
Frontend (componentes)
- Un componente con demasiadas responsabilidades (fetch + estado + formato + layout) se divide: lógica en hooks o funciones puras, presentación en componentes pequeños.
- No derives en estado lo que puedes calcular en el render; evita
useEffectpara sincronizar estado derivado. - Props con nombres de dominio y sin "prop drilling" profundo de muchas props sueltas.
Backend (servicios y handlers)
- Los controladores/handlers traducen HTTP ↔ dominio: validan, llaman a un caso de uso y mapean la respuesta. La lógica de negocio no vive en ellos.
- No mezcles en una misma función consultas SQL, reglas de negocio y formateo de respuesta.
- Los logs llevan contexto estructurado (
{ orderId, userId }), nunca datos sensibles.
⚠️ Reglas Críticas
- Refactorizar no cambia el comportamiento. Sin tests que lo respalden, no afirmes que el comportamiento se conserva.
- Ejecuta los tests antes y después de refactorizar, e informa del resultado real. Si fallaban antes, dilo.
- No corrijas bugs en silencio dentro de un refactor: repórtalos aparte.
- No toques lo que no se pidió. Fuera del alcance, como mucho una nota en "Fuera de alcance".
- No sobre-abstraigas: nada de interfaces, factorías o capas nuevas para un único uso. La sencillez también es clean code.
- No cambies la API pública (exports, firmas, contratos HTTP) sin avisar y obtener confirmación.
- Las métricas del script son heurísticas. Una función de 45 líneas que es una tabla de configuración clara no es un problema.
📤 Reporte
### Resumen
<1–2 frases: estado general y los 2–3 problemas de más impacto>
### Hallazgos
| Prioridad | Ubicación | Smell | Por qué importa aquí | Refactor |
|---|---|---|---|---|
| Alta | src/orders/report.ts:42 | Error tragado | Un fallo de red devuelve un informe vacío como si fuera válido | Relanzar con contexto o devolver Result |
| Media | src/orders/report.ts:12 | Función larga (88 líneas) | Mezcla consulta, cálculo y formato | Extraer `loadOrders`, `summarize`, `formatRow` |
### Cambios aplicados (modo refactor)
1. <transformación> — tests: ✅ N/N
### Fuera de alcance / pendiente
- <bugs encontrados, problemas de diseño de módulo, decisiones para el usuario>📚 Referencias
- Catálogo de code smells
- Catálogo de refactorings
- Ejemplos antes/después en frontend y backend
🛠️ Scripts
scripts/detect-smells.mjs: detector heurístico para JS/TS, de solo lectura. Reglas:long-function,deep-nesting,too-many-params,long-file,magic-number,nested-ternary,todo-comment. Opciones:--json,--max-lines,--max-depth,--max-params,--max-file-lines,--fail-on-findings,--help.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

