Piyush-Nagar/coding-agents-skills

Le code est lu bien plus souvent qu'il n'est écrit. La maintenabilité est ce qui distingue une base de code de trois ans agréable d'un bourbier. Optimisez pour le prochain développeur, qui pourrait être vous dans six mois.

Qu'est-ce que coding-agents-skills ?

Cette compétence fournit un ensemble de règles de conception pour assurer la maintenabilité des bases de code sur le long terme. Elle s'applique à tout langage de programmation et tout environnement de développement, et est particulièrement utile pour les agents IA travaillant sur des projets logiciels. La compétence met l'accent sur des pratiques comme le regroupement par fonctionnalité, l'utilisation d'interfaces uniquement aux frontières des modules, la suppression du code mort plutôt que sa mise en commentaire, la préférence pour les fonctions pures et testables, et la vérification automatique de la qualité du code dans l'intégration continue. Elle identifie également des signaux d'alarme comme les fichiers trop volumineux, les packages "utils" partagés, ou des tests qui échouent après un simple changement d'implémentation. Ces règles aident les agents à produire du code que les humains peuvent maintenir et faire évoluer sereinement.

Compatible avec✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/Piyush-Nagar/coding-agents-skills/tree/HEAD/backend/core/nfr/maintainability

Documentation

Maintenabilité

Règles

Une fonctionnalité, un emplacement. Regroupez par fonctionnalité (voir backend/core/SKILL.md). Une modification unique doit toucher des fichiers adjacents, et non des couches éparpillées.
Interfaces uniquement aux frontières des modules. À l'intérieur d'une fonctionnalité, les classes concrètes sont acceptables. Les interfaces existent pour permettre aux appelants de dépendre de contrats à travers les frontières, et non pour décorer chaque classe.
Supprimez, ne mettez pas en commentaire. Le code mort et les commentaires // TODO éternels pourrissent. Git se souvient ; l'IDE n'a pas besoin de se souvenir.
Préférez les petites fonctions pures. Plus faciles à tester, plus faciles à raisonner, plus faciles à composer. Les effets de bord aux limites du système, pas dispersés à travers lui.
Les tests couvrent le comportement, pas l'implémentation. Réécrire les internes ne devrait pas casser les tests. Si cela arrive, le test est couplé à la mauvaise chose.
Les API publiques sont versionnées. Les modifications cassantes derrière une nouvelle version ou un feature flag — jamais un renommage silencieux.
Injection de dépendances plutôt que singletons statiques. Les statiques sont non testables et cachent le couplage. Passez les dépendances ; mockez-les dans les tests.
Épinglez et mettez à jour régulièrement les dépendances. Lockfiles commits ; Renovate/Dependabot en PR automatique. Laisser deux ans de retard signifie une migration imprévue de deux semaines.
Documentez le "pourquoi", pas le "quoi". Le code montre ce qui est fait ; les commentaires expliquent la règle métier, la contrainte historique, le compromis non évident.
Lint, formatez, et vérifiez les types dans l'IC. Pas en mode conseil, en mode bloquant. Les humains devraient débattre de conception, pas d'espacement.
Gardez le build vert et rapide. Les tests instables ou lents sont ignorés, et une fois ignorés, ils ne protègent rien.

Signaux d'alarme

Un fichier de plus de ~500 lignes, ou une classe avec plus de ~10 méthodes publiques — généralement une fonctionnalité qui cherche à s'échapper.
Un package "utils" partagé où les assistants orphelins vont mourir.
Moquer la chose testée pour faire passer un test.
"Ne touche pas à ce module, plus personne ne le comprend."
Temps de build IC mesuré en dizaines de minutes.