Communitygithub.com

lguidolin/engineering-constitution

Use ao iniciar o trabalho em um projeto que segue a constituição de engenharia, orientando-se por suas regras, ou decidindo qual prática de engenharia se aplica a uma tarefa — escrita de especificações, commits, testes, segurança, deploys, banco de dados ou trabalho de UI.

O que é engineering-constitution?

Este skill serve como um índice portátil de práticas de engenharia de software, organizado em skills focados. Ele estabelece oito princípios invioláveis — como 'entenda antes de construir', 'testes são um controle, não uma formalidade' e 'YAGNI impiedosamente' — e roteia o usuário para o skill específico necessário para cada tarefa (ex.: design, commits, testes, segurança, deploys). O raciocínio completo está no arquivo `references/engineering-constitution.md`, que acompanha o SKILL.md. O skill é dividido em dois tiers: Tier 1 (universal, aplica-se a qualquer projeto) e Tier 2 (específico de stack, como PostgreSQL, GraphQL ou Kubernetes). Ele reforça que o usuário deve consultar o skill relevante antes de codificar, commitar ou fazer deploy, e que instruções explícitas do usuário têm precedência sobre a constituição.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/engineering-constitution
Ver original→Navegar por todas as habilidades

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentação

Constituição de Engenharia

Visão Geral

Uma carta portátil de práticas de engenharia, decomposta em skills focados. Este skill é o índice: ele declara os princípios invioláveis e roteia você para o skill específico da sua tarefa. O raciocínio completo está em references/engineering-constitution.md, incluído junto com este SKILL.md para que viaje com o skill onde quer que ele seja instalado.

Ideia central: Engenharia de software é programação integrada ao longo do tempo. Otimize para o sistema de longa duração — operá-lo, alterá-lo com segurança, recuperá-lo quando quebrar — não para o primeiro deploy.

Os Oito Princípios Invioláveis

  1. Entenda antes de construir. Nenhum código antes de um design aprovado.
  2. Registre cada decisão com sua justificativa — e o que você rejeitou.
  3. Testes são um controle, não uma formalidade — e mudança comportamental é test-first. Um teste falhando é informação, nunca editado. Mudança estrutural é limitada pela suíte existente passando sem edições.
  4. YAGNI, impiedosamente.
  5. Automatize o repetível.
  6. Engenharia de software é programação integrada ao longo do tempo.
  7. Uma regra não imposta é uma sugestão. Vincule regras a ferramentas ou rotule-as como julgamento do revisor.
  8. As instruções explícitas do usuário têm precedência sobre este documento. Precedência: Usuário → Constituição → padrões da ferramenta.

Qual Skill Eu Preciso?

Tier 1 — universal (aplica-se a todo projeto):

Sua tarefaSkill
Iniciar uma funcionalidade, transformar uma ideia em especificação/planodesigning-before-building
Uma decisão foi tomada; escrevê-la (ADR, índice, ideias adiadas)recording-decisions
Commitar, escrever mensagens, releases automatizadosconventional-commits-and-releases
Escrever/alterar testes; regras de permissão/papéis; um teste quebrou em um refatortests-as-a-control
Escrever ou refatorar código; estruturar uma mudança; decisões DRYchange-hygiene-and-code-craft
Construir UI, componentes, estilização, acessibilidadeinterface-craft-and-accessibility
CI, hooks pre-push, runners de tarefas, portões de mergemerge-gates-and-automation
Logging, métricas, tracing, health checks, SLOs, alertasobservability-and-slos
Entrada não confiável, segredos, autenticação, dependências, modelagem de ameaçasdefense-in-depth-security
Caminhos críticos, paginação, N+1, endpoints de lista, interfaces públicasperformance-and-scale
Planejar um deploy, rollback ou incidente/pós-morteresilience-and-deploy-safety

Tier 2 — específico de stack (carregue apenas quando a ferramenta/tópico estiver presente):

Sua tarefaSkill
PostgreSQL, PostGraphile, RLS, arquivos SQL, o caminho app→GraphQL→DBpostgres-postgraphile-rls-and-sql
Consultas GraphQL compartilhadas entre UI e testes; testes de contrato rota/schemagraphql-contract-testing
Mudança de schema com dados que devem sobreviver — migrações, backfillszero-downtime-migrations
Deploy no Kubernetes/AKS, segredos na nuvem, rollout progressivo, ambientes por PRcloud-delivery-aks

Como Esses Skills se Aplicam a um Novo Projeto

  • Tier 1 viaja sem alterações. Todo skill acima da linha se aplica a qualquer projeto — web app, pipeline, CLI, biblioteca.
  • Tier 2 é substituível. Quando a stack difere, os skills Tier 2 não serão acionados (suas descrições são específicas de stack) e você substitui por equivalentes. Os princípios que eles implementam (um caminho de dados, aplicação final baixa, seams de contrato, deploys reversíveis) ainda se mantêm.
  • Escala para o ciclo de vida. Um projeto pré-lançamento ou apenas local aplica migrações zero-downtime, canary e processo formal de incidente como escreva-a-regra-agora, ative-no-gatilho. Declare o modo do projeto em seu primeiro registro de decisão.

Bandeira Vermelha

Se você está prestes a escrever código, commitar, fazer deploy ou alterar um teste e não consultou o skill relevante acima — pare e carregue-o primeiro. A constituição substitui o hábito padrão (Princípio 7); o hábito é o que ela está corrigindo.

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.

Habilidades Relacionadas

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