Darle capacidades

Lo que se construye: la API de guardia. Cuatro capacidades sobre infraestructura real: estado de una VM en Google Cloud, arrancarla, leer un registro DNS en Cloudflare, restaurarlo. Credenciales con mínimo privilegio, dentro de la API; quien la consume jamás las ve. Y un CLI, guardiactl, porque los operadores de esta API no van a ser solo humanos.

Requiere: proyecto GCP con una VM de laboratorio y una service account que solo pueda tocar esa máquina, y un token de Cloudflare que alcance una sola zona de laboratorio. El procedimiento de credenciales está en el runbook. Trabaja siempre desde un clon limpio en main: si tienes las ramas de solución bajadas en el clon, el agente las encuentra por git log y se salta el aprendizaje.

Parte A: el plan primero

1. Lee el issue #15. Es el peor especificado del repo, a propósito: “necesitamos poder ver y arreglar la infra desde el sistema, para no entrar a las consolas de cloud cada vez”. La tentación es tirárselo al agente. No.

2. Primer momento de subir de modelo (opcional): /model y elige el más grande que tengas. Para escribir código Sonnet sobra; para decidir arquitectura el modelo grande paga, porque este plan se hace una vez y condiciona todo lo que viene. Planifica caro, ejecuta barato (existe como configuración: opusplan). Luego /plan hasta ver “plan mode on”.

Lee el issue #15. NO implementes nada. Dame: las preguntas que le harías
al autor, criterios de aceptación medibles, componentes afectados, plan
por pasos con estrategia de tests, y riesgos con su rollback.

Resultado esperado: no toca código. Detecta que Terraform ya provisiona una VM y una identidad que ningún código usa (el alcance real es conectar lo que existe). Parte en fases: primero ver (solo lectura), después arreglar (acotado por allowlist). Devuelve preguntas al autor, criterios, componentes, riesgos con rollback. El plan queda guardado como archivo.

3. Aprobado el plan, /model y de vuelta a Sonnet: el plan caro ya está pagado.

Parte A: la construcción

4. Implementación con contratos fijos. El agente construye 20 a 40 minutos; déjalo. Cada capacidad con su test antes.

Implementa el plan aprobado del issue #15, fase por fase y con el test de
cada capacidad ANTES de su implementación. Contratos fijos: el CLI es
bin/guardiactl con subcomandos `vm status|start` y `dns get|restore`; las
mutaciones exigen --confirm; la API valida contra una lista permitida y
no existe operación de borrado. Al terminar cada fase, corre su test y
muéstrame el tick.

CAPACIDAD           GATE
1/4 estado VM       [ ]
2/4 arrancar VM     [ ]
3/4 leer DNS        [ ]
4/4 restaurar DNS   [ ]

Cuatro capas, cada una con su rol: la skill indica (propone y espera OK) · los permisos bloquean (allow lecturas, ask mutaciones) · guardiactl exige --confirm · la API valida (lista permitida, sin borrado).

Cuatro capacidades funcionando en local. ¿Terminado? Todavía no: “funciona en mi máquina” no es terminado. A eso vuelve el Capstone.

Parte B: la skill

Una skill es el manual operativo de tu herramienta, escrito para que un agente pueda descubrirla y usarla correctamente. Tres partes: cuándo usarla, cómo usarla, qué no hacer jamás. El consumidor nuevo de tu API es un agente, y a un agente no le das solo la documentación.

5. Escríbela:

Escribe la skill en .claude/skills/api-guardia/SKILL.md: cuándo usarla
(alertas o preguntas de estado de infraestructura), cómo (bin/guardiactl
vm status|start · dns get|restore; nunca gcloud ni la API de Cloudflare
directo), y sus límites: consultar es libre, las mutaciones requieren mi
aprobación explícita con --confirm, solo recursos de la lista permitida,
y un rechazo se reporta tal cual, no se rodea.

Detalle de diseño: una skill puede declarar herramientas preautorizadas en su encabezado. Es una comodidad, no una frontera de seguridad. Las restricciones reales van en el Nivel 7. Hoy se dejan fuera a propósito, para que se vea qué es instrucción y qué es permiso.

6. La prueba de fuego. Otra terminal en el mismo clon, claude, y escribe solamente:

la web del sistema está caída

Resultado esperado: sin que menciones la skill, la descubre por su descripción, la lee, consulta guardiactl vm status (la VM está detenida), propone bin/guardiactl vm start --confirm y se detiene a pedir aprobación. Apruebas, arranca la máquina a través de tu API, verifica y reporta con evidencia. Corre guardiactl desde el directorio del proyecto, sin cd adelante, o las lecturas piden permiso de más.

No le entregaste Google Cloud ni Cloudflare a Claude. Le entregaste una capacidad operativa, autenticada y auditable. Ya no escribes APIs solo para humanos: la skill es el contrato entre tu código y los agentes que lo van a operar.

Parte B½: generar infraestructura

Hasta acá el agente opera infraestructura que ya existía. También puede crearla, con las mismas reglas de un cambio de código: se escribe, se revisa el plan, se aprueba, recién ahí se aplica.

7. En la sesión principal:

La API de guardia necesita un lugar donde dejar sus reportes de estado
(exports JSON, poco volumen). Crea el recurso en la infraestructura del
repo: un bucket de Cloud Storage privado, siguiendo las convenciones del
Terraform existente en infra/environments/staging/. Escribe el archivo
.tf, corre fmt, validate y plan, y muéstrame el plan. NO ejecutes apply:
espera mi aprobación.

Resultado esperado: sigue las convenciones del Terraform existente (hasta las etiquetas), el bucket sale privado con acceso público bloqueado, y le da acceso solo a la identidad de la guardia, sin que se lo pidas. Si detecta drift (labels perdidas por un deploy manual), pregunta en vez de decidir. El plan de infraestructura es un diff, y ese diff delata la mano de un humano.

8. Aprobación:

Aprobado: aplica el plan completo. El drift de labels es nuestro,
restáuralo también. Después verifica que el bucket existe y muéstrame
la evidencia.

Resultado esperado: apply, y verificación con la CLI de Google de que el bucket existe. Destrúyelo después si no lo vas a usar.

Parte C: MCP y los ojos

La skill resuelve tus herramientas. Para las que no son tuyas (la base, el issue tracker, el navegador) existe MCP: un estándar abierto para que el agente se conecte a servicios vivos sin que tú seas el cable.

9. Los MCP cargan al iniciar la sesión, así que primero en la terminal, sin sesión abierta:

claude mcp add curso-db -e DATABASE_URI=postgresql://incidents:incidents@localhost:5432/incidents -- uvx --with "mcp==1.12.0" postgres-mcp --access-mode=restricted

Lección del pin de versión: fijar dependencias también aplica a las herramientas del agente. El servidor elegido es postgres-mcp en modo restricted (solo lectura a nivel de transacción); el servidor oficial viejo está archivado por una inyección SQL.

Si la base está vacía, siembra tres incidentes:

docker compose -f deploy/compose/docker-compose.yml exec -T db psql -U incidents -d incidents -c "INSERT INTO incidents (fingerprint, source, title, body, status, created_at) VALUES ('f1','monitor','Web caida','','new', now() - interval '3 days'), ('f2','monitor','DNS intermitente','','new', now() - interval '1 day'), ('f3','monitor','VM reiniciada','','done', now() - interval '2 days');"

10. Abre claude, aprueba el servidor cuando lo pida, /mcp para verlo conectado, y la pregunta:

¿Cuántos incidentes hay en estado 'new' y cuál es el más antiguo?

Resultado esperado: va a la base por MCP y responde con el dato real (dos abiertos, el más antiguo la web caída). Sin copy-paste, sin cliente SQL.

11. Los ojos. Claude Code se conecta a tu navegador Chrome (extensión + claude --chrome; requiere login de claude.ai). Levanta la API en otra terminal (docker compose -f deploy/compose/docker-compose.yml up -d api; la interfaz es el Swagger en http://localhost:8000/docs), abre una sesión con claude --chrome y pega, agregando la URL:

Abre la interfaz del sistema de incidentes en el navegador
(http://localhost:8000/docs) y verifica que la lista cargue y el
formulario cree un incidente de prueba.

Resultado esperado: navega la app, interactúa, reporta lo que ve. “Creo que se ve bien” pasa a “lo vi funcionando”.

El criterio: qué mecanismo para qué

Diseña para agentes: no conviertas tu API REST a MCP uno a uno. Menos herramientas con descripciones claras le ganan a cincuenta tools genéricas.

Comandos desbloqueados

• Plan Mode (/plan, o rotar modos con Shift+Tab) · planear sin tocar nada; tú apruebas antes de que actúe.
• Skills (.claude/skills/<nombre>/SKILL.md) · procedimientos descubribles por descripción.
• MCP (claude mcp add, /mcp) · servicios vivos.
• Navegador Chrome (claude --chrome, /chrome) · los ojos.

Backlog: ítem 2 con contrato construido, falta desplegarlo de verdad. Marcador: autonomía sube (opera herramientas) · control sube (bajo contrato).