Communitygithub.com

lguidolin/hygiène-des-changements-et-artisanat-du-code

À utiliser lors de l'écriture ou du refactoring de code, de la structuration d'un commit ou d'une PR, ou pour décider s'il faut abstraire une duplication. Symptômes : mélange de réorganisation et de changements logiques, PR qui fait plusieurs choses à la fois, fichier qui grossit, deuxième copie de code similaire, ou hésitation à appliquer le principe DRY.

Qu'est-ce que hygiène-des-changements-et-artisanat-du-code ?

Cette compétence fournit des principes et des heuristiques pour améliorer la qualité des changements de code et la rédaction du code lui-même. Elle repose sur deux thèmes centraux : séparer les changements structurels des changements comportementaux, et exprimer clairement l'intention avec le moins d'astuce possible. En matière d'hygiène des changements, elle recommande de valider indépendamment les réorganisations (scinder des fichiers, renommer, ajouter des commentaires) avant les modifications de comportement, de ne traiter qu'un seul sujet par changement, et d'améliorer le code environnant sans partir dans un refactoring non lié. Pour l'artisanat du code, elle prône l'explicite plutôt que l'implicite (pas de wildcards, pas de conversions implicites), des noms descriptifs, des commentaires sur l'intention, des unités petites et mono-fonctionnelles, une application réfléchie du principe DRY (abstraire après la deuxième occurrence et seulement sur une intention partagée), et le respect des standards de l'écosystème. La compétence détaille également des tensions nommées (DRY vs abstraction prématurée, DRY vs DAMP) et les rationalisations courantes qui conduisent à de mauvaises pratiques. Elle s'applique à tout environnement de développement (Claude Code, Cursor, Codex, etc.) et est conçue pour être utilisée lors de la rédaction, du refactoring, ou de la revue de code.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/change-hygiene-and-code-craft
Voir l'original→Voir toutes les compétences

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentation

Hygiène des Changements et Artisanat du Code

Aperçu

Comment les changements sont façonnés et comment le code est écrit. Deux thèmes : séparer les changements structurels des changements comportementaux, et dire ce que l'on veut avec le moins d'astuce qui fonctionne.

Hygiène des Changements

  • Les changements structurels avant les changements comportementaux, validés indépendamment. La réorganisation (scinder des fichiers, renommer, ajouter des commentaires) est une étape distincte et vérifiable indépendamment de la modification du comportement (nouvelles contraintes, logique modifiée). Ne les mélangez jamais en un seul changement indivisible — un relecteur ne peut pas distinguer un remaniement sûr de véritables changements logiques.
  • Un seul sujet par changement. Un changement a un objectif unique et énonçable.
  • Améliorez le code dans lequel vous travaillez lorsque ses problèmes affectent votre tâche (laissez le campement plus propre) — mais ne commencez pas un refactoring non lié. Restez concentré sur l'objectif.

Artisanat du Code

  • Explicite plutôt qu'implicite. Pas de jokers là où des noms sont nécessaires, pas de conversions implicites, pas de chaînes vides ni de sentinelles magiques. Dites ce que vous voulez.
  • Noms descriptifs. Les fonctions/variables décrivent ce qu'elles font ; suivez les idiomes du langage et de l'écosystème.
  • Commentez l'intention, pas le mécanisme. Expliquez pourquoi quand ce n'est pas évident ; évitez les commentaires sur du code explicite.
  • Unités petites et mono-fonctionnelles. Pour toute unité, vous devriez pouvoir dire ce qu'elle fait, comment l'utiliser, de quoi elle dépend — sans lire ses détails internes. Un fichier volumineux fait généralement trop de choses.
  • DRY dans le code de production, avec discernement. La duplication est un signal, pas une erreur automatique. La deuxième occurrence quasi identique déclenche une décision délibérée : abstraire, ou consigner pourquoi pas. Abstraire le sens partagé, jamais la forme fortuite — les choses qui se ressemblent mais changent pour des raisons différentes restent séparées.
  • Suivez les standards de l'écosystème. Utilisez les idiomes et les bibliothèques bien supportées qu'un praticien compétent attend. Ne réinventez pas ce que la plateforme a résolu.

Les Tensions Nommées

  • DRY vs abstraction prématurée : le code de production abstrait sur une répétition démontrée de l'intention, pas une répétition anticipée de la forme. En cas de doute, attendez la troisième occurrence (YAGNI gère l'arbitrage).
  • DRY vs DAMP : le code de production est DRY ; le code de test est DAMP (clarté avant dé-duplication, voir tests-as-a-control). Appliquer DRY aux tests est une violation.

Rationalisations Courantes

ExcuseRéalité
"Je vais renommer et ajouter la fonctionnalité en un seul commit"Structure et comportement dans un seul diff sont impossibles à réviser. Séparez-les.
"Deux copies, je dois appliquer DRY maintenant"Deuxième occurrence = décidez. Même forme ≠ même sens. La duplication fortuite doit rester séparée.
"Pendant que je suis là, laissez-moi refactorer cet autre module"Le refactoring non lié étend la portée et le risque. Notez-le ; ne le faites pas maintenant.
"Une one-liner astucieuse est plus élégante"L'explicite bat l'astuce. Optimisez pour le prochain lecteur.

Drapeaux Rouges — ARRÊTEZ

  • Un diff qui déplace du code et modifie son comportement
  • Une PR dont l'objectif nécessite le mot "et" pour être décrit
  • Abstraire dès la première vue d'une similarité, ou sur une répétition anticipée (non réelle)
  • Un fichier que vous ne pouvez plus garder en tête

Raisonnement complet : Articles V & VI de la constitution, regroupés dans engineering-constitution/references/engineering-constitution.md.

Individual skills in this repo

This repo contains 18 individual skills — each has its own dedicated page.

lguidolin/cloud-delivery-aks

Use when deploying to Kubernetes or Azure Kubernetes Service (AKS), configuring cloud secrets, setting up progressive rollout/canary, per-PR ephemeral environments, or k8s health probes. Keywords — Kubernetes, AKS, Key Vault, Argo Rollouts, Flagger, canary, blue-green, liveness, readiness, PodDisruptionBudget, HPA, rollback, GHCR.

lguidolin/commit-history-rewrite

Use when an existing repository has messy commit history that needs to conform to conventional commits before adopting release-please, or when intermediate WIP/fixup/merge commits need to be cleaned up.

lguidolin/conventional-commits-and-releases

Use when committing, writing a commit message, opening a PR that will be squash-merged, or configuring automated versioning/changelogs. Keywords — conventional commits, release-please, semver, feat/fix/chore, breaking change, changelog.

lguidolin/defense-in-depth-security

Use when handling untrusted input, secrets, authentication/authorization, or dependencies — or threat-modeling a new surface. Keywords — STRIDE, threat model, least privilege, secrets management, supply chain, dependency scanning, input validation, audit log, defense in depth.

lguidolin/designing-before-building

Use when starting a feature, fixing a non-trivial bug, or about to write implementation code — before any code exists. Symptoms you need this: "this is simple, I'll just code it", reaching for the editor before a design is approved, or an idea that hasn't been turned into a spec and plan.

lguidolin/engineering-constitution

Use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

lguidolin/graphql-contract-testing

Use when writing a GraphQL query/mutation that the UI and a test will share, or building route/schema contract or smoke tests. Symptoms — copying a query into a test, a test asserting on query text, schema change that didn't break the UI build, or RLS/permission drift. Keywords — graphql-codegen, typed document, contract test, route smoke test.

lguidolin/init-repo-CI

Use when setting up a new repository with conventional commits, release-please, and CI automation, or when retrofitting an existing repository that lacks automated versioning and PR validation workflows.

lguidolin/interface-craft-and-accessibility

Use when building or styling UI — components, layouts, forms, design tokens — or making accessibility decisions. Keywords — a11y, WCAG, keyboard navigation, focus state, contrast, design system, minimalist UI, component reuse, ARIA, semantic HTML.

lguidolin/merge-gates-and-automation

Use when setting up or changing CI, pre-push hooks, or a task runner, or deciding what must pass before merge. Symptoms — tempted to put authoritative checks only in a local hook, skip CI, bypass with --no-verify, or unsure what gates a merge vs. runs locally.

lguidolin/observability-and-slos

Use when adding logging, metrics, tracing, health checks, SLOs, or alerting — or when building a service surface that needs to be operable and debuggable. Keywords — structured logs, OpenTelemetry, correlation id, RED metrics, liveness, readiness, SLI, SLO, error budget, alerting.

lguidolin/performance-and-scale

Use when working on hot paths, list endpoints, pagination, data-access in loops, or public interfaces/schemas. Symptoms — unbounded queries, N+1 access, no latency budget, optimizing without measuring, or changing an interface many consumers depend on. Keywords — pagination, N+1, Hyrum's Law, performance budget, bundle size.

lguidolin/postgres-postgraphile-rls-and-sql

Use when writing PostgreSQL, PostGraphile config, Row-Level Security policies, SQL schema files, or working on the Browser→App→PostGraphile→Postgres data path. Keywords — RLS, SECURITY DEFINER, search_path, pgSettings, grants, roles, GraphQL depth limit, query cost, statement_timeout, SQL file organization.

lguidolin/recording-decisions

Use when a design or architecture decision has been made and needs to be captured — writing a decision record or ADR, updating a decision index, noting a deferred idea, or superseding a past decision. Keywords — ADR, decision record, rationale, rejected alternatives, dependency index.

lguidolin/resilience-and-deploy-safety

Use when planning a deploy, designing a rollback, or responding to an incident or writing a postmortem. Keywords — deploy safety, rollback, immutable artifact, progressive delivery, canary, blast radius, incident response, blameless postmortem, error budget.

lguidolin/ship-it

Use when the user wants to ship work — push, PR, archive decision records, merge, and clean up. Handles the full lifecycle from committing final changes through post-merge cleanup including converting specs/plans to compact decision records.

lguidolin/tests-as-a-control

Use when writing or modifying tests, when a test breaks during a refactor, or when testing permission/role rules. Symptoms — tempted to edit a test to make it pass, testing only the happy path, a deny-test that started passing, flaky tests, or unsure what to assert.

lguidolin/zero-downtime-migrations

Use when changing a database schema where data must survive the change — adding/removing/renaming columns, constraints, indexes, or backfilling. Symptoms — a destructive migration bundled with a code deploy, a NOT NULL column with a backfill, a table-locking UPDATE, or a rename. Keywords — expand/contract, parallel change, backfill, NOT VALID, CREATE INDEX CONCURRENTLY, graphile-migrate.

Skills associés

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community