ATLAS + GOTCHA -- Parte 10

Un Generador de Scaffolding para Claude — Construido sobre los Siete Invariantes de Gartner

#claude-code #scaffolding #seguridad #governance #gartner #atlas #gotcha #hooks

El Problema

Empiezas un proyecto nuevo con Claude. Abres una carpeta, escribes claude, y le pides que construya algo. Claude está encantado de ayudar. Demasiado encantado.

En los primeros 20 minutos tienes:

  • Un package.json creado con npm init (querías pnpm)
  • Un terraform apply ejecutado contra tu suscripción de dev (no autorizaste eso)
  • Un commit firmado con “Co-Authored-By: Claude” (tu empresa lo prohíbe)
  • Una API key hardcodeada en appsettings.json porque “es solo para pruebas”
  • Una storage account con allow_blob_public_access = true porque la IA lo vio en una respuesta de stack overflow de 2019
  • Cero tests, porque no los pediste

Cada una de estas cosas es pequeña. Juntas, son la razón por la que tu equipo de seguridad bloquea las herramientas de IA.

La solución no es “ten cuidado”. La solución es hacerlo imposible. No para Claude — para el proyecto. Desde el primer fichero.

La Solución

He construido scaffold-generator, un repo público en GitHub que hace una sola cosa: genera la estructura de un proyecto nuevo con todos los guardrails ya instalados.

No es un template. No es un starter kit. Es una entrevista determinista. Abres el repo con Claude, y Claude te hace preguntas — una a una — sobre qué quieres construir. Stack tecnológico, arquitectura, requisitos, plataforma de CI/CD, metodología ATLAS+GOTCHA. Entonces, y solo entonces, genera el scaffolding.

El scaffolding incluye:

  • Un CLAUDE.md con las reglas de tu proyecto específico
  • 14 hooks en .claude/hooks/ que bloquean acciones peligrosas antes de que lleguen al disco
  • Un documento governance.md con los siete invariantes que todo artefacto debe pasar
  • Pipelines de CI/CD para tu plataforma (GitHub Actions, GitLab CI, o Azure DevOps)
  • Una estructura completa de .NET Clean Architecture (o React, o Terraform, según tus respuestas)
  • Tests reales generados — no stubs

La entrevista importa. Claude no asume cosas. Pregunta. Si no sabes una respuesta, te da opciones. Si das una respuesta vaga, te pide más detalle. El objetivo es: ninguna decisión de diseño tomada por la IA sin tu consentimiento.

Dónde encaja Gartner

Esto no es algo inventado. La arquitectura sigue la nota de investigación de Gartner How to Govern Anthropic’s Claude Code at Scale (G00850426, marzo 2026). Gartner define siete invariantes que todo artefacto generado por IA debe cumplir:

#InvarianteQué significa
1FuncionalImplementa la spec, pasa análisis estático y contract tests
2TesteadoTests unit + integration + E2E, ≥75% de coverage
3SeguroSin secretos, sin CVEs, sin findings de SAST, sin flujos inseguros
4EscalableSin queries N+1, I/O asíncrono, handlers idempotentes
5PerformanteCumple el budget de latencia P95, sin regresiones
6ObservableLogs estructurados, métricas, trazas desde el día uno
7AuditableConventional commits, SBOM, artefactos firmados, linaje de prompts

Y tres checkpoints donde estos invariantes deben aplicarse:

  1. Generación — Los hooks de Claude bloquean acciones malas mientras se escribe el fichero
  2. Pre-commit / pre-push — Los git hooks corren las mismas comprobaciones antes de que el código salga de tu máquina
  3. Pipeline de CI/CD — El pipeline las corre otra vez, con la misma configuración

Las mismas herramientas en cada checkpoint. Saltarse cualquiera crea un hueco explotable.

La mayoría de los equipos se quedan en el pipeline de CI. Para cuando el pipeline caza un secreto hardcodeado, el secreto ya está en el historial de git. El sentido de aplicar las reglas en tiempo de generación es no permitir nunca que el código malo exista en primer lugar.

Execute

Pre-flight checklist antes del despegue — todas las preguntas respondidas antes de que el proyecto empiece

Vamos a ver qué hay realmente dentro del repo.

El flujo de la entrevista

Cuando abres el repo y le pides a Claude que genere un proyecto, sigue goals/scaffold.md. Lo primero que hace es detectar tu idioma. Si escribes en español, la entrevista entera es en español. Si cambias a inglés a mitad, también cambia.

Después pregunta, en orden:

Fase 1 — Identidad del Proyecto
  Q1: Nombre del proyecto (PascalCase)
  Q2: Descripción (1-2 frases)

Fase 2 — Requisitos
  Q3: Descripción de la arquitectura
  Q4: Requisitos funcionales
  Q5: Requisitos no funcionales

Fase 3 — Tipo de Proyecto
  Q6: ¿Web, móvil, infra, API, o combinaciones?

Fase 4 — DevOps
  Q7: ¿GitHub, GitLab, o Azure DevOps?
  Q8: Plataforma de issue tracking

Fase 5 — Metodología
  Q9: ¿Aplicar ATLAS + GOTCHA + SDD?

Solo cuando confirmas con “SÍ” empieza la generación. El orden de generación también es determinista — los ficheros se crean en una secuencia específica para que las dependencias siempre existan cuando algo las referencia.

Los hooks que te protegen

Hooks cazando acciones peligrosas antes de que lleguen al disco

Dentro de .claude/hooks/ hay 14 scripts de shell. Cada uno se dispara en llamadas específicas de Claude (Write, Edit, Bash) e inspecciona qué está a punto de pasar. Si algo parece mal, el hook bloquea la acción y le dice a Claude por qué.

Aquí va una muestra:

# block-secrets.sh — se dispara en Write/Edit
# Bloquea AWS keys, GitHub PATs, Azure connection strings,
# private keys, passwords hardcodeadas, JWTs en código fuente

PATTERNS=(
    'AKIA[0-9A-Z]{16}'                          # AWS Access Key
    'ghp_[A-Za-z0-9]{36}'                       # GitHub PAT
    'AccountKey=[A-Za-z0-9+/=]{40,}'            # Azure storage
    '-----BEGIN (RSA |EC |OPENSSH )PRIVATE KEY-----'
    '(password|passwd|pwd)[[:space:]]*[:=][[:space:]]*["\x27][^"\x27]{6,}["\x27]'
)

O este, que bloquea el error más caro de Terraform — una storage account pública:

# block-tf-public-exposure.sh — se dispara en Write/Edit para ficheros *.tf
declare -a PATTERNS=(
    '0\.0\.0\.0/0'
        "CIDR abierto (0.0.0.0/0). Restringir a rangos conocidos."
    'public_network_access_enabled[[:space:]]*=[[:space:]]*true'
        "Usar private endpoints en su lugar."
    'allow_blob_public_access[[:space:]]*=[[:space:]]*true'
        "El storage debe ser privado."
    'min_tls_version[[:space:]]*=[[:space:]]*"TLS1_0"'
        "TLS1_0 está deprecated. Usar TLS1_2 mínimo."
    'skip_final_snapshot[[:space:]]*=[[:space:]]*true'
        "Los datos de producción deben tener snapshot."
)

La lista completa de hooks:

HookQué bloquea
block-npm.shCualquier npm install / npm run — solo pnpm
block-git-push.shgit push sin autorización explícita del usuario
block-terraform-apply.shterraform apply desde tu portátil — solo pipelines
block-no-verify.shgit commit --no-verify — arregla el hook, no lo saltes
block-claude-attribution.shCo-Authored-By: Claude en commits
block-destructive-actions.shrm -rf, comandos destructivos de az CLI
block-secrets.shCredenciales hardcodeadas en cualquier fichero
block-tf-public-exposure.shStorage público, CIDRs abiertos, TLS débil en Terraform
enforce-invariants.shFicheros que violan los siete invariantes
enforce-tf-policy.shTerraform sin tags, naming, encryption requeridos
provenance-stamp.shSella cada generación con el linaje del prompt
require-tests.shEl código de producción en Domain/Application/Api necesita tests
require-tf-module-tests.shLos módulos de Terraform necesitan una carpeta tests/
require-tf-tags.shTodos los recursos de Azure necesitan tags

Estos no son sugerencias. Se ejecutan automáticamente. Si Claude intenta escribir un fichero que viola cualquiera de ellos, el hook sale con código de error y Claude ve el mensaje y lo intenta otra vez.

Cómo es el CLAUDE.md generado

Después de la entrevista, el proyecto generado tiene su propio CLAUDE.md. Incluye todos los guardrails más las decisiones específicas que tomaste:

# CLAUDE.md — QuantumApi

## Qué Es Este Proyecto
Una REST API para gestionar claves de cifrado post-cuántico.
Construida con .NET 10 Clean Architecture, PostgreSQL, desplegada
en Azure vía GitHub Actions.

## Stack Tecnológico
- Backend: .NET 10 (Domain / Application / Infrastructure / Api)
- Base de datos: PostgreSQL 16
- Auth: Entra ID
- Hosting: Azure Container Apps
- IaC: Terraform
- CI/CD: GitHub Actions

## Metodología
ATLAS + GOTCHA + SDD aplicado a todas las features

## Coverage
75% mínimo, 80% objetivo — aplicado en CI

## Guardrails (aplicados por hooks)
- Solo pnpm (block-npm.sh)
- No git push sin autorización (block-git-push.sh)
- No terraform apply localmente (block-terraform-apply.sh)
- Sin atribución a Claude (block-claude-attribution.sh)
- ... (la lista completa)

Este fichero es lo primero que Claude lee en cualquier conversación nueva. Así que cada futura sesión en ese proyecto empieza con las reglas ya cargadas.

El registro de linaje de prompts

Esta es la parte de la que estoy más orgulloso. Cada vez que Claude genera un fichero, el hook provenance-stamp.sh escribe una entrada en .claude/provenance/<fecha>.jsonl. La entrada contiene:

  • El prompt exacto que disparó la generación
  • El modelo y la versión usados
  • La ruta del fichero que se creó o modificó
  • Un hash SHA-256 del contenido
  • El timestamp

Esto es tu audit trail. Dentro de seis meses, cuando alguien pregunte “¿por qué existe esta función?”, puedes responder: “porque el 9 de abril, el usuario pidió X, y Claude generó este fichero como respuesta, y aquí tienes el hash que demuestra que no ha cambiado desde entonces”.

Este es el invariante número 7 — Auditable — y es el que la mayoría de los equipos olvida.

Template

Aquí va el mínimo que necesitas para usarlo en tu próximo proyecto. Sin clonar, sin trucos de git, sin setup. Solo abre la carpeta del proyecto con Claude y pídeselo:

# 1. Abre la carpeta de scaffold-generator
cd ruta/a/scaffold-generator

# 2. Arranca Claude
claude

Después di, en el idioma que quieras: “Quiero crear un proyecto nuevo.”

Claude detectará tu idioma, anunciará la entrevista, y empezará a hacer preguntas. No te saltes pasos. No digas “usa los valores por defecto”. El objetivo es que tú tomes las decisiones, y Claude las documente.

Cuando la entrevista termine, Claude te muestra un resumen. Si todo se ve bien, respondes con “SÍ” y empieza la generación. Los hooks ya están activos — lo estaban desde el momento en que abriste Claude en esa carpeta, porque .claude/settings.json los registró.

Si quieres verificar que los hooks funcionan antes de generar nada, pídele a Claude que escriba un fichero con una AWS key falsa. Se negará — y el mensaje de error vendrá de block-secrets.sh, no de las buenas intenciones de Claude.

Reto

Pruébalo en un proyecto real:

  1. Clona el repo scaffold-generator
  2. Elige una idea pequeña — una API de TODOs, un tracker de gastos personales, un script que lee RSS
  3. Pasa por la entrevista de principio a fin (sí, todas las preguntas)
  4. Mira el proyecto generado y cuenta: ¿cuántas decisiones tomó Claude por su cuenta?

La respuesta debería ser cero. Cada nombre de carpeta, cada versión de paquete, cada step de CI, cada tag de Terraform — todo vino de tus respuestas. Eso es lo que parece el desarrollo con IA gobernable.

Y luego prueba los hooks. Intenta hacer commit de una password hardcodeada. Intenta ejecutar npm install. Intenta escribir un fichero de Terraform con 0.0.0.0/0. Mira qué pasa.

El repo es público, con licencia MIT. Úsalo, haz fork, manda PRs. Si tu equipo tiene un guardrail que me he dejado, abre un issue — quiero añadirlo.

Si este artículo te ayuda, considera patrocinarme en GitHub o invitarme a un café.

Este es un artículo independiente. Si quieres aprender la estructura de prompts que ATLAS + GOTCHA + SDD usan para guiar estas generaciones, empieza con la serie ATLAS + GOTCHA. Si quieres ver cómo el mismo modelo de governance se aplica a un Internal Developer Platform completo, la serie AI-Native IDP lo recorre de principio a fin.

Comments

Loading comments...