Communitygithub.com

lguidolin/change-hygiene-and-code-craft

Verwenden beim Schreiben oder Refactoren von Code, beim Strukturieren eines Commits oder PRs oder bei der Entscheidung über Abstraktion von Duplikaten. Symptome – Vermischung von Umstrukturierung mit Logikänderungen, ein PR der mehrere Dinge gleichzeitig tut, eine wachsende Datei, die zweite Kopie ähnlichen Codes oder Unsicherheit, ob etwas DRY gemacht werden soll.

Was ist change-hygiene-and-code-craft?

Diese Skill-Anleitung definiert Prinzipien für saubere Änderungshygiene und Codierungshandwerk in AI-Agent-Umgebungen wie Claude Code, Cursor oder Codex. Sie betont zwei Hauptthemen: **trenne strukturelle von verhaltensbezogenen Änderungen** und **sage, was du meinst, mit der geringsten Cleverness, die funktioniert.** Die Änderungshygiene fordert, dass Umstrukturierungen (z. B. Dateien teilen, umbenennen, Kommentare hinzufügen) als unabhängiger, überprüfbarer Schritt vor Logikänderungen erfolgen. Jede Änderung sollte einen einzigen, klar formulierten Zweck haben. Die Code-Craft-Prinzipien fokussieren auf explizite statt implizite Ausdrücke, deskriptive Namen, Kommentare zu Absichten statt Mechaniken, kleine Einheiten mit einem Zweck und den durchdachten Einsatz von DRY (Don't Repeat Yourself) auf Grundlage demonstrierter Wiederholung von Absicht, nicht zufälliger Form. Die Anleitung behandelt auch Spannungen wie DRY vs. vorzeitige Abstraktion und DRY vs. DAMP (in Tests) und listet häufige Rationalisierungen auf, die vermieden werden sollten. Sie enthält auch rote Flaggen (STOPP-Signale), die auf unangemessene Änderungsstruktur hinweisen. Die Anleitung ist plattformunabhängig und hilft Entwicklern und AI-Agenten, qualitativ hochwertigen, wartbaren Code zu produzieren, indem sie die Trennung von Belangen und klare Kommunikation durch Code fördert.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/change-hygiene-and-code-craft
Original anzeigen→Alle Skills durchsuchen

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Dokumentation

Änderungshygiene und Code Craft

Überblick

Wie Änderungen geformt und wie Code geschrieben wird. Zwei Themen: Trenne strukturelle von verhaltensbezogenen Änderungen und sage, was du meinst, mit der geringsten Cleverness, die funktioniert.

Änderungshygiene

  • Strukturelle Änderungen vor verhaltensbezogenen Änderungen, unabhängig validiert. Umstrukturieren (Dateien teilen, umbenennen, Kommentare hinzufügen) ist ein separater, unabhängig überprüfbarer Schritt von der Änderung des Verhaltens (neue Einschränkungen, veränderte Logik). Vermische sie niemals in einer untrennbaren Änderung – ein Prüfer kann sicheres Umstellen nicht von echten Logikänderungen unterscheiden.
  • Ein Anliegen pro Änderung. Eine Änderung hat einen einzigen, klar angebbaren Zweck.
  • Verbessere den Code, in dem du arbeitest, wenn seine Probleme deine Aufgabe beeinträchtigen (hinterlasse den Campingplatz sauberer) – aber beginne nicht mit unzusammenhängendem Refactoring. Bleibe fokussiert auf das Ziel.

Code Craft

  • Explizit vor implizit. Keine Wildcards, wo Namen hingehören, keine impliziten Typumwandlungen, keine leeren Zeichenketten oder magischen Sentinels. Sage, was du meinst.
  • Deskriptive Namen. Funktionen/Variablen beschreiben, was sie tun; folge den Idiomen der Sprache und des Ökosystems.
  • Kommentiere Absicht, nicht Mechanik. Erkläre warum, wenn es nicht offensichtlich ist; überspringe Kommentare bei selbsterklärendem Code.
  • Kleine, einsatzorientierte Einheiten. Für jede Einheit solltest du angeben können, was sie tut, wie man sie verwendet, wovon sie abhängt – ohne ihre Interna lesen zu müssen. Eine große Datei tut normalerweise zu viel.
  • DRY im Produktionscode mit Urteilsvermögen. Duplikation ist ein Signal, kein automatischer Fehler. Das zweite nahezu identische Vorkommen löst eine bewusste Entscheidung aus: abstrahiere oder dokumentiere, warum nicht. Abstrahiere gemeinsame Bedeutung, niemals zufällige Form – Dinge, die ähnlich aussehen, sich aber aus unterschiedlichen Gründen ändern, bleiben getrennt.
  • Befolge Ökosystemstandards. Verwende die Idiome und gut unterstützten Bibliotheken, die ein kompetenter Praktiker erwartet. Erfinde nicht neu, was die Plattform gelöst hat.

Die benannten Spannungen

  • DRY vs. vorzeitige Abstraktion: Produktionscode abstrahiert auf der Grundlage demonstrierter Wiederholung von Absicht, nicht antizipierter Wiederholung von Form. Wenn du unsicher bist, warte auf das dritte Vorkommen (YAGNI entscheidet den Tie-Break).
  • DRY vs. DAMP: Produktionscode ist DRY; Testcode ist DAMP (Klarheit vor Deduplizierung, siehe tests-as-a-control). DRY auf Tests anzuwenden ist ein Verstoß.

Häufige Rationalisierungen

AusredeRealität
"Ich benenne um und füge das Feature in einem Commit hinzu"Struktur und Verhalten in einem Diff sind nicht überprüfbar. Trenne sie.
"Zwei Kopien, ich muss jetzt DRY machen"Zweites Vorkommen = entscheide. Gleiche Form ≠ gleiche Bedeutung. Zufällige Duplikation sollte getrennt bleiben.
"Solange ich hier bin, lasse ich mich dieses andere Modul refactoren"Unzusammenhängendes Refactoring erweitert Umfang und Risiko. Notiere es; mache es jetzt nicht.
"Ein cleverer Einzeiler ist eleganter"Explizit schlägt clever. Optimiere für den nächsten Leser.

Rote Flaggen – STOPP

  • Ein Diff, das sowohl Code verschiebt als auch sein Verhalten ändert
  • Ein PR, dessen Zweck das Wort "und" zur Beschreibung benötigt
  • Abstraktion beim ersten Anzeichen von Ähnlichkeit oder bei antizipierter (nicht tatsächlicher) Wiederholung
  • Eine Datei, die du nicht mehr im Kopf behalten kannst

Vollständige Begründung: Artikel V & VI der Verfassung, gebündelt unter 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.

Verwandte Skills

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