17 de junio de 2026Actualizado el Fathy Shalaby13 min de lectura
Plantilla de especificación técnica: escribe una spec que los ingenieros sí lean
Una plantilla de especificación técnica para copiar, las prácticas de design docs y RFC en las que se inspira y un método paso a paso para escribir una spec que los ingenieros lean hasta el final.
Una plantilla de especificación técnica debe poner las decisiones de riesgo en la primera página: el problema y sus restricciones, el diseño propuesto, las alternativas descartadas y lo que podría salir mal, en una a tres páginas para la mayoría de los cambios. Los design docs de Google y los RFC de Uber siguen esta forma. La plantilla para copiar que verás abajo añade un resumen de una frase y una tabla de decisiones, para que quien revisa encuentre las decisiones difíciles en menos de un minuto.
Ideas clave
Los design docs de Google tienen cinco secciones centrales y ocupan de 10 a 20 páginas en proyectos grandes, pero de 1 a 3 páginas en trabajo incremental (Malte Ubl, 2020).
Los lectores consumen alrededor del 20 % de las palabras de una página web promedio, y como máximo el 28 % (Nielsen Norman Group, 2008). Las specs se leen igual: se escanean en busca de lo que podría estar mal.
El 61 % de los desarrolladores dedica más de 30 minutos al día a buscar respuestas (Stack Overflow, 2024). Una spec que registra las decisiones responde esas preguntas una sola vez.
Los equipos con documentación de alta calidad tienen 3,8 veces más probabilidades de aplicar buenas prácticas de seguridad (DORA, 2021).
«Alternativas consideradas» es la sección en la que más confían los revisores, porque demuestra que buscaste una razón para no construirlo así.
¿Qué es una especificación técnica y en qué se diferencia de un PRD?
Una especificación técnica (también llamada design doc o documento de diseño técnico) explica cómo va a construir algo un equipo y qué compromisos acepta. Un PRD explica qué problema vale la pena resolver, para quién y cómo se medirá el éxito. Primero va el PRD; la especificación técnica le responde.
Los equipos usan cuatro documentos relacionados. Confundirlos es la razón más común por la que una spec crece hasta 15 páginas que nadie termina.
¿Qué problema, para quién y cómo sabremos que funcionó?
Product manager
2–5 páginas
Especificación técnica / design doc
¿Cómo lo construiremos y qué estamos sacrificando?
Tech lead o ingeniero
1–3 páginas (10–20 en sistemas grandes)
RFC (request for comments)
¿Está de acuerdo el resto de la organización con este plan antes de empezar?
Autor y aprobadores nombrados
Igual que una spec, con fecha límite de revisión
ADR (architecture decision record)
¿Por qué tomamos esta decisión concreta y qué implica?
Ingeniero que tomó la decisión
1–2 páginas
La guía de Google describe el design doc como el lugar donde documentar la estrategia de implementación de alto nivel y las decisiones clave de diseño, con énfasis en los compromisos. El formato de ADR de Michael Nygard, publicado en 2011, lo reduce a una única decisión con cinco partes: título, contexto, decisión, estado y consecuencias (Michael Nygard, 2011). Si quieres empezar por el lado del producto, lee primero la guía para escribir un PRD.
¿Por qué los ingenieros se saltan la mayoría de las especificaciones técnicas?
Los ingenieros se saltan las specs que responden preguntas que nadie hizo y esconden las que importan. Tres patrones explican la mayor parte.
Se escriben para ser completas, no para decidir. El análisis de Jakob Nielsen de 2008 encontró que, en una página promedio de 593 palabras, los lectores tenían tiempo para como máximo el 28 % de las palabras, y lo más probable era el 20 %. Solo llegaban a la mitad del contenido en páginas de 111 palabras o menos. Un revisor con seis specs en la cola lee igual: resumen, diagrama, texto en negrita y luego la sección con la que no está de acuerdo.
Esconden la decisión arriesgada en prosa uniforme. Si la decisión irreversible está en el párrafo nueve, cada revisor tiene que volver a deducirla. Ese es justo el desperdicio que una spec debería evitar.
Se quedan obsoletas. La encuesta Stack Overflow Developer Survey 2024 halló que el 61 % de los encuestados dedica más de 30 minutos al día a buscar respuestas, y que el 30 % dice que los silos de conocimiento perjudican su productividad 10 o más veces por semana. Una spec que deja de coincidir con el código se convierte en una fuente más de respuestas equivocadas.
El beneficio de hacerlo bien es medible. La investigación de DORA de 2021 encontró que los equipos con documentación de alta calidad tenían 3,8 veces más probabilidades de aplicar buenas prácticas de seguridad y 2,5 veces más probabilidades de aprovechar la nube al máximo.
¿Qué debe incluir una especificación técnica?
Incluye solo lo que cambia cómo alguien construiría o revisaría el trabajo. Dos prácticas publicadas ofrecen una buena base.
Las secciones del design doc de Google
El texto de Malte Ubl de 2020 sobre los design docs en Google enumera las secciones que comparten la mayoría de los documentos:
Contexto y alcance: el entorno en el que vive el sistema, en pocos párrafos.
Objetivos y no objetivos: lo que el sistema debe hacer y lo que explícitamente no hará.
El diseño en sí: diagrama del sistema, APIs, almacenamiento de datos, y código o pseudocódigo solo donde aclare un algoritmo novedoso.
Alternativas consideradas: otros diseños y por qué perdieron.
Aspectos transversales: seguridad, privacidad y observabilidad.
Las secciones de los RFC de Uber
El proceso de RFC de Uber creció con la empresa, de decenas de ingenieros a un par de miles, según Gergely Orosz, que trabajó allí (The Pragmatic Engineer, 2018). Su plantilla de backend empezaba con una lista de aprobadores y luego cubría cambios de arquitectura, SLA de servicios, dependencias, pruebas de carga, aspectos multicentro de datos, seguridad, pruebas y despliegue, métricas y monitorización, y atención al cliente. La plantilla móvil añadía la interfaz y la accesibilidad. Se fueron añadiendo secciones a medida que la empresa aprendía qué pasaba por alto una y otra vez.
La lección de ambas: una plantilla de especificación técnica es una lista de comprobación de errores pasados. Empieza pequeño y añade una sección solo cuando su ausencia haya causado un problema real.
Plantilla de especificación técnica (para copiar y adaptar)
Esta plantilla de especificación técnica combina las secciones de Google, el hábito de Uber de poner primero a los aprobadores y el formato de decisión de Nygard. Elimina cualquier sección que fuera a decir «N/A».
# [Nombre de la funcionalidad o del sistema]: especificación técnica
**Resumen:** Vamos a hacer [X] para lograr [Y], aceptando el compromiso de [Z].
**Autor:** [nombre] · **Aprobadores:** [2–3 nombres] · **Revisar antes del:** [fecha]
**Estado:** Borrador | En revisión | Aprobada | Reemplazada por [enlace]
**PRD / ticket relacionado:** [enlace]
## 1. Problema y restricciones
- Qué está roto, a quién afecta y qué se vuelve posible cuando se arregle.
- Restricciones duras: presupuesto de latencia, residencia de datos,
compatibilidad hacia atrás, el SLA que no puedes romper.
## 2. Objetivos y no objetivos
- Objetivos (medibles siempre que sea posible).
- No objetivos: cosas que un lector razonable podría esperar y que no haremos.
## 3. Decisiones clave (léelo primero)
| # | Decisión | ¿Reversible? | Riesgo si es errónea | Confianza |
|---|----------|-------------|---------------|------------|
| 1 | | Puerta de sentido único / de doble sentido | | Alta / Media / Baja |
## 4. Diseño propuesto
- Un diagrama. Cambios de APIs y del modelo de datos. Pseudocódigo solo
para lo que sea novedoso.
## 5. Alternativas consideradas
- Opción A: por qué perdió.
- Opción B: por qué perdió.
- No hacer nada: qué pasa si no construimos esto.
## 6. Riesgos y preguntas abiertas
- Supuestos de los que depende todo y cómo los comprobaremos.
- Preguntas que necesitamos resolver antes o durante la construcción.
## 7. Aspectos transversales
- Seguridad y privacidad · Observabilidad · Accesibilidad · Costo.
## 8. Despliegue, validación y reversión
- Feature flag / plan de despliegue por etapas.
- Métricas que demuestran que funciona y el umbral que activa la reversión.
## 9. Registro de decisiones
- [fecha] Se cambió [decisión] porque [motivo]. (Actualiza aquí, no en un comentario de PR.)
La tabla de decisiones de la sección 3 es la parte que justifica la plantilla. Marcar cada decisión como puerta de sentido único o de doble sentido le indica a quien revisa dónde poner su atención. El marco de decisiones reversibles e irreversibles explica cómo juzgar cuál es cuál.
¿Qué extensión debe tener una especificación técnica?
La más corta que permita la decisión más arriesgada. La guía de Google sitúa los design docs de proyectos grandes en unas 10 a 20 páginas y considera adecuados los «mini design docs» de 1 a 3 páginas para trabajo incremental. Los ADR de Nygard ocupan una o dos páginas. Amazon sustituye las diapositivas por «memorandos de seis páginas con estructura narrativa», que se leen en silencio al comienzo de cada reunión, y Jeff Bezos escribió que uno realmente bueno probablemente lleva una semana o más de escritura (Amazon, 2018).
Una regla práctica según el tamaño del cambio:
Cambio
Formato
Extensión
Revisión
Corrección de un bug, cambio de texto, ajuste de configuración
Descripción del ticket
Un párrafo
Solo revisión de código
Nuevo endpoint o componente dentro de un servicio
Mini spec
1 página
Un aprobador, asíncrono
Funcionalidad que toca 2–3 servicios o una API pública
Especificación técnica (plantilla de arriba)
2–3 páginas
2–3 aprobadores, ventana de 2–3 días
Sistema nuevo, migración de datos o frontera de seguridad
Design doc completo o RFC
5–20 páginas
Reunión formal de revisión
La guía de Google también dice cuándo no escribir una: cuando la solución es inequívoca y el documento sería solo un manual de implementación sin compromisos que discutir.
¿Cómo escribes una spec que los ingenieros sí lean?
Escríbela en este orden. Gran parte del trabajo consiste en decidir qué dejar fuera.
Escribe primero el resumen de una frase. «Vamos a hacer X para lograr Y, aceptando el compromiso de Z.» Si no puedes escribirlo, aún no estás listo para escribir la spec, y quienes la revisen tampoco podrán resumirla.
Abre con el problema, no con la solución. Los ingenieros no pueden juzgar un diseño hasta que conocen las restricciones a las que responde. Indica lo no negociable antes del diagrama de arquitectura.
Rellena la tabla de decisiones. Enumera cada decisión con la que un revisor podría estar razonablemente en desacuerdo. Pon en negrita las puertas de sentido único.
Escribe las alternativas con honestidad. Incluye «no hacer nada». Una spec sin opciones descartadas parece una decisión ya tomada.
Nombra a dos o tres aprobadores y una fecha límite de revisión. Uber listaba a los aprobadores al inicio de cada RFC. Una spec sin quien decida ni fecha tiende a quedarse en revisión indefinidamente.
Revisa de forma asíncrona y reúnete solo para los desacuerdos. Los comentarios en el documento resuelven la mayor parte del feedback. Si os reunís, copia a Amazon y dedica los primeros diez minutos a la lectura en silencio.
Actualiza la spec cuando la construcción la cambie. En el ciclo de vida de Google, el documento se revisa durante la implementación. Registra los cambios en el registro de decisiones, no en un comentario de pull request que nadie encontrará.
Orosz señala que, cuando un equipo se pone de acuerdo en un plan, ponerlo por escrito suele llevar unas pocas horas. Si lleva días, el desacuerdo es el hallazgo.
Ejemplo práctico (ilustrativo)
Digamos que un equipo de seis personas necesita evitar que los webhooks lentos de los clientes hagan expirar el checkout. Su frase de resumen: «Vamos a mover el envío de webhooks a una cola para que el checkout nunca espere al servidor de un cliente, aceptando hasta 60 segundos de retraso en la entrega.»
#
Decisión
¿Reversible?
Riesgo si es errónea
Confianza
1
Pasar a entrega al menos una vez; los clientes deben deduplicar por ID de evento
Puerta de sentido único (contrato público)
Pedidos duplicados en los sistemas de los clientes
Media
2
Usar la base de datos Postgres existente como cola en lugar de un broker nuevo
Puerta de doble sentido
Techo de rendimiento en horas pico; migrar más adelante
Alta
3
Reintentar cinco veces durante 24 horas y luego marcar como fallido
Puerta de doble sentido
Algunos clientes pierden eventos en caídas largas
Alta
Quienes revisan ven en 30 segundos que la decisión 1 merece el debate: cambia un contrato de API público, necesita una nota de migración para los clientes y no se puede deshacer en silencio. Las decisiones 2 y 3 pueden aprobarse en un comentario.
¿Cuáles son los errores comunes con las especificaciones técnicas?
Escribir la spec después del código. Una spec escrita para justificar un pull request terminado no tiene alternativas y no detecta nada.
Cinco diagramas en lugar de uno. Un diagrama del sistema con el cambio resaltado vale más que cinco que lo muestran todo.
Tratar la plantilla como un formulario. Las secciones vacías con «N/A» enseñan a los lectores a saltarse cosas. Elimínalas.
Sin responsable para las preguntas abiertas. Cada pregunta abierta necesita un nombre y una fecha, o acabará siendo un incidente en producción.
Congelar el documento. Una spec que deja de coincidir con lo construido es peor que no tener ninguna, porque la gente confía en ella.
Usar una spec donde un prototipo respondería más rápido. Si la pregunta de riesgo es «¿aguantará esta librería nuestra carga?», un spike de un día vale más que cinco páginas de argumentos.
¿Cómo cambian las especificaciones técnicas con los agentes de programación con IA?
Los agentes de programación leen las specs al pie de la letra. La ambigüedad que un ingeniero humano resolvería en Slack se convierte en código que un agente escribe mal con total seguridad. Las partes de la plantilla que más importan para un agente son los no objetivos, las restricciones y los criterios de aceptación comprobables. La plantilla de PRD para agentes de programación con IA muestra cómo hacerlos explícitos. Una vez aprobada la spec, el siguiente paso es dividir el PRD en historias de usuario, y un pre-mortem de lanzamiento pone a prueba el plan de despliegue antes de la salida.
¿Dónde encaja Specky?
La brecha entre la intención documentada y la realidad entregada suele abrirse cuando los requisitos, las decisiones y los tickets viven en herramientas distintas. Specky redacta PRD en un editor con citas en línea que remiten a las evidencias de los clientes, genera tickets con criterios de aceptación comprobables y registra las decisiones en un Product Graph para que el «porqué» siga unido al trabajo. Los agentes de programación pueden leer ese contexto a través de un servidor MCP. El ingeniero sigue escribiendo el diseño técnico; el contexto de producto que lo rodea se mantiene al día. Si encontrar tiempo para escribir es el cuello de botella, el ejemplo de semana de un PM protege un bloque de concentración para ello.
Preguntas frecuentes
¿Cuál es la diferencia entre un PRD y una especificación técnica?
Un PRD define el problema, los usuarios y cómo se medirá el éxito; una especificación técnica define cómo construirá el equipo la solución y qué compromisos acepta. Normalmente el product manager es dueño del PRD y el tech lead de la spec. Escribe primero el PRD y luego enlázalo desde la spec para que quienes revisan puedan comprobar el diseño frente al objetivo original.
¿Quién debe escribir la especificación técnica?
El ingeniero o tech lead que será responsable de la construcción debe escribir la especificación técnica, y el product manager la revisa frente al PRD. El autor responde por las decisiones, no por teclear cada sección. En un equipo pequeño, el PM puede redactar las secciones de problema, objetivos y no objetivos, y el ingeniero completa el diseño, las alternativas y el plan de despliegue.
¿Qué extensión debe tener un documento de diseño técnico?
La mayoría de los documentos de diseño técnico deberían ocupar de una a tres páginas. En la práctica de Google, los mini design docs de 1 a 3 páginas son normales para cambios incrementales, y de 10 a 20 páginas se reservan para sistemas nuevos grandes. Si tu spec supera las tres páginas para una funcionalidad dentro de servicios existentes, probablemente mezcla varias decisiones que deberían ser ADR separados.
¿Qué es un RFC en ingeniería de software?
Un RFC (request for comments) es un plan por escrito que se comparte con toda la organización de ingeniería antes de empezar el trabajo, para que otros señalen riesgos. Uber usó los RFC mientras pasaba de decenas a un par de miles de ingenieros, y listaba a los aprobadores por nombre al inicio de cada uno. Un RFC es una especificación técnica más un proceso de revisión, una fecha límite y alguien que decide.
¿Cuándo no hay que escribir una especificación técnica?
Omite la spec cuando la solución es inequívoca y no hay compromisos relevantes que discutir, que es la línea que traza la guía de Google. Las correcciones de bugs, los cambios pequeños de interfaz y las actualizaciones de configuración van en un ticket. Si la principal incertidumbre es la viabilidad técnica, haz primero un spike acotado en el tiempo y escribe la spec cuando sepas qué funciona.
¿Qué es un architecture decision record (ADR)?
Un ADR es un registro de una o dos páginas de una única decisión de arquitectura. El formato de Michael Nygard de 2011 tiene cinco partes: título, contexto, decisión, estado y consecuencias. Muchos equipos guardan los ADR en el repositorio de código, para que los futuros ingenieros vean por qué algo se construyó de cierta manera. Usa ADR para las decisiones que sobreviven a una sola spec.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing