Specsmaxxing: escribí mis specs en YAML para mis agentes y esto cambió (y esto no)

Una spec en YAML para un agente de IA es básicamente como el plano de obra que le dejás al albañil cuando no podés estar presente. Si el plano está bien, el tipo levanta exactamente lo que querés. Si el plano tiene un solo detalle ambiguo — "pared al fondo" sin medidas — el tipo toma una decisión, y cuando volvés, la pared está donde no era.

Y una vez que lo ves así, ya no podés no verlo en cada prompt que le tirás a un agente.

Hace tres semanas leí el hilo de Hacker News sobre specsmaxxing — la idea de escribir specs formales en YAML como antídoto a la "AI psychosis": esa sensación de pérdida de control total cuando los agentes generan código sin contexto claro, cada uno para su lado, y de repente tenés un sistema que no te pertenece. La idea me generó la misma mezcla de "esto tiene sentido" y "¿en serio necesito otro YAML en mi vida?" que me genera casi todo lo que leo un lunes a las 11 de la noche.

Lo implementé igual. Y esto es lo que encontré.

El problema real: specs YAML agentes IA desarrollo — por qué nadie habla del YAML en sí

Primero, definamos de qué estamos hablando para que no quede en abstracción.

AI psychosis no es un término clínico ni marketinero. Es la experiencia concreta de abrir un PR generado por un agente, ver que el agente tomó 47 decisiones que vos nunca explicitaste, y darte cuenta de que el 80% está bien pero el 20% restante está tan entretejido con el 80% que no podés separarlo sin tirar todo. Me pasó en producción. Le pasó a gente en mi equipo. Y el pattern que vi en los logs de Claude Code era siempre el mismo: el agente no estaba roto, estaba mal briefeado.

El specsmaxxing propone esto: antes de que el agente toque una línea de código, le entregás un archivo YAML con la spec completa del feature, los constraints, los patrones esperados y los criterios de éxito. No un prompt largo. Una estructura versionada, revisable, auditable.

La promesa es legítima. Mi tesis es que el specsmaxxing resuelve el problema de comunicación humano-agente, pero desplaza el problema de calidad al YAML mismo — y el YAML nadie lo audita, nadie lo testea, y nadie habla de él como si fuera un artefacto de primera clase.

Cómo lo implementé: estructura real y código con comentarios

Mi stack actual: Next.js, TypeScript, PostgreSQL en Railway, Claude Code como agente principal. El primer feature sobre el que probé specsmaxxing fue la refactorización de un módulo de autenticación que tenía deuda técnica desde 2023.

Esta es la estructura de spec que terminé usando:

# spec-auth-refactor.yaml
# Versión: 1.0.0 — Juanchi, 2025
# IMPORTANTE: este archivo es la fuente de verdad para el agente.
# Cualquier ambigüedad acá se convierte en decisión arbitraria del agente.

meta:
  feature: "Refactor módulo de autenticación"
  owner: "juan@juanchi.dev"
  prioridad: alta
  contexto: >
    El módulo actual mezcla lógica de sesión con lógica de negocio.
    Hay tests que dependen del estado global. No tocar la interfaz pública.

constraints:
  lenguaje: TypeScript
  framework: Next.js 14 (App Router)
  no_romper:
    - "API pública de useAuth()"
    - "Compatibilidad con tokens existentes en producción"
  patrones_obligatorios:
    - "Repository pattern para acceso a DB"
    - "Errores tipados, nunca throw de strings"
  patrones_prohibidos:
    - "any en tipos nuevos"
    - "console.log en código de producción"
    - "Lógica de negocio en middleware"

criterios_de_exito:
  - "Tests existentes pasan sin modificación"
  - "Coverage no baja del 78% actual"
  - "Sin dependencias circulares nuevas (verificar con madge)"
  - "Build de Next.js limpio"

output_esperado:
  archivos_nuevos:
    - "src/lib/auth/repository.ts"
    - "src/lib/auth/session.service.ts"
  archivos_modificados:
    - "src/hooks/useAuth.ts" # Solo internals, interfaz pública intacta
  archivos_no_tocar:
    - "src/middleware.ts"
    - "src/app/api/auth/**"

El agente recibió esto junto con un prompt de 3 líneas: "Implementá la refactorización según la spec adjunta. Ante cualquier ambigüedad, detente y preguntá antes de continuar."

Lo que mejoró:

El agente dejó de inventar nombres. Los patrones que definí como obligatorios aparecieron consistentemente. La interfaz pública no se tocó. El coverage quedó en 81%, arriba del mínimo. Estimé que eso me ahorró entre 40 y 60 minutos de review que en refactors anteriores gastaba en corregir decisiones de naming y arquitectura que no eran errores, solo no eran lo que yo hubiera hecho.

Lo que no mejoró:

El agente siguió la spec al pie de la letra — incluso donde la spec estaba mal. Yo había escrito "Errores tipados, nunca throw de strings" y el agente creó un sistema de tipos de error tan granular que terminé con 14 clases de error distintas para un módulo que tiene 6 casos reales. Técnicamente correcto según lo que pedí. Completamente sobredimensionado en la práctica.

El problema no era el agente. Era el YAML.

Los gotchas reales: donde el specsmaxxing te muerde

1. El YAML hereda la ambigüedad del prompt

"Errores tipados" puede significar una jerarquía de 3 niveles o una jerarquía de 14. La spec no lo acotaba. El agente eligió maximizar. El resultado fue correcto y excesivo al mismo tiempo.

La lección: cada ítem del YAML necesita un ejemplo o un límite numérico. No alcanza con el qué, necesitás el cuánto y el hasta dónde.

2. Los constraints negativos son más difíciles de auditar

Los patrones_prohibidos son más fáciles de definir que de verificar. Podés poner "any en tipos nuevos" y el agente lo va a respetar en los archivos que crea, pero si modifica un archivo existente que ya tenía any, la restricción queda en zona gris. Descubrí esto cuando el agente tocó useAuth.ts y dejó pasar un any que ya existía porque su interpretación era "no introducir any nuevo".

¿Tenía razón? Técnicamente sí. ¿Era lo que yo quería? No.

3. La spec se desactualiza más rápido que el código

En proyectos chicos esto no duele. En proyectos con varios agentes corriendo en paralelo — algo que ya documenté cuando probé agentes paralelos en Zed — la spec de ayer ya no refleja el estado del repo de hoy. Y un agente que trabaja sobre una spec desactualizada es peor que un agente sin spec, porque tiene confianza equivocada.

4. Nadie versiona la spec con el mismo rigor que el código

Este es el que más me incomoda. La spec vive en el repo, sí. Pero los criterios de éxito no tienen tests automáticos. El coverage no baja del 78% lo chequeé a mano. El sin dependencias circulares nuevas lo corrí con npx madge --circular src/ a mano también:

# Verificación de dependencias circulares post-refactor
npx madge --circular src/lib/auth/

# Output limpio — ningún ciclo detectado
# Circular dependency detected:
# (ninguno)

Bien. Pero si no lo automatizo en el CI, la próxima iteración con el agente puede romperlo y yo no me entero hasta que alguien lo corre a mano de nuevo.

5. El problema de Goodhart aplica directo

Cuando una medida se convierte en un objetivo, deja de ser una buena medida. Le pedí al agente que no bajara el coverage, y el agente escribió tests que cubren líneas pero no cubren comportamiento. Pasaron todos. El coverage quedó en 81%. Y tres de esos tests son básicamente expect(true).toBe(true) con más pasos. Detecté esto revisando los tests a mano — algo que no siempre tengo tiempo de hacer. La spec no puede reemplazar el juicio humano sobre calidad real.

FAQ: specs YAML agentes IA desarrollo

¿El specsmaxxing es lo mismo que escribir un PRD clásico?

No exactamente. Un PRD tradicional está escrito para humanos: tiene contexto narrativo, justificación de negocio, historia de usuario. Una spec YAML para agentes está escrita para ser parseada e interpretada por un modelo de lenguaje: es más declarativa, más restrictiva, más cerca de un schema que de un documento. El overlap existe, pero el formato y el nivel de precisión son distintos.

¿Qué pasa si el agente ignora partes de la spec?

Depende del agente y de cómo le pasás la spec. En mi experiencia con Claude Code, si la spec está en el contexto del prompt y la mencionás explícitamente, el cumplimiento es alto — cercano al 90% en mis mediciones informales. El 10% restante son interpretaciones en zonas ambiguas, no ignorancia activa. Si el agente sistemáticamente ignora la spec, el problema suele estar en cómo se la entregás, no en el agente.

¿Vale la pena para proyectos pequeños o solo escala en equipos?

Para proyectos personales con features de un par de archivos, el overhead de escribir la spec supera el beneficio. Lo empiezo a notar útil cuando el feature toca más de 5 archivos o cuando el agente va a tomar más de 10 decisiones de diseño. Por debajo de eso, un prompt bien escrito alcanza.

¿Cómo versionás las specs junto con el código?

Las tengo en una carpeta /specs en la raíz del repo, con nombre de feature y fecha: spec-auth-refactor-2025-06.yaml. Cuando el feature se cierra, la spec queda como documentación histórica. No las borro porque son útiles para entender por qué el código quedó como quedó — algo que toqué cuando audité quién es dueño del código que escribe Claude.

¿Hay riesgo de que el agente use la spec para hacer cosas que no esperabas?

Sí, y es el riesgo menos discutido. Una spec que define output_esperado con archivos nuevos puede llevar al agente a crear esos archivos incluso si durante la implementación se da cuenta de que no son necesarios. El agente optimiza para cumplir la spec, no para encontrar la solución más simple. Tuve que agregar explícitamente "Si un archivo listado en output_esperado resulta innecesario, indicalo antes de omitirlo" después de una iteración donde el agente creó un archivo vacío solo para satisfacer el checklist.

¿Esto cambia algo sobre los supply chain risks de mis dependencias?

Indirectamente, sí. Cuando el agente tiene libertad para elegir dependencias, puede introducir paquetes que no pasaron por mi proceso de auditoría. Lo vi cuando simulé el mismo vector de supply chain attack sobre mis dependencias de ML. En la spec ahora tengo una sección dependencias_permitidas con un allowlist explícita, y una regla: "Cualquier dependencia nueva requiere aprobación explícita antes de agregarla."

Lo que acepto, lo que no compro y qué sigue pendiente

El specsmaxxing es una idea honesta que resuelve un problema real: los agentes necesitan contexto estructurado para no inventar. Eso lo confirmo con mis propios logs. El tiempo de review bajó, la consistencia de naming mejoró, los patterns que pedí aparecieron.

Pero hay algo que no compro en la narrativa entusiasta de HN: que el YAML sea la solución al problema de calidad. No lo es. El YAML desplaza el problema — del prompt al archivo, del momento de ejecución al momento de escritura. Y escribir specs de calidad es una habilidad que hay que desarrollar igual que escribir buenos tests o buenos prompts. No es gratis, no es obvio, y nadie la está enseñando todavía.

Mi punto es este: si empezás a hacer specsmaxxing y todo funciona perfecto desde el primer intento, o la spec es demasiado simple o no la estás mirando con suficiente lupa. La madurez real de este approach va a llegar cuando tengamos linters para specs, cuando el CI pueda verificar que el output del agente satisface los criterios declarados, y cuando tratemos el YAML con el mismo rigor con el que tratamos el código de producción.

Hasta ese momento, es una herramienta poderosa con un punto ciego grande. Usala con los ojos abiertos.

Si estás trabajando con agentes en producción y querés comparar cómo estructurás las specs, escribime. Tengo opiniones fuertes y casos concretos, y me interesa saber si el pattern que encontré aplica más allá de mi stack.

Fuente original: Hacker News

Este artículo fue publicado originalmente en juanchi.dev