PragmaWorks · For Engineering Leaders PragmaWorks · Para Líderes de Ingeniería

Get a real audit of one of your team's repos. By dinner. Obtén una auditoría real de uno de los repos de tu equipo. Para la cena.

If you're a tech lead, engineering manager, VP, or CTO and your team has been using AI assistance for code generation, your codebase is changing in ways your usual review cadence can't catch. This guide gets you a manager-grade report on one of your repos in an afternoon — including the team-habit and AI-bug analysis no static analyzer surfaces. Si eres tech lead, engineering manager, VP, o CTO y tu equipo ha estado usando asistencia de IA para generar código, tu base de código está cambiando de formas que tu cadencia normal de revisión no puede atrapar. Esta guía te entrega un reporte de calidad gerencial sobre uno de tus repos en una tarde — incluyendo el análisis de hábitos de equipo y bugs introducidos por IA que ningún analizador estático muestra.

Who this is for. Leaders running existing engineering teams. If you're starting a brand-new project, the developer cookbook covers that path. Three ways to run this: Para quién es esto. Líderes que manejan equipos de ingeniería existentes. Si estás empezando un proyecto totalmente nuevo, el recetario para desarrolladores cubre ese camino. Tres formas de correrlo:

What you'll get Qué obtendrás

at the end of the afternoon al final de la tarde

The conversation La conversación

~3-4 hours · brownfield only ~3-4 horas · solo código existente

Open your AI assistant — Claude Code, Cursor, VS Code with Copilot Chat, Aider, Windsurf — in the project root. Then walk through these steps. The assistant does the work; you direct. Abre tu asistente de IA — Claude Code, Cursor, VS Code con Copilot Chat, Aider, Windsurf — en la raíz del proyecto. Después camina estos pasos. El asistente hace el trabajo; tú diriges.

01
Scope the run. Pick one repo. Ideally not your largest, not your smallest — somewhere in the middle is the most informative. The audit runs on a new branch and never touches main, so risk is zero. Define el alcance. Escoge un repo. Idealmente no el más grande, no el más chico — algo en medio es lo más informativo. La auditoría corre en una rama nueva y nunca toca main, así que el riesgo es cero.
02
Run the audit. Paste this prompt: Corre la auditoría. Pega este prompt:
Paste this verbatimPega esto literalmenteUse PragmaWorks to audit this project for engineering leadership. Find pragmaworks on npm, install what you need, run the analysis on a new branch (don't touch main), and generate the initial report as both HTML and PDF. Cover: (1) the seven GS properties — Self-describing, Bounded, Composable, Verifiable, Auditable, Defended, Executable — each scored 0-2 with cited evidence and a concrete path to improve; (2) which structural disciplines apply to this codebase from the catalog (SOLID, TDD, hexagonal, layered, clean architecture) and how it scores against each; (3) documentation health and staleness; (4) test pyramid coverage; (5) security and logging baseline; (6) a prioritized remediation plan I can review before we apply anything. If this repo already has a CLAUDE.md, agents.md, or similar AI behavioral file, map your output to those locations rather than overriding them. Format the output for a manager-readable report.Usa PragmaWorks para auditar este proyecto para liderazgo de ingeniería. Busca pragmaworks en npm, instala lo que necesites, corre el análisis en una rama nueva (no toques main), y genera el reporte inicial como HTML y PDF. Cubre: (1) las siete propiedades de GS — Auto-descriptivo, Acotado, Componible, Verificable, Auditable, Defendido, Ejecutable — cada una puntuada 0-2 con evidencia citada y un camino concreto para mejorar; (2) qué disciplinas estructurales aplican a esta base desde el catálogo (SOLID, TDD, hexagonal, capas, clean architecture) y cómo puntúa contra cada una; (3) salud y desactualización de la documentación; (4) cobertura de la pirámide de pruebas; (5) baseline de seguridad y logging; (6) un plan de remediación priorizado que pueda revisar antes de aplicar nada. Si este repo ya tiene CLAUDE.md, agents.md, o archivo similar de comportamiento de IA, mapea tu output a esas ubicaciones en lugar de sobreescribirlas. Formatea el output como un reporte legible por un manager.
Show the pure-GS variant of this step (no tools)Mostrar la variante pura de GS de este paso (sin herramientas)

Same step without our orchestration. The leadership-grade audit is just a longer prompt — the rubric is fully nameable, which is what makes the result reproducible across two independent runs (the test for "is this an opinion or a measurement"). El mismo paso sin nuestra orquestación. La auditoría de calidad gerencial es solo un prompt más largo — la rúbrica es totalmente nombrable, que es lo que hace el resultado reproducible entre dos corridas independientes (la prueba de "¿esto es una opinión o una medición?").

Paste thisPega estoAudit this project for engineering leadership. Read the codebase, docs, tests, CI config, and git log. Produce a manager-readable markdown report at reports/audit-initial.md that I could hand a CTO or a board member without translation. Cover: (1) The seven Generative Specification properties, each scored 0/1/2 with cited file:line evidence and one specific path to improve: Self-describing, Bounded, Composable, Verifiable, Auditable, Defended, Executable. Score each on TWO independent passes and report any divergence — the rubric is reproducible only when two passes land within ±1. Where they don't, name the property and explain why the evidence is thin. (2) Which structural disciplines apply (SOLID, TDD, hexagonal, layered, clean architecture, CQRS, ports-and-adapters). Score each as applicable / partial / n-a with cited evidence. (3) Documentation health: stale (90+ days unchanged while code underneath shifted), missing, duplicated. (4) Test pyramid coverage: unit / integration / e2e ratios with the weakest layer flagged. (5) Security and logging baseline: secrets handling, input validation, audit trail, what's logged at the trust boundary. (6) Prioritized remediation plan: 8-15 items. For each: effort (S/M/L), risk (low/med/high), ordering rationale. Group as "this quarter" / "next quarter" / "won't fix unless triggered." Tone: direct, quantitative, no jargon without definition. The reader should not need to understand the codebase to act on the report. Open with a one-page executive summary; put the detail behind it. Do not apply any remediation in this pass.Audita este proyecto para liderazgo de ingeniería. Lee la base de código, docs, pruebas, config de CI, y git log. Produce un reporte markdown legible por un manager en reports/audit-initial.md que pudiera pasarle a un CTO o miembro del board sin traducción. Cubre: (1) Las siete propiedades de Especificación Generativa, cada una puntuada 0/1/2 con evidencia file:line citada y un camino específico para mejorar: Auto-descriptivo, Acotado, Componible, Verificable, Auditable, Defendido, Ejecutable. Puntúa cada una en DOS pasadas independientes y reporta cualquier divergencia — la rúbrica es reproducible solo cuando dos pasadas caen dentro de ±1. Donde no, nombra la propiedad y explica por qué la evidencia es delgada. (2) Qué disciplinas estructurales aplican (SOLID, TDD, hexagonal, capas, clean architecture, CQRS, ports-and-adapters). Puntúa cada una como aplicable / parcial / n-a con evidencia citada. (3) Salud de documentación: desactualizada (90+ días sin cambio mientras el código debajo se movió), faltante, duplicada. (4) Cobertura de pirámide de pruebas: ratios unit / integration / e2e con la capa más débil flageada. (5) Baseline de seguridad y logging: manejo de secretos, validación de input, audit trail, qué se loggea en el trust boundary. (6) Plan de remediación priorizado: 8-15 items. Para cada uno: esfuerzo (S/M/L), riesgo (bajo/med/alto), racionalidad de orden. Agrupa como "este trimestre" / "siguiente trimestre" / "no se arregla a menos que se dispare." Tono: directo, cuantitativo, sin jerga sin definición. El lector no debe necesitar entender la base de código para actuar sobre el reporte. Abre con un resumen ejecutivo de una página; pon el detalle detrás. No apliques remediación en esta pasada.

The PragmaWorks audit packages this with PDF rendering, the structural-discipline catalog, and continuity across runs. The prompt alone gets you a manager-grade report. La auditoría de PragmaWorks empaqueta esto con renderizado de PDF, el catálogo de disciplinas estructurales, y continuidad entre corridas. El prompt solo te da un reporte de calidad gerencial.

03
Review the initial report. The PDF tells you where the codebase is today. Score per property with cited evidence (so the rubric is reproducible — two independent runs land within ±1), structural-discipline assessment, the prioritized issue list. This is the document you can forward to peers — your CTO, your CEO, your board — without translation. Revisa el reporte inicial. El PDF te dice dónde está la base de código hoy. Puntaje por propiedad con evidencia citada (para que la rúbrica sea reproducible — dos corridas independientes caen dentro de ±1), evaluación de disciplinas estructurales, lista de issues priorizada. Este es el documento que puedes reenviar a tus pares — tu CTO, tu CEO, tu board — sin traducción.
04
Run the team-habit analysis. The most under-measured layer in modern engineering organizations. Paste: Corre el análisis de hábitos de equipo. La capa menos medida en organizaciones de ingeniería modernas. Pega:
Paste this verbatimPega esto literalmenteNow run the team-habit analysis on the last 90 days of commit history. Cover: PR review density, regression test coverage of bugs introduced, AI-introduced bug rate (detect commits with AI-assisted authorship signals and correlate with subsequent bug fixes), commit-size distribution, and collaboration graph across team members. Output as a separate PDF with charts.Ahora corre el análisis de hábitos de equipo en los últimos 90 días de historial de commits. Cubre: densidad de revisión de PRs, cobertura de pruebas de regresión de bugs introducidos, tasa de bugs introducidos por IA (detecta commits con señales de autoría asistida por IA y correlaciona con fixes posteriores de bugs), distribución de tamaño de commits, y gráfico de colaboración entre miembros del equipo. Output como un PDF separado con gráficas.

If your team has been using AI assistance for the last few months, the AI-bug rate chart is often the most useful single image you can show a leadership audience. It quantifies what you've suspected. Si tu equipo ha estado usando asistencia de IA los últimos meses, la gráfica de tasa de bugs por IA suele ser la imagen individual más útil que puedes mostrar a una audiencia de liderazgo. Cuantifica lo que ya sospechabas.

Show the pure-GS variant of this step (no tools)Mostrar la variante pura de GS de este paso (sin herramientas)

Same analysis computed directly from git log. The signals are visible to anyone with read access to the repo — our analyzer just packages them. Ask the AI to compute them and cite each git log query so a skeptic can reproduce. El mismo análisis computado directamente desde git log. Las señales son visibles para cualquiera con acceso de lectura al repo — nuestro analizador solo las empaqueta. Pídele a la IA que las compute y cite cada query git log para que un escéptico pueda reproducir.

Paste thisPega estoCompute team-habit signals from the last 90 days of git history. Produce a markdown report at reports/team-habits.md with these sections, each backed by the `git log` query you actually ran (cite the exact command in a footnote so I can reproduce): 1. PR review density. Ratio of commits that landed on main via a PR with at least one human reviewer comment vs commits that landed directly. Per-author breakdown. Flag authors below 0.5 and authors above 0.95 (no review vs over-review). 2. Regression test coverage. For each `fix:` commit, was a test added or modified in the same commit (look for files matching test/, *.test.*, *.spec.*, __tests__/)? Report the percentage and list the fix commits with no test added. This is the single best leading indicator of "are we calcifying our bugs." 3. AI-introduced bug rate. Identify commits authored with AI assistance signals: Co-Authored-By trailers naming Claude / Copilot / Cursor / Codeium, "🤖 Generated with" footers, distinctive commit-message patterns. For each, check whether a `fix:` commit referencing the same files landed within 14 days. Report the rate. List the commits. 4. Commit-size distribution. Histogram of changed lines per commit (buckets: 0-50, 51-200, 201-500, 501-1000, 1000+). Flag the long tail and name authors who appear in the 1000+ bucket repeatedly — large commits are where AI drift hides. 5. Collaboration graph. Who reviewed whom; who pairs on which modules. Build it from PR review participation; render as a markdown adjacency table with weights (number of PR reviews between each pair). For each metric include a one-line interpretation pitched at a manager: "PR review density of 0.62 means 38% of commits skipped human review — investigate or set a policy." End with three concrete next-step recommendations sized to a sprint. Keep the report under 2000 words.Computa señales de hábitos de equipo desde los últimos 90 días de historial de git. Produce un reporte markdown en reports/team-habits.md con estas secciones, cada una respaldada por la query `git log` que realmente corriste (cita el comando exacto en una nota al pie para que pueda reproducir): 1. Densidad de revisión de PRs. Ratio de commits que aterrizaron en main vía un PR con al menos un comentario de revisor humano vs commits que aterrizaron directamente. Desglose por autor. Flagea autores debajo de 0.5 y autores arriba de 0.95 (sin revisión vs sobre-revisión). 2. Cobertura de pruebas de regresión. Para cada commit `fix:`, ¿se agregó o modificó una prueba en el mismo commit (busca archivos que coincidan con test/, *.test.*, *.spec.*, __tests__/)? Reporta el porcentaje y lista los commits de fix sin prueba agregada. Este es el mejor indicador líder de "¿estamos calcificando nuestros bugs?" 3. Tasa de bugs introducidos por IA. Identifica commits autorados con señales de asistencia de IA: trailers Co-Authored-By nombrando Claude / Copilot / Cursor / Codeium, footers "🤖 Generated with", patrones distintivos de mensaje de commit. Para cada uno, chequea si un commit `fix:` referenciando los mismos archivos aterrizó dentro de 14 días. Reporta la tasa. Lista los commits. 4. Distribución de tamaño de commits. Histograma de líneas cambiadas por commit (buckets: 0-50, 51-200, 201-500, 501-1000, 1000+). Flagea la cola larga y nombra autores que aparecen en el bucket 1000+ repetidamente — los commits grandes son donde se esconde la deriva de IA. 5. Gráfico de colaboración. Quién revisó a quién; quién hace pair en qué módulos. Constrúyelo desde la participación en revisión de PRs; renderea como tabla de adyacencia markdown con pesos (número de revisiones de PR entre cada par). Para cada métrica incluye una interpretación de una línea pitched a un manager: "Densidad de revisión de PRs de 0.62 significa que 38% de los commits se saltaron la revisión humana — investiga o pon una política." Termina con tres recomendaciones concretas de siguiente paso dimensionadas a un sprint. Mantén el reporte debajo de 2000 palabras.

PragmaWorks renders these as charts in a PDF and tracks deltas across quarters. The prompt computes them once for a single read. PragmaWorks renderea estos como gráficas en un PDF y rastrea deltas entre trimestres. El prompt los computa una vez para una sola lectura.

05
Decide whether to remediate now. The initial report includes a remediation plan. You have three options: Decide si remediar ahora. El reporte inicial incluye un plan de remediación. Tienes tres opciones:
  • Apply now — proceed to step 6 in this session. Aplicar ahora — procede al paso 6 en esta sesión.
  • Bring back to your team — share the PDF, discuss in your next planning session, return when ready. Llevarlo a tu equipo — comparte el PDF, discútelo en tu siguiente sesión de planeación, regresa cuando estés listo.
  • Engage PragmaWorks for done-for-you remediation — for larger codebases or compliance-sensitive contexts, our concierge engagement handles the remediation for you. Contratar a PragmaWorks para remediación hecha-para-ti — para bases de código más grandes o contextos sensibles de compliance, nuestro engagement de concierge maneja la remediación por ti.
06
Apply the remediation plan (optional, this session). Paste: Aplica el plan de remediación (opcional, esta sesión). Pega:
Paste thisPega estoApply the top 5 items from the remediation plan on the same branch under GS discipline. For each item, generate the spec change first, then the code change, then the harness verification. Pause before any change that would touch the database schema or the public API — ask me first on those.Aplica los top 5 items del plan de remediación en la misma rama bajo disciplina GS. Para cada item, genera el cambio de spec primero, luego el cambio de código, luego la verificación con el harness. Pausa antes de cualquier cambio que toque el schema de base de datos o la API pública — pregúntame primero en esos.
07
Get the after-report. Once remediation is done, paste: Obtén el reporte antes/después. Una vez terminada la remediación, pega:
Paste thisPega estoGenerate the after-report. Same format as the initial one, but with a before/after comparison: coverage delta, structural discipline scores delta, GS rubric delta, regression tests added for past bugs, documentation updates. Include charts.Genera el reporte final. Mismo formato que el inicial, pero con una comparación antes/después: delta de cobertura, delta de puntajes de disciplinas estructurales, delta de la rúbrica GS, pruebas de regresión agregadas para bugs pasados, actualizaciones de documentación. Incluye gráficas.

This is the document you take to your next leadership review. It quantifies what changed, with receipts. Este es el documento que llevas a tu siguiente revisión de liderazgo. Cuantifica qué cambió, con recibos.

Optional — install Chronicle for organizational memory Opcional — instala Chronicle para memoria organizacional

Your team's AI sessions today are amnesiac: every new session starts from zero, re-learning what the last session figured out. Chronicle persists architectural decisions, prompt history, design rationale, and team conventions across sessions — so your team's collective discipline stops being lost between Mondays. Las sesiones de IA de tu equipo hoy son amnésicas: cada sesión nueva empieza desde cero, re-aprendiendo lo que la anterior averiguó. Chronicle persiste decisiones arquitectónicas, historial de prompts, racionalidad de diseño, y convenciones del equipo entre sesiones — para que la disciplina colectiva de tu equipo deje de perderse entre los lunes.

To install for the project: Para instalar en el proyecto:

Paste thisPega estoInstall Chronicle for this project so future sessions inherit the architectural decisions, the spec rationale, and the prompt history from this audit. Configure it to record team-level decisions, not just personal ones.Instala Chronicle para este proyecto para que las futuras sesiones hereden las decisiones arquitectónicas, la racionalidad de la spec, y el historial de prompts de esta auditoría. Configúralo para registrar decisiones a nivel de equipo, no solo personales.

For the team-wide version (Chronicle Team) that aggregates organizational memory across multiple repos and developers, that's part of the PragmaWorks Team subscription. juan@pragmaworks.dev for setup. Para la versión multi-equipo (Chronicle Team) que agrega memoria organizacional entre múltiples repos y desarrolladores, eso es parte de la suscripción PragmaWorks Team. juan@pragmaworks.dev para configurar.

Show the pure-GS variant of this step (no tools)Mostrar la variante pura de GS de este paso (sin herramientas)

Chronicle is a project-scoped persistent memory for AI sessions — what was decided, why, and what conventions emerged. You can self-document the same memory using only files in the repo. It's coarser than the tool, but the discipline travels. Chronicle es una memoria persistente con alcance de proyecto para sesiones de IA — qué se decidió, por qué, y qué convenciones emergieron. Puedes auto-documentar la misma memoria usando solo archivos en el repo. Es más burda que la herramienta, pero la disciplina viaja.

Paste thisPega estoSet up a pure-prompt persistent project memory without installing any tooling. The goal: the next AI session in this repo should inherit the architectural decisions, the audit findings, and the team conventions from this session. Create the following files: 1. .ai/memory/decisions.md — append-only log of architectural and organizational decisions. One entry per decision: date, decision, rationale, alternatives considered, who decided. Seed it with the decisions captured during this audit and remediation. 2. .ai/memory/conventions.md — team conventions extracted from the codebase: naming, file layout, error handling, logging format, test style, commit-message style. One section per convention, with a citation to a representative file:line. 3. .ai/memory/prompts.md — the prompts that drove this audit, the remediation plan, and the after-report. Future sessions can replay the relevant ones to re-establish context without me re-typing. 4. .ai/memory/glossary.md — domain terms with definitions. One line per term, anchored to where it first appears in the codebase. 5. CLAUDE.md (or AGENTS.md, or whatever convention this team uses) at the repo root. Short header that points future AI sessions at .ai/memory/ as their first read. List the four files above and what each contains. Three lines max per item. The session-end convention from now on: append any new decisions to decisions.md, any new conventions to conventions.md, and the session's notable prompts to prompts.md. Treat this as a non-negotiable closing step, the same way a doctor writes up rounds. Print a one-paragraph "what changed" summary so I can paste it into the team chat — that's the human handoff that the file convention on its own can't replace.Configura una memoria persistente del proyecto pura-de-prompt sin instalar ninguna herramienta. La meta: la siguiente sesión de IA en este repo debe heredar las decisiones arquitectónicas, los hallazgos de la auditoría, y las convenciones del equipo de esta sesión. Crea los siguientes archivos: 1. .ai/memory/decisions.md — log append-only de decisiones arquitectónicas y organizacionales. Una entrada por decisión: fecha, decisión, racionalidad, alternativas consideradas, quién decidió. Siémbralo con las decisiones capturadas durante esta auditoría y remediación. 2. .ai/memory/conventions.md — convenciones del equipo extraídas de la base de código: naming, layout de archivos, manejo de errores, formato de logging, estilo de pruebas, estilo de mensaje de commit. Una sección por convención, con una cita a un file:line representativo. 3. .ai/memory/prompts.md — los prompts que manejaron esta auditoría, el plan de remediación, y el reporte final. Las sesiones futuras pueden reproducir los relevantes para re-establecer contexto sin que yo re-teclee. 4. .ai/memory/glossary.md — términos del dominio con definiciones. Una línea por término, anclada a donde aparece primero en la base de código. 5. CLAUDE.md (o AGENTS.md, o la convención que use este equipo) en la raíz del repo. Header corto que apunta a las futuras sesiones de IA a .ai/memory/ como su primera lectura. Lista los cuatro archivos de arriba y qué contiene cada uno. Tres líneas máximo por item. La convención de cierre de sesión de aquí en adelante: agregar cualquier decisión nueva a decisions.md, cualquier convención nueva a conventions.md, y los prompts notables de la sesión a prompts.md. Trata esto como un paso de cierre no-negociable, igual que un doctor escribe sus rounds. Imprime un resumen de un párrafo "qué cambió" para que pueda pegarlo en el chat del equipo — ese es el handoff humano que la convención de archivos por sí sola no puede reemplazar.

Chronicle automates this loop, queries it semantically, and shares it across sessions and machines. The file convention gets you the discipline without the tool — sufficient for a single repo and a single contributor. Chronicle automatiza este loop, lo consulta semánticamente, y lo comparte entre sesiones y máquinas. La convención de archivos te da la disciplina sin la herramienta — suficiente para un solo repo y un solo contribuyente.

What this does not do. Domain expert review, real user testing, compliance sign-off, aesthetic and strategic decisions — the judgment layer remains yours. PragmaWorks ensures everything before the judgment layer is correct, so your team's judgment is spent only on what it alone can decide. We do the 90% you couldn't get to anyway. You still own the irreducible 10%. Lo que esto no hace. Revisión de experto de dominio, pruebas con usuarios reales, sign-off de compliance, decisiones estéticas y estratégicas — la capa de juicio sigue siendo tuya. PragmaWorks asegura que todo antes de la capa de juicio sea correcto, para que el juicio de tu equipo se gaste solo en lo que solo él puede decidir. Hacemos el 90% al que no llegabas de todas formas. Tú sigues siendo dueño del 10% irreducible.

Free for individuals running it on one repo. The audit and team-habit reports above are free for individual use. Multi-repo organizational dashboards, Chronicle Team, ongoing governance KPIs, and managed remediation are part of the paid Team and Enterprise tiers — see pricing. Gratis para individuos corriéndolo en un repo. La auditoría y los reportes de hábitos de equipo de arriba son gratuitos para uso individual. Dashboards organizacionales multi-repo, Chronicle Team, KPIs de gobernanza continuos, y remediación gestionada son parte de los tiers Team y Enterprise de paga — ver precios.

If you get stuck — or if you want a tech lead in the conversation Si te atoras — o si quieres un tech lead en la conversación

For technical questions during the run, your tech lead can take the conversation forward — the prompts above work the same way regardless of who's typing them. For audit interpretation, remediation scope, or a Concierge engagement to handle the work end-to-end, email me directly. Para preguntas técnicas durante la corrida, tu tech lead puede llevar la conversación — los prompts de arriba funcionan igual sin importar quién los teclea. Para interpretación de la auditoría, alcance de remediación, o un engagement de Concierge para manejar el trabajo end-to-end, escríbeme directamente.

juan@pragmaworks.dev →

For pricing, tiers, and the longer commercial walkthrough: pragmaworks.dev/teams Para precios, tiers, y el walkthrough comercial más largo: pragmaworks.dev/teams

Juan Carlos Ghiringhelli · PragmaWorks Labs LLC · ResourcesRecursos · Developer CookbookRecetario para Desarrolladores · Pricing & TiersPrecios y Tiers · forgeworkshop.dev