Cómo Crear una Especificación Técnica Efectiva para Claude

Introducción

Poca gente habla de esto en voz alta: usar a Claude sin método es como dar un GPS a alguien que no sabe leer mapas. Te lleva rápido. Te deja en medio de la nada.

Descubrí algo curioso trabajando con equipos: los proyectos con mejor documentación no son los más lentos. Son los que sobreviven. Y con IA, la supervivencia depende de tu habilidad para traducir intuiciones en contratos técnicos claros. Claude puede ser el mejor compañero para eso —si sabes cómo pedirle las cosas.

Esto no es un manual académico. Es un plan para usar Claude y salir del “hacer que funcione” hacia “hacer que dure”.

Guía paso a paso

1) Empieza por el porqué, no por el cómo

No le sueltes al modelo: “Hazme el CRUD.” Suéltale: “Esto existe porque…”

Explica el negocio en 3–5 frases. Quién usa el producto. Qué métricas importan. Qué es un éxito y qué es un fallo. Claude necesita entender el valor antes de diseñar la estructura. Si no sabe el porqué, propondrá soluciones bonitas que no resuelven nada real.

2) Brain dump: vacía la cabeza en orden

Haz un volcado de contexto. Todo. Usuarios, roles, integraciones, datos sensibles, presupuestos, deadlines. Todo en bruto. Luego organízalo en secciones:

• Objetivo del producto.
• Requisitos no negociables.
• Integraciones externas.
• Restricciones de coste o tiempo.

Si no lo pones por escrito, la IA lo “olvidará” cuando la conversación crezca. La ventana de contexto es grande, pero limitada. La spec fija el rumbo.

3) Define límites claros: el terreno de juego

Un LLM sin límites propone arquitectura épica. Kubernetes para un formulario. Event Sourcing para un blog. Fija el stack y las reglas: Next.js o Angular, Postgres o Mongo, monolito o microservicios. Di lo que está permitido y lo que está prohibido.

Esto no es control por control. Es evitar decisiones peligrosas. Cuanto más concreto seas, más útiles serán las propuestas de Claude.

4) Usa a Claude como auditor: Red Teaming

Hazle preguntas desagradables. Pídele que rompa el diseño.

“Si la base de datos recibe 10k req/s, ¿qué falla?”

“¿Qué pasa si el OAuth provider devuelve 500 por 30 segundos?”

“Describe tres formas en que esto puede ser explotado.”

Pedir a Claude que actúe como Staff Engineer es oro. Suele encontrar cuellos de botella y escenarios que no ves en la primera pasada.

5) Pide un Plan Técnico Estructurado (no un ensayo)

No le pidas “un diseño”. Pide un plan accionable y dividido en entregables. Que incluya:

• Arquitectura general (componentes y responsabilidades).
• Modelos de datos (tablas o colecciones, relaciones).
• Contratos de API (endpoints, métodos, payloads).
• Reglas de seguridad y manejo de secretos.
• Estrategia de testing y despliegue.
• Checklist de aceptación.

Exige formatos concretos: interfaces TypeScript, OpenAPI, diagramas Mermaid. Claude los produce con disciplina si se lo pides.

6) Prompt maestro: estructura rígida para resultados deterministas

Empaqueta la solicitud final con bloques semánticos. Ejemplo sencillo que Claude entiende bien:

<contexto_negocio>
Resumen del problema en 3–5 frases.
</contexto_negocio>

<stack_requerido>
Frontend: Next.js 14. Backend: Node 20. DB: PostgreSQL 15.
</stack_requerido>

<restricciones>
Monolito. No sugerir microservicios. Cumplir GDPR.
</restricciones>

<output_esperado>
Markdown con: arquitectura, modelos TypeScript, OpenAPI y Mermaid.
</output_esperado>

Sí: usa algo parecido. Claude procesa estructura. Evita “hazme algo bueno” y usa “hazme esto exacto”.

7) Itera en pequeños pasos: divide para conquistar

No le pidas “termina todo en un prompt”. Divide el plan en fases:

• Fase 1: Modelo de datos y contratos.
• Fase 2: Endpoints principales + seguridad.
• Fase 3: Estrategia de despliegue y observabilidad.

Aprueba cada fase antes de avanzar. Así mantienes coherencia y controlas la complejidad.

8) Genera pruebas desde el principio

Pide a Claude que escriba tests de aceptación junto al contrato. Un endpoint sin test es un contrato sin firma.

Solicita ejemplos de payloads válidos e inválidos. Solicita tests automáticos que fallen si no cumples las reglas. Así la implementación se vuelve una verificación automática del plan.

9) Convierte la spec en artefactos machine-readable

No dejes todo en texto. Pide:

• OpenAPI / Swagger.
• Esquema DB (SQL o Prisma).
• Interfaces TypeScript.
• Mermaid para diagramas.

Estos artefactos alimentan la fase de implementación y reducen la ambigüedad cuando uses Copilot o agentes de coding.

10) Añade reglas de guardia: políticas y anti-patrones

Incluye en la spec lo que NO se debe hacer. Ejemplos útiles:

• No exponer tokens en el frontend.
• No usar dependencias sin CVE review.
• Todas las APIs deben ser idempotentes.
• Tiempo máximo de respuesta: 500ms en endpoints críticos.

La IA responde bien a instrucciones negativas si las formulas claras.

11) Implantación práctica: .cursorrules y SPEC.md

Pon la spec en el repo. No escondas nada en Google Docs. Dos archivos mínimos:

• SPEC.md: objetivo, reglas, contratos, checklist de aceptación.
• .cursorrules (o el archivo que tu herramienta use): reglas automáticas consumibles por agentes.

Que la spec sea la primera lectura del modelo cada vez que se genere código.

12) Checklist de revisión para PRs generados por IA

No es lo mismo revisar un PR humano que uno generado por IA. Usa una checklist específica:

• ¿Respeta la spec? (sí/no)
• ¿Hay tests que cubren casos límite?
• ¿Se siguen convenciones de seguridad?
• ¿Hay duplicación innecesaria de lógica?
• ¿Los nombres reflejan la intención del dominio?

Si falla cualquiera, rechaza y pide reescritura a la IA con referencia a la sección exacta de SPEC.md.

13) Historias reales (sin fantasías)

Equipo A: arrancó sin spec. 10 librerías distintas, 3 sistemas de auth, un pico y nada funcionó. Reescritura completa en 3 semanas.

Equipo B: escribió spec en 2 días, usó Claude para generar contratos y tests. Demo en 48 horas. Integración estable en producción. ¿Qué prefieres?

14) Cuándo no usar Claude para esto

Claude es excelente en diseño. No lo necesitas para:

• Tiny fixes en funciones locales.
• Tests unitarios triviales.
• Autocompletado en IDE (usa Copilot si quieres velocidad inline).

Usa Claude cuando la decisión impacte contratos, seguridad o arquitectura.

15) Plantilla mínima de SPEC.md (pégala ya)

Pon esto en la raíz del repo. No la copies palabra por palabra sin adaptar. Pero hazlo.

– Título y objetivo en una frase.

– Stack aprobado (y versiones).

– Reglas arquitectónicas innegociables (3).

– Interfaces/contratos principales.

– Criterios de aceptación (tests que deben pasar).

– Política de secretos.

– Responsables y permisos de cambio.

Hazlo ahora. No mañana.

16) Metáfora que pega y no falla

La spec es la brújula. Claude es el marinero diestro. Sin brújula, el marinero navega. Rápido. Pero a la deriva. Con la brújula, llega al puerto. A salvo.

17) Urgencia real: la deuda técnica no perdona

Cada PR aceptado sin spec es una deuda invisible. Se acumula. Multiplica el coste de cada iteración futura. Actuar ahora es barato. Reescribir después es caro.

CTA: hazlo en 60 minutos

Abre el repo. Crea SPEC.md con las seis secciones mínimas que te di.

Si quieres, te doy la plantilla lista para pegar. Respóndeme con “Quiero la plantilla” y te la envío ahora mismo.

Esto no acaba aquí. Si quieres, te enseño:

• Un prompt maestro listo para Claude.
• Un SPEC.md completo para un proyecto típico (Next.js + PostgreSQL).
• Un .cursorrules ejemplo para que la spec sea leída por agentes.

Dime cuál quieres y te lo mando. Tus commits lo agradecerán. Y dentro de seis meses, tu equipo también.

Si quieres recursos y experimentos prácticos sobre automatización, agentes y workflows, revisa Dominicode Labs. Es una continuación lógica para quienes aplican estas prácticas en repos reales y pipelines de integración continua.