Cómo escribir especificaciones técnicas que realmente navegan

Si estás leyendo esto, es probable que hayas mirado a una especificación técnica medio acabada a las 2 de la mañana, tratando desesperadamente de envolverla antes de la estancia.O tal vez hayas estado en el extremo de la recepción - slogando a través de la obra de 47 páginas de otra persona, preguntándose si un PTO ilimitado vale la pena después de todo. Pero aquí está la cosa: cuando se hagan bien, las especificaciones técnicas no son tareas de casa de su líder tecnológico. Son una de las herramientas más poderosas que tiene que impulsar las características de la idea a la producción. voy a mostrarle cómo me acerco a escribirlas, basado en mi experiencia en Monzo y las lecciones que he recogido de los ingenieros de AWS, Google y Meta. Mi fondo es la ingeniería de software, pero mucho de esto se transfiere a otras disciplinas técnicas. ¿Por qué se escriben las especificaciones tecnológicas de todas formas? Escribir la documentación se siente como busworks cuando usted podría ser el código de envío. pero permanezca conmigo aquí, porque una buena especificación técnica hace mucho más que satisfacer algunos requisitos de proceso. Cuando se utiliza bien, las especificaciones técnicas te ayudan: Valida la idea antes de perder semanas construyéndola - he matado más malas ideas durante la fase de especificación de lo que me importa admitir. Obtenga el buy-in de las personas que realmente importan: su ingeniero de personal, su gerente de producto, ese ingeniero principal que lo ha visto todo. Iterate en el plan de alto nivel con personas más inteligentes que tú —no soy la persona más inteligente en la habitación, y si eres honesto contigo mismo, tampoco eres. Compartir conocimientos con su equipo - Encargar a nuevos ingenieros se convierte en "leer esta especificación" en lugar de "dejemos que explique esta arquitectura por tercera vez esta semana". — Your product manager, compliance team, or finance folks need to understand what you're building and why. A well-written spec bridges that gap. Share knowledge with stakeholders outside engineering Utilice como validación cuando el trabajo esté terminado — ¿Has resuelto realmente lo que has decidido resolver? Spec-driven development and LLMs LLMs han cambiado la forma en que pienso sobre las especificaciones técnicas. Los LLM funcionan mejor con las especificaciones técnicas estrictas y aisladas. Cuanto menos dejes a la imaginación, mejor. Una especificación bien definida se puede alimentar en un LLM para la creación automática de boletos o incluso la implementación técnica. Puede generar pruebas de sus especificaciones. Puede usar los LLM para idear partes de su propuesta, pedirles que hagan investigación o incluso ayudar a identificar defectos en su lógica. Tengo otro artículo que viene en las próximas semanas dedicado al desarrollo basado en las especificaciones con los LLMs. Tenga un ojo en él - he estado experimentando con esto a escala y los resultados son verdaderamente impresionantes. Pero incluso si nunca tocas un LLM, la disciplina de escribir una especificación rigurosa paga dividendos. Anatomía de una buena propuesta técnica (parte 1) Una buena especificación técnica es bien estructurada, fácil de entender y actuable. Debe ser escamosa para los ejecutivos y lo suficientemente detallada para que el ingeniero la implemente. Aquí está la primera mitad de la anatomía. Esto es lo que escribe antes de comprar. What are you trying to solve? Start with the problem statement. Not the solution — the problem. I've seen so many specs that jump straight into Nunca explican lo que está roto. "Deberíamos construir un microservicio con GraphQL" Your problem statement should be clear enough that someone outside your team can understand it. At my startup, Tandem, I have a simple test: could Jack, my non-technical co-founder understand the problem, just by reading it? If not, rewrite it. Algunas técnicas que funcionan: Utilice ejemplos concretos: No "los usuarios experimentan latencia", sino "los usuarios esperan un promedio de 8 segundos para que su historial de transacciones se cargue, y estamos viendo un descenso del 23% en esta pantalla". Mostrar el impacto del negocio: "Esto nos cuesta aproximadamente £2.3M anualmente en pérdidas de conversiones" es mucho más convincente que "esto es lento". Incluir citas o datos: Si tiene investigaciones de usuarios, quejas de clientes o datos de seguimiento, descargue. ¿Qué no estás tratando de resolver? Scope creep es real, y si no llamas explícitamente lo que está fuera de alcance, pasarás el próximo mes argumentando sobre casos de borde que no importan. Imagine this: you get a proposal from the platform team to upgrade to their shiny new shared UI library. Seems straightforward, right? Just swap out some imports, update a few components. But then you discover the new library uses a completely different routing system underneath. Now you need to refactor every route in your application. Then you realise your product team's navigation patterns don't quite fit the new model, so you need custom wrappers. Oh, and every equipo de productos que depende de esta biblioteca compartida? Todos están bloqueados en los mismos cambios. acaba de convertirse en un esfuerzo de migración de seis meses que está manteniendo el trabajo de características en toda la organización. Otros "simple utility update" Una explícita section could have caught this early. It gives you permission to say no. It keeps the culture of Y protege tu línea de tiempo de esas sugerencias aparentemente inocentes que se convierten en pesadillas organizativas. “Lo que no estamos resolviendo” "why-notism" ¿Por qué se debe resolver este problema? No todos los problemas necesitan ser resueltos. Algunos pueden vivir con problemas. Algunos no son realmente problemas, sólo inconvenientes menores. Haz el caso claro: Impacto en los usuarios: ¿Cuántas personas afecta? Impacto en el negocio: ingresos, retención, conversión, costes operativos? Impacto en la ingeniería: ¿es esta deuda tecnológica que está ralentizando cada otro proyecto? Impacto en el cumplimiento o el riesgo: ¿Esto explotará en seis meses si no lo arreglamos? Soy un gran creyente en mostrar tu trabajo aquí. no sólo digas Una vez basamos una propuesta para cambiar el texto en un botón en un experimento que demostró un aumento del 23% en la conversión, lo que se tradujo en +£12k ARR. “Esto es importante”. "this button copy could be better." ¿Por qué ahora? He visto perfectamente buenas propuestas quedarse en las esquinas porque no era el momento adecuado.Y he visto propuestas mediocres quedarse verde porque el momento era perfecto. ¿Por qué ahora es el mejor momento para resolver este problema? : Regulatory changes, marketing campaigns, conference demos External deadlines Preparación interna: ¿Tienes la infraestructura adecuada? ¿La capacidad del equipo adecuado? Dependencias: ¿Hay otros proyectos que necesitan enviar primero? : Sometimes, there's a narrow window when solving something is easier than it'll ever be again. Opportunity windows He aquí un ejemplo específico.Tuvimos una propuesta para utilizar las zonas horarias locales en las declaraciones de cuentas bancarias en lugar de UTC. El tiempo era crítico - queríamos hacerlo justo después de que los ahorros de luz diurna terminaran en el Reino Unido. Esto nos dio seis meses cuando UTC y el tiempo local eran los mismos. También tuvimos que mantener las declaraciones históricas en su zona horaria original por razones legales. Comenzando justo después de que los relojes cambiaran significó que teníamos la ventana máxima antes de la próxima transición, lo que redujo enormemente las posibilidades de que alguien necesitase generar una declaración con múltiples conversiones de zona horaria lógica. Si lo hubiéramos hecho en marzo en lugar de noviembre, habríamos introducido más complejidad y casos de raíz. Requirements ¿Cuáles son los mínimos absolutos que no se pueden excluir? Piensa en los requisitos como los que hay que tener.No los que hay que tener, ni los que quizás deberíamos tener, sino las cosas básicas que deben ser verdaderas para que esto valga la pena hacer. Requisitos de estructura como declaraciones probables: "El historial de transacciones debe cargarse en menos de 2 segundos en p95" "Solution must work for users on iOS 14 and above" "Los datos deben ser cifrados en reposo y en tránsito" "No debe exigir a ningún cliente que se autentique de nuevo" Tenga en cuenta que estos son específicos y verificables. Puedes probar si los has cumplido. o are useless. Pin them down. “Tienes que ser rápido” “Debería ser seguro” El ojo del pájaro de la solución Ellos inmediatamente se sumergen en los detalles de la implementación - qué base de datos, qué API, qué servicio mesh. El punto de vista del pájaro debe ser comprensible para las partes interesadas no técnicas. Estoy hablando con los gerentes de productos, las personas de operaciones, tal vez incluso las finanzas.Si no puedes explicar tu solución a alguien que no sabe qué es Kubernetes, no lo entiendes lo suficientemente bien tú mismo. Some rules for this section: Sin embargo, no. En lugar de say No tech talk. “Distribuiremos un nuevo microservicio con una caché de Redis y lo exponeremos a través de GraphQL.” " almacenaremos los datos de acceso frecuente más cerca del usuario para que se carguen de inmediato en lugar de hacer un viaje lento a la base de datos cada vez". ¿Qué cambia desde la perspectiva del usuario? ¿Cómo es el éxito para ellos? Think user-centric. Comienza con y luego explica a un alto nivel cómo logrará eso. Anchor on outcomes, work backwards. “Los usuarios verán su historial de transacciones en menos de 1 segundo” A veces hay enfoques verdaderamente diferentes. Coloca dos o tres opciones con pros y contras. Esto muestra que lo has pensado y da a las partes interesadas una elección real. If possible, offer multiple potential solutions. At this point, you should stop and reassess. Here's my checklist before moving forward: [ ]La declaración del problema es clara y específica [ ]El impacto de los negocios se cuantifica [ ]Los objetivos no están explicitamente indicados [ ]Los requisitos son probables [ ]La solución de alto nivel tiene sentido para un no ingeniero [ ]Estoy convencido de que vale la pena hacer Si no puede comprobar todas estas cajas, no proceda a la parte 2 todavía. seriamente. He perdido semanas escribiendo planes de implementación detallados para ideas que no valían la pena hacer. Hacer buy-in y colaborar Su siguiente paso es obtener feedback de las partes interesadas clave. Esto no es una formalidad. Esto es donde su especificación se mejora o se descompone. Algunos consejos para ganar un buen pitch: Soy un fan de Notion debido a los comentarios en tiempo real y la colaboración, pero Google Docs también funciona. Incluso he visto a algunos pioneros verdaderos usar Figma para esto una vez! Lo importante es que la gente pueda dejar comentarios en línea y sugerir cambios. Use a platform that makes collaboration easy. Si está proponiendo cambios a un viaje de usuario, crea mockups o wireframes. Si está optimizando un servicio, muestre las métricas actuales con capturas de pantalla de su seguimiento. Recomiendo Figma (alta fidelidad) o Excalidraw (baja fidelidad) para viajes de usuario y capturas de pantalla de Grafana o Datadog para métricas. Illustrate your points. Deja tu ego a la puerta.Cada pieza de crítica que recibes ahora es un problema de producción que no tendrás más tarde.He tenido especificaciones desgarradas en la revisión, y se succiona.Pero sabes lo que es peor?Construir algo durante tres meses solo para que falle en la producción porque has perdido algo obvio. Getting feedback should be your main objective. Si alguien deja un comentario como pídales amablemente que expliquen por qué y sugieran una alternativa.La negatividad vaga no ayuda a nadie.Pero las preocupaciones genuinas con el razonamiento? Guide your contributors. “No me gusta este enfoque”, Alguien preguntará You need an answer. The best answers have numbers. Es mucho más convincente que Be ready to defend your value proposition. “¿Vale la pena el tiempo de ingeniería?” "Esto puede conducir a una reducción del 27% en los costes de alojamiento de bases de datos, lo que resulta en un ahorro anual de £1.5M" “Esto hará las cosas más eficientes”. Un plan que vale la pena implementar (parte 2) ¿Tratas las especificaciones tecnológicas como un esfuerzo en solitario? escribe solo, comparte para la revisión, obtenga algunos comentarios, envíelo? Las mejores especificaciones técnicas son el resultado de una fuerte colaboración.Usted escribe el primer proyecto, seguro.Pero luego invita a personas inteligentes para que lo hagan mejor.Usted incorpora su feedback.Usted se ajusta en función de lo que aprende.La especificación evoluciona. Esta segunda parte de la anatomía es más dinámica. varía dependiendo de la cultura de su empresa, las prácticas de su equipo y el tipo de proyecto. Mejores prácticas y estándares de la empresa Su plan de implementación debe ser una extensión de las prácticas establecidas de su empresa. Si está utilizando React y Next.js para frontends web, su especificación debe usar React y Next.js. Si su empresa tiene un tubo CI/CD estándar, use eso. La excepción es cuando usted está proponiendo explícitamente cambiar una práctica establecida. Tal vez desee introducir un nuevo marco o migrar a una base de datos diferente. Cuando he propuesto cambios a las prácticas establecidas, siempre incluyo: : Has another company done this successfully? Show case studies. Outside proof of concept : Have we used similar approaches in different contexts? Prior art from adjacent domains Razonamiento claro de por qué el enfoque actual no funciona: No digas simplemente "esto es mejor". Ruta migratoria: ¿Cómo llegar de aquí a allá sin romper todo? En Superbet, lideré un equipo que construyó una biblioteca de UI dedicada para reemplazar el continuamente problemático Ant Design que estábamos usando antes. Hemos hecho de él un reemplazo 100% drop-in a través de una capa de compatibilidad - técnicamente perfecto. Pero todavía no pude convencer a la mayoría de los equipos a adoptarlo, porque no podía llevar el caso de negocio a casa. Esa es la lección aquí: reemplazar la tecnología establecida es difícil incluso cuando su solución es objetivamente mejor. Necesitas los números, los estudios de caso, el camino de migración. Prior art and alternatives considered Is there something similar that already exists? Have you implemented features with similar attributes in the past? All of this is worth mentioning. Mejor escenario de caso: descubre que no necesita construir nada nuevo. Añadirlo a la base de conocimientos relacionada con la solución que encontró. Ayuda a los mantenedores a comprender quiénes son sus partes interesadas y por qué las personas lo necesitan.Si quieren poner el atardecer, transferir la propiedad o refactor su software, sabrán con quién hablar. If this happens, don't throw away your spec. Hemos usado Statsig para enviar experimentos, pero habíamos escrito nuestro propio SDK sobre él en lugar de usar el oficial. Nuestra implementación no soportaba asignaciones persistentes, lo que significaba que no podíamos ejecutar experimentos pegajosos. Comenzé a especular sobre cómo agregar esta característica —pensando que necesitaría construirlo desde cero— y fui a una persecución de gusanos salvajes. Luego encontré un servicio existente específico de dominio que ya resolvió la persistencia para un caso de uso diferente. What other approaches did you evaluate? Why didn't they make the cut? Esto muestra que has hecho tu tarea. También impide que las personas sugieran alternativas que ya hayas considerado y rechazado. Approach Pros Cons Why we rejected it Use existing service X Fast, proven Doesn't support feature Y Missing critical functionality Build custom solution Perfect fit High maintenance cost Not worth the ongoing burden Third-party API Easy integration Vendor lock-in, high cost £250K annually vs £30K to build Uso del servicio existente X Rápido y probado No soporta la función Y Falta de funcionalidad crítica Build custom solution Perfect fit El alto costo de mantenimiento Not worth the ongoing burden Third-party API Easy integration Vendor lock-in, high cost £250K annually vs £30K to build El enfoque técnico Ahora, finalmente, puede entrar en los detalles.Este es el lugar donde explica la implementación real, las decisiones de arquitectura y las opciones de tech stack. Diagramas de arquitectura, diagramas de secuencia, diagramas de flujo de datos. recomiendo (Ahora La desventaja es que no hay compartir en vivo como Figma, por lo que necesitará exportar e incorporar imágenes. Use diagrams. Título.io diagrams.net Para los diagramas de secuencias, me gusta Mermaid porque puedes escribirlos en marcado y se renderizan automáticamente en la mayoría de las herramientas. sequenceDiagram User->>API: Request transaction history API->>Cache: Check cache Cache-->>API: Cache miss API->>Database: Query transactions Database-->>API: Return results API->>Cache: Store in cache API-->>User: Return results No sólo digas Dice Explain the "why" behind technical decisions, not just the "what." “Utilizaremos Redis para el cache”. “Utilizaremos Redis para el caché porque nuestros patrones de acceso son muy legibles (95% de lecturas versus 5% de escrituras) y necesitamos latencia submillisegundos. Be honest about where this will break. That's way more useful than pretending your solution scales infinitely. Call out performance characteristics and scalability limits. "Este enfoque funciona hasta alrededor de 100.000 solicitudes por segundo. Más allá de eso, tendremos que descomponer". Mostrar cómo se ven los datos. Mostrar cómo se ven las solicitudes y respuestas de la API. Normalmente incluyo ejemplos de JSON: Mention data models, API contracts, key interfaces. { "transaction_id": "tx_123", "amount": 1250, "currency": "GBP", "timestamp": "2025-01-15T14:30:00Z", "category": "groceries" } Una ventaja de incorporar modelos en un formato transferible, como JSON, es que esto puede ser copiado/pasado a un servicio de prueba o mock más tarde. Una ventaja de incorporar modelos en un formato transferible, como JSON, es que esto puede ser copiado/pasado a un servicio de prueba o mock más tarde. Si esto requiere la incorporación de nuevos servicios, bases de datos o integraciones de terceros, llámelo. Highlight any new infrastructure or services needed. romper el trabajo ¿Cómo descompones esta solución en hitos y tareas que se pueden rastrear?Esta es la gestión de proyectos, pero es tu trabajo proporcionar la estructura. Soy un gran fan de la progresión de MVP → MLP → Producto completo: Split into phases that deliver incremental value. MVP (Minimum Viable Product): La cosa más pequeña que se puede construir para validar el enfoque. Usualmente solo interno o limitado a un pequeño porcentaje de usuarios. MLP (Minimum Lovable Product): La versión más pequeña que es realmente lo suficientemente buena como para que los usuarios reales lo utilicen y disfruten. : All the bells and whistles. Full Product Don't try to ship everything at once. This is tough to admit, but in many cases, we ended up keeping the MLP as the end-result, because it was . “Lo suficientemente bueno” What must ship for this to work? What's optional? Use a prioritisation framework. I like MoSCoW (Must have, Should have, Could have, Won't have). Identify critical path items vs nice-to-haves. ¿Pueden los equipos de backend y frontend trabajar simultáneamente? o el backend necesita enviar primero? Call out what can be parallelised vs must be sequential. De hecho, odio el tamaño y también me siento mal. prefiero las horas de desarrollador, los días de desarrollador, las semanas de desarrollador como unidades de medida, cuando hablo de líneas de tiempo. Si no estás seguro, haz una medición, por ejemplo: ¿no estás seguro de si son 3 o 4 días de desarrollador? Assign rough t-shirt sizes or story points if your team uses them. Utilice un gráfico de dependencias simple o simplemente enumere: Make dependencies between tasks explicit. "Tareas B depende de que Tareas A estén completas. Tareas C pueden comenzar en paralelo con Tareas B." Success metrics ¿Cómo medir si la implementación realmente funcionó? ¿Cuáles son los KPIs? This is where you define victory conditions. And you need to be specific. No es una métrica de éxito. Es una métrica de éxito. "Make it faster" "Reduce la latencia de la API p95 de 500ms a menos de 200ms" Examples: Define measurable outcomes. Reducción de la latencia: "la latencia p95 disminuye de 800ms a 200ms" Reducción de la tasa de error: "Los errores 5xx caen del 0,3% al menos del 0,1%" Conversion improvement: "checkout completion rate increases from 73% to 80%" Cost savings: "database costs decrease by £40K annually" Necesitas saber dónde estás empezando.Tomo capturas de pantalla de tableros que muestran el rendimiento actual y las ancho a la especificación.Es muy fácil olvidar cómo eran las cosas antes de comenzar. Set baseline metrics before implementation. ¿Vas a construir un dashboard? establecer alertas? ejecutar una prueba A/B? ser explícito sobre la metodología de medición. Specify how you'll track these metrics. Los gerentes de productos se preocupan por los ingresos y el compromiso.Los ingenieros se preocupan por la latencia y el rendimiento. Include both business metrics and technical metrics. Evaluación de riesgos, dependencias y mitigación What could go wrong? What are you worried about? What do you need from other teams? He aprendido a ser brutalmente honesto en esta sección. Fingir que los riesgos no existen no los hace desaparecer. ¿Necesitas otro equipo para enviar algo primero? ¿Confías en un servicio de terceros que pueda tener límites de tarifas o tiempos de inactividad? llámalo. List external dependencies. ¿Dónde puede romperse esto? ¿Qué sucede si ese servicio crítico falla? Si está introduciendo una nueva base de datos, ¿qué sucede si falla? Call out single points of failure in your design. ¿Estás utilizando una tecnología por primera vez? ¿Es esta una área de la base de código que ya nadie entiende realmente? ¿Estás haciendo suposiciones sobre el comportamiento de los usuarios que podrían estar equivocados? Identify areas with high uncertainty. No solo enumere los riesgos, muestra cómo los manejas.Ejemplo: For each major risk, propose a mitigation strategy or fallback plan. Riesgo: las API de terceros pueden tener un tiempo de inactividad Mitigación: Implementa el interruptor de circuitos con retroalimentación exponencial; cache de respuestas durante 5 minutos; tiene un modo degradado que funciona sin la API Esto crea confianza y pide ayuda. Es mejor que fingir que lo has entendido todo. Be honest about what you don't know yet. "No estoy seguro de cómo vamos a manejar la migración de 500GB de datos existentes - buscando información aquí" No espere hasta que la revisión de seguridad descubra que necesita una evaluación de impacto de la privacidad completa. Si está tocando los datos de los usuarios, llámelo. Mention compliance, security, or data privacy concerns early. Estrategia de Rollout How will this actually get deployed? Phased rollout? Feature flags? Canary deployments? I never ship big changes to 100% of users on day one. Never. If you only have two users, ship to just one. Si solo tienes dos usuarios, envíe a uno solo. My usual progression: 5% → 10% → 50% → 100%. At each stage, you monitor metrics and watch for issues. If something breaks, you're only affecting a small subset of users. Plan for gradual rollout. Despliegue el código en la producción pero manténgalo detrás de una bandera. Esto le permite controlar quién ve la nueva característica independientemente de su proceso de implementación. He utilizado LaunchDarkly, Statsig y construido soluciones nativas. Todos funcionan. Seleccione uno y uselo religiosamente. Use feature flags to decouple deploy from release. ¿Qué condiciones desencadenan un rollback? Define rollback criteria. If error rate exceeds 0.5%, roll back Si la latencia p95 excede de 1 segundo, vuelva If we get more than 10 customer complaints in an hour, roll back Tener estos criterios definidos de antemano significa que no tomarás decisiones emocionales durante un incidente. Send real traffic through the new code path but don't show users the results. Compare the output to the old code path (also called: shadow testing). This flushes out bugs before users see them. Consider dark launching to test in production without user impact. Migración de millones de registros de base de datos es arriesgado. Hacerlo separadamente de enviar nuevas características. Idealmente, migrar los datos primero, luego implementar el código que utiliza el nuevo esquema, y luego limpiar el viejo esquema (espand-migrate-contract patrón). Plan for data migrations separately from code deploys. ¿Quién necesita saber cuándo este barco? equipo de soporte al cliente? marketing? socios externos? Escriba el plan de comms en la especificación. Have a communication plan for internal stakeholders and customers. Estrategia de Rollback ¿Qué sucede si de repente te vuelves indisponible cuando todo está en llamas? ¿Sabía tu equipo cómo manejarlo? Think of it like a preflight checklist for pilots. When stress is high and adrenaline is pumping, you don't want to be figuring things out. You want a list you can follow mechanically: Desactivar la bandera X O: volver a rodar para cometer abc123 y implementar Ejecutar el script de base de datos Y para revertir los cambios de esquema Clear Cache Z para eliminar los datos permanentes Métriques de monitoreo A, B, C para confirmar el éxito del rollback Post in #incidents channel with status This keeps stress to a minimum in incident scenarios. Testing approach Pruebas de unidad, pruebas de integración, pruebas de carga, casos de borde: ¿cómo validarás que esto realmente funciona? Los caminos críticos necesitan pruebas extensas. Las características de buen uso pueden tener una cobertura más ligera. Sea explícito sobre lo que necesita qué nivel de pruebas. Define test coverage expectations. Si esto servirá a millones de solicitudes, necesita probarlo a escala.Uso herramientas como k6 o Locust para simular la carga.No espere hasta que la producción descubra que su base de datos cae a 10.000 QPS. Plan load/performance testing for high-traffic features. Matar las dependencias. Injetar la latencia. Simular las particiones de la red. Ver lo que se rompe. Chaos Monkey de Netflix es el ejemplo canónico, pero no necesita nada que sea sofisticado. Consider chaos engineering for critical systems. ¿Qué sucede cuando la base de datos es lenta? Cuando la caché está vacía? Cuando un usuario envía una entrada malformada? Test edge cases and failure modes, not just happy paths. Las pruebas automatizadas son grandes, pero solo capturan lo que pensabas que deberías probar.Un clic humano puede encontrar las cosas extrañas. Plan for manual QA/exploratory testing where needed. Test de pluma, OWASP Top 10 checks, escaneo de dependencia.Si está tocando autenticación, pagos o datos personales, necesita una revisión de seguridad. Include security testing for sensitive features. Timelines y Milestones Realistic estimates, buffer for unknowns, key delivery dates. Here's an uncomfortable truth: your initial estimates will be wrong. They're always wrong. The question is how wrong. Si hay un requisito regulatorio o una demostración de conferencia, comience allí y trabaje hacia atrás para averiguar si es factible. Work backwards from hard deadlines if they exist. Si estás trabajando en territorio familiar con tecnología conocida, multiplique las estimaciones por 1,2x. Si estás en territorio desconocido o usando nueva tecnología, multiplique por 1,5x a 2x. Pad estimates for unknowns. Every two weeks, you should be able to show something. It keeps momentum and surfaces problems early. Define clear milestones with demos or checkpoints. Vacaciones, temporada de conferencias, plazos de cumplimiento, lanzamientos de marketing.Si la mitad de tu equipo va a estar fuera por una semana, factor que en. Call out external constraints. Toma en cuenta las rotaciones en la llamada, otros compromisos, el hecho de que nadie es productivo 8 horas al día. Be realistic about team capacity. Las estimaciones iniciales son adivinaciones educadas. A medida que entras en la implementación, aprendes cosas. Actualiza tu línea de tiempo en consecuencia. Una especificación debe ser un documento vivo, no un contrato escrito en piedra. Update estimates as you learn more. Preguntas abiertas ¿Qué hay que investigar? ¿qué hay que investigar? Esta sección debe encajar con el tiempo a medida que obtienes respuestas, pero es crucial tenerla. "Necesitamos validar que el enfoque X puede manejar nuestro volumen de consulta" o "Deberíamos prototipar el script de migración en un conjunto de datos de prueba primero". List unknowns that need research or prototyping before committing. "Necesitaba revisar el equipo de seguridad sobre el enfoque de cifrado" o "Necesitaba la entrada de producto sobre qué comportamiento debería ser el fallback". Call out decisions that need input from specific people or teams. "We're assuming users will click this button, but we should A/B test to confirm" or "We think this cache hit rate will be 80%, but we should measure real traffic patterns first." Highlight areas where you need to validate assumptions with data. "Podríamos optimizar la latencia o el rendimiento, pero no ambos - necesitamos decidir qué importa más para este caso de uso". Be explicit about trade-offs you haven't resolved yet. Alguien debe ser responsable de obtener una respuesta, y debe haber un plazo. Assign owners to each open question with target resolution dates. Cómo la cultura juega un papel I've worked at companies where specs were treated as bureaucratic box-checking exercises, and I've worked at companies where they were genuinely valued as thinking tools. The difference is night and day. This reduces cognitive load and makes sure everyone's on the same page. You shouldn't have to reinvent the structure every time. We had a template in Notion. For Tandem, we use Google Docs templates, and at Docler, we had Confluence. The tool doesn't matter as much as the consistency. Technical specifications should be based on a standard template. Having a standard template also means reviewing specs is easier. You know where to look for the problem statement, the requirements, the risks. You're not hunting through a free-form essay trying to figure out basic information. No tengas miedo de compartir la tuya con un público más amplio.Sé que es aterrador poner tus ideas allí, pero la transparencia tiene enormes beneficios.Otros equipos pueden descubrir que están resolviendo problemas similares.Alguien de una vertical diferente puede tener un contexto crucial que te falta.Serendipidad ocurre cuando la información es pública. Make all proposals publicly available. All specs were in a shared Notion space that anyone in engineering could read. The number of times someone from a completely different squad dropped a comment that changed the whole approach was remarkable. Esto sirve a múltiples fines: ayuda a otros a aprender, alienta la colaboración, hace que las personas sean conscientes de lo que se está construyendo en toda la organización. sesiones en las que las personas presentarían propuestas en curso y obtendrían feedback de un grupo cross-funcional. Schedule regular review sessions of critical proposals. "architecture review" Praise great proposals publicly. Acknowledge all participants, even if they just left a single comment. This encourages a culture of collaboration. I've seen teams where people were afraid to comment on specs because they thought they'd be seen as obstructionists. That's poison. You want people to feel like their input is valued, even if it's critical feedback. Tell people they're doing great. Cuando alguien escribe una especificación particularmente buena, lo llamo en un canal público. Dura cinco segundos y hace que las personas se sientan bien con el trabajo que están haciendo. "Esta especificación de Alex es un excelente ejemplo de cómo estructurar una propuesta compleja - compruebe para la referencia". El Spec es el trabajo Aquí está mi último pensamiento, y es probablemente la cosa más importante en todo este artículo: escribir la especificación está haciendo el trabajo. Too many engineers treat the spec as overhead before the La especificación es donde haces el pensamiento más difícil. Es donde descubres lo que no sabes. Es donde encuentras los defectos fatales antes de que se conviertan en incidentes de producción. “El trabajo real” The best specs I've written have been collaborative, iterative, and occasionally contentious. They've been marked up with dozens of comments. They've gone through multiple revisions. They've forced me to reconsider assumptions I didn't even know I was making. Y cada uno de ellos hizo la implementación más suave, más rápida y más exitosa de lo que habría sido de otra manera. Así que la próxima vez que esté tentado a saltar la especificación y simplemente comenzar a codificar, resista. abre ese documento. Comience con el problema. Trabaje a través de los detalles. Invite a las personas inteligentes a hacer agujeros en su lógica. Iterate. Your future self — and your on-call rotation — will thank you. Mi plantilla de propuesta de producto está disponible en GitHub. Capta la mayoría de las ideas discutidas aquí. Si su organización no tiene una plantilla de propuesta técnica todavía, use esto como punto de partida. El modelo de propuesta de producto está disponible en GitHub