Communitygithub.com

lguidolin/constitucion-de-ingenieria

Úsalo al comenzar a trabajar en un proyecto que sigue la constitución de ingeniería, orientándote a sus reglas o decidiendo qué práctica de ingeniería aplica a una tarea — escribir especificaciones, commits, pruebas, seguridad, despliegues, base de datos o trabajo de UI.

¿Qué es constitucion-de-ingenieria?

La habilidad 'Constitución de Ingeniería' sirve como un índice portátil de principios y prácticas de ingeniería, desglosada en habilidades específicas. Define ocho principios inviolables que priorizan la mantenibilidad a largo plazo, como 'Entender antes de construir' y 'Pruebas como control', y determina qué habilidad detallada cargar según la tarea (diseño, commits, despliegue, etc.). Se divide en dos niveles: las habilidades de Nivel 1 son universales y aplican a cualquier proyecto (ej. diseño antes de construir, decisiones de registro, pruebas), mientras que las de Nivel 2 son específicas del stack (ej. PostgreSQL, GraphQL, Kubernetes). El usuario siempre tiene la máxima prioridad sobre la constitución. Esta habilidad es particularmente útil para equipos que buscan estandarizar procesos, reducir la deuda técnica y garantizar que las decisiones de ingeniería estén documentadas y sean consistentes, funcionando en plataformas de agentes de IA como Claude Code, Cursor o Codex.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/engineering-constitution
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

Constitución de Ingeniería

Resumen

Una carta portátil de práctica de ingeniería, descompuesta en habilidades enfocadas. Esta habilidad es el índice: establece los principios inviolables y te enruta a la habilidad específica para tu tarea. El razonamiento completo reside en references/engineering-constitution.md, empaquetado junto a este SKILL.md para que viaje con la habilidad dondequiera que esté instalada.

Idea central: La ingeniería de software es programación integrada a lo largo del tiempo. Optimiza para el sistema de larga duración — operarlo, cambiarlo de forma segura, recuperarlo cuando se rompe — no para el primer despliegue.

Los Ocho Principios Inviolables

  1. Entender antes de construir. Sin código antes de un diseño aprobado.
  2. Registrar cada decisión con su justificación — y lo que rechazaste.
  3. Las pruebas son un control, no una formalidad — y el cambio de comportamiento es primero la prueba. Una prueba fallida es información, nunca se edita. El cambio estructural, en cambio, está condicionado a que la suite existente pase sin editar.
  4. YAGNI, sin piedad.
  5. Automatiza lo repetible.
  6. La ingeniería de software es programación integrada a lo largo del tiempo.
  7. Una regla no aplicada es una sugerencia. Vincula las reglas a herramientas o etiquétalas como juicio del revisor.
  8. Las instrucciones explícitas del usuario están por encima de este documento. Precedencia: Usuario → Constitución → valores predeterminados de la herramienta.

¿Qué Habilidad Necesito?

Nivel 1 — universal (aplica a todo proyecto):

Tu tareaHabilidad
Comenzar una funcionalidad, convertir una idea en una especificación/plandesigning-before-building
Se tomó una decisión; escribirla (ADR, índice, ideas diferidas)recording-decisions
Hacer commits, escribir mensajes, lanzamientos automatizadosconventional-commits-and-releases
Escribir/cambiar pruebas; reglas de permisos/roles; una prueba se rompió en una refactorizacióntests-as-a-control
Escribir o refactorizar código; estructurar un cambio; decisiones DRYchange-hygiene-and-code-craft
Construir UI, componentes, estilos, accesibilidadinterface-craft-and-accessibility
CI, ganchos pre-push, ejecutores de tareas, puertas de fusiónmerge-gates-and-automation
Registro, métricas, trazas, comprobaciones de salud, SLO, alertasobservability-and-slos
Entrada no confiable, secretos, autenticación, dependencias, modelado de amenazasdefense-in-depth-security
Rutas críticas, paginación, N+1, endpoints de listas, interfaces públicasperformance-and-scale
Planificar un despliegue, reversión o incidente/postmortemresilience-and-deploy-safety

Nivel 2 — específico del stack (cargar solo cuando la herramienta/tema está presente):

Tu tareaHabilidad
PostgreSQL, PostGraphile, RLS, archivos SQL, la ruta app→GraphQL→DBpostgres-postgraphile-rls-and-sql
Consultas GraphQL compartidas entre UI y pruebas; pruebas de contrato de ruta/esquemagraphql-contract-testing
Cambio de esquema con datos que deben sobrevivir — migraciones, rellenadozero-downtime-migrations
Desplegar en Kubernetes/AKS, secretos en la nube, despliegue progresivo, entornos por PRcloud-delivery-aks

Cómo se Aplican Estas Habilidades a un Proyecto Nuevo

  • El Nivel 1 viaja sin cambios. Cada habilidad por encima de la línea aplica a cualquier proyecto — aplicación web, pipeline, CLI, biblioteca.
  • El Nivel 2 es intercambiable. Cuando el stack difiere, las habilidades de Nivel 2 no se activarán (sus descripciones son específicas del stack) y sustituyes equivalentes. Los principios que implementan (una ruta de datos, aplicación final baja, costuras de contrato, despliegues reversibles) siguen vigentes.
  • Escala según el ciclo de vida. Un proyecto pre-lanzamiento o solo local aplica migraciones de cero tiempo de inactividad, canary y proceso de incidente formal como escribe-la-regla-ahora, activa-en-desencadenador. Indica el modo del proyecto en su primer registro de decisión.

Bandera Roja

Si estás a punto de escribir código, hacer commit, desplegar o cambiar una prueba y no has consultado la habilidad relevante anterior — detente y cárgala primero. La constitución anula el hábito predeterminado (Principio 7); el hábito es lo que está corrigiendo.

Individual skills in this repo

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

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.

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/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

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