Communitygithub.com

lguidolin/change-hygiene-and-code-craft

Use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

¿Qué es change-hygiene-and-code-craft?

change-hygiene-and-code-craft is a Claude Code agent skill that use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/change-hygiene-and-code-craft
Ver original→Ver todas las habilidades

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentación

Change Hygiene and Code Craft

Overview

How changes are shaped and how code is written. Two themes: separate structural from behavioral change, and say what you mean with the least cleverness that works.

Change Hygiene

  • Structural changes before behavioral changes, validated independently. Reorganizing (splitting files, renaming, adding comments) is a separate, independently-checkable step from changing behavior (new constraints, altered logic). Never mix them in one indivisible change — a reviewer can't tell safe reshuffling from real logic changes.
  • One concern per change. A change has a single, statable purpose.
  • Improve the code you're working in when its problems affect your task (leave the campsite cleaner) — but don't start unrelated refactoring. Stay focused on the goal.

Code Craft

  • Explicit over implicit. No wildcards where names belong, no implicit casts, no empty-string or magic sentinels. Say what you mean.
  • Descriptive names. Functions/variables describe what they do; follow language and ecosystem idioms.
  • Comment intent, not mechanics. Explain why when non-obvious; skip comments on self-evident code.
  • Small, single-purpose units. For any unit you should be able to state what it does, how to use it, what it depends on — without reading its internals. A large file is usually doing too much.
  • DRY in production code, with judgment. Duplication is a signal, not an automatic error. The second near-identical occurrence triggers a deliberate decision: abstract, or record why not. Abstract shared meaning, never coincidental shape — things that look alike but change for different reasons stay apart.
  • Follow ecosystem standards. Use the idioms and well-supported libraries a competent practitioner expects. Don't reinvent what the platform solved.

The Named Tensions

  • DRY vs. premature abstraction: production code abstracts on demonstrated repetition of intent, not anticipated repetition of shape. When unsure, wait for the third occurrence (YAGNI governs the tie-break).
  • DRY vs. DAMP: production code is DRY; test code is DAMP (clarity over de-duplication, see tests-as-a-control). Applying DRY to tests is a violation.

Common Rationalizations

ExcuseReality
"I'll rename and add the feature in one commit"Structure and behavior in one diff are unreviewable. Split them.
"Two copies, I must DRY it now"Second occurrence = decide. Same shape ≠ same meaning. Coincidental duplication should stay apart.
"While I'm here, let me refactor this other module"Unrelated refactoring expands scope and risk. Note it; don't do it now.
"A clever one-liner is more elegant"Explicit beats clever. Optimize for the next reader.

Red Flags — STOP

  • A diff that both moves code and changes its behavior
  • A PR whose purpose needs the word "and" to describe
  • Abstracting on the first sight of similarity, or on anticipated (not actual) repetition
  • A file you can no longer hold in your head

Full rationale: Articles V & VI of the constitution, bundled at 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 relacionados

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

affaan-m/prisma-patterns

Prisma ORM patterns for TypeScript backends — schema design, query optimization, transactions, pagination, and critical traps like updateMany returning count not records, $transaction timeouts, migrate dev resetting the DB, @updatedAt skipped on bulk writes, and serverless connection exhaustion.

community

affaan-m/django-celery

Django + Celery async task patterns — configuration, task design, beat scheduling, retries, canvas workflows, monitoring, and testing. Use when adding background jobs, scheduled tasks, or async processing to a Django app.

community

affaan-m/quarkus-patterns

Quarkus 3.x LTS architecture patterns with Camel for messaging, RESTful API design, CDI services, data access with Panache, and async processing. Use for Java Quarkus backend work with event-driven architectures.

community