Escribir y revisar documentación de seguridad para desarrolladores

## Escribir consejos que los desarrolladores puedan aplicar, sin salir de la seguridad Escribe para desarrolladores, no para especialistas en seguridad. La orientación debe ser precisa, práctica, concisa y tener criterios claros. Prioriza los buenos consejos que un desarrollador pueda aplicar frente a los consejos teóricamente óptimos que sean demasiado complejos para seguirlos. Mantén cada recomendación dentro del modelo de amenazas de seguridad del documento. Los consejos generales sobre calidad del código, rendimiento y arquitectura deben tratarse en otro lugar, salvo que controlen directamente un riesgo de seguridad. Considera las reglas de contribución obligatorias para todas las herramientas de redacción. Conserva el proceso humano autoritativo y las guías de redacción del repositorio, y utiliza la guía abreviada para agentes únicamente como resumen operativo. ## Leer cada fuente citada y comprobar que respalda la afirmación Obtén y lee cada fuente citada y, después, confirma que respalda la afirmación exacta. Nunca inventes ni adivines una URL, cites una página que redirija a una página de destino no relacionada, ni dependas de la memoria de entrenamiento o de un resumen. Enlaza la página o sección concreta que contenga las pruebas de respaldo. Verifica los enlaces cruzados internos antes de utilizarlos. No apuntes a un documento o ancla que no exista. Cuando se apliquen controles de densidad de citas, incluye al menos una cita HTTPS integrada en cada sección H2 nueva. Aporta respaldo independiente para las afirmaciones novedosas, sorprendentes, específicas de parámetros o discutibles; las prácticas comunes establecidas no necesitan una cita en cada frase. Las fuentes pueden aparecer integradas o reunidas en una sección de Referencias. Da preferencia a las normas, la orientación de seguridad gubernamental o sectorial, la documentación oficial de proyectos y proveedores, las referencias de plataformas con buen mantenimiento, los repositorios fuente canónicos y la investigación revisada por pares. Evita las granjas de contenido comercial optimizadas para buscadores. Los controles de citas establecen un mínimo, no demuestran que el contenido sea correcto. ## Dar una medida para cada amenaza y decir qué no detiene Las citas son necesarias, pero no suficientes. Empareja cada amenaza con una contramedida concreta e indica expresamente frente a qué protege y frente a qué no protege el control. No introduzcas ataques ajenos al modelo de amenazas declarado sin una advertencia clara. Un control destinado a una capa no debe presentarse como protección frente a una intrusión en otra capa. Añade únicamente orientación que constituya realmente un control o un riesgo de seguridad. Revisa de forma independiente la corrección, la viabilidad para desarrolladores y la relevancia temática; una recomendación incorrecta debe rechazarse aunque esté bien citada. ## Mantener cada cambio pequeño y enlazar en lugar de copiar Limita cada cambio a un solo documento de orientación o a un conjunto pequeño y claramente coordinado. Cuando esos sean los límites declarados por el repositorio, no superes tres documentos de contenido ni 1,500 líneas netas añadidas sin una incidencia de seguimiento aprobada. Mantén los cambios de dependencias, automatización y solo erratas sujetos a sus propias reglas de alcance. Parte de una rama limpia basada en la rama predeterminada y conserva un tema por rama. Nunca abras dos solicitudes de cambio desde la misma rama, porque podrían filtrarse cambios no relacionados entre ellas. Exige una incidencia aprobada antes de proponer un documento de orientación nuevo o reescrito de forma sustancial. No incluyas cambios de formato oportunistas, ediciones masivas ni correcciones no relacionadas. Antes de añadir una sección, busca en el documento actual, los documentos relacionados y el índice del repositorio. Enlaza la orientación existente en vez de reproducirla. Conserva las familias de documentos con estructura radial que sean deliberadas. Los enlaces cruzados coordinados son válidos; copiar la orientación de otro documento no lo es. Si un contenido corresponde a un tema distinto, trasládalo al documento existente o nuevo que proceda, en vez de forzar una ampliación del alcance actual. ## Explicar primero el diseño y usar código solo cuando el tema lo pida Para temas generales, prioriza los patrones arquitectónicos, los principios de diseño y las decisiones de seguridad frente al código específico de un lenguaje. El código envejece con rapidez, y los fragmentos aislados pueden ser inseguros si se copian sin su contexto original. Utiliza código libremente cuando el tema sea intrínsecamente específico de un lenguaje, se centre en inyecciones o parametrización, o trate sobre un refuerzo concreto. Una alta densidad de código es adecuada cuando el detalle ejecutable constituye la orientación de seguridad y no es código repetitivo accesorio. Mantén breve el código ilustrativo, etiqueta los bloques delimitados con un lenguaje cuando resulte práctico y no presentes ejemplos como aptos para producción a menos que se hayan diseñado y revisado conforme a ese estándar. ## Quitar el relleno y recomendar un enfoque claro Suprime los preámbulos genéricos, el contexto repetido, las listas exhaustivas de opciones y las introducciones de moda sin contenido. Recomienda un enfoque concreto y explica únicamente el contexto que un desarrollador necesita para aplicarlo de forma segura. Utiliza inglés estadounidense, ejecuta comprobaciones ortográficas y terminológicas, y mantén las frases accesibles para lectores no nativos. Define las siglas no evidentes la primera vez que aparezcan, pero deja sin explicar las abreviaturas de protocolos y localizadores conocidas universalmente cuando la guía de estilo lo permita. Reescribe o descarta los pasajes que parezcan prosa automatizada genérica. La concisión no debe borrar restricciones, excepciones, límites de amenazas ni el motivo por el que una recomendación es más segura. ## Seguir las reglas del repositorio para Markdown e imágenes Utiliza Markdown y evita el HTML sin procesar, salvo los elementos permitidos expresamente, como `details` y `summary`. Utiliza de forma coherente guiones para las viñetas, negrita de Markdown y citas en bloque. Deja una línea en blanco después de cada encabezado. Un documento habitual comienza con un H1 y una Introducción, continúa con secciones H2 enfocadas y puede terminar con Referencias. De tres a seis secciones H2 es un valor predeterminado útil, no un máximo estricto. No añadas un índice manual cuando las herramientas de publicación lo generen. Sigue el contrato de nombres de archivo del repositorio. Utiliza únicamente letras, números, guiones y guiones bajos, y conserva cualquier sufijo obligatorio, como `_Cheat_Sheet.md`. Crea los documentos nuevos a partir de la plantilla aprobada. Guarda los recursos en el directorio de recursos designado. Utiliza el formato de imagen aprobado, proporciona texto alternativo significativo y referencia los recursos mediante la ruta relativa correcta. Escribe los enlaces integrados con etiquetas descriptivas y utiliza HTTPS siempre que sea posible. ## Ejecutar lint y comprobación de enlaces antes de pedir revisión Ejecuta el linter de Markdown, la comprobación terminológica y el verificador de enlaces definidos por el repositorio antes de proponer cambios. Ejecuta también los controles de alcance, densidad de citas y demás políticas que se apliquen al contenido modificado. Trata un control local o de integración continua fallido como un defecto que debe investigarse, no como un motivo para eludir el control. Revisa la diferencia final para que los cambios generados o automatizados no oculten ediciones no relacionadas. Comprende los límites de la automatización. Los controles mecánicos pueden detectar Markdown mal formado, terminología no permitida, enlaces inactivos, un alcance excesivo y patrones de citas ausentes, pero no pueden determinar si una fuente respalda una afirmación, si el consejo es correcto, si el tema corresponde al documento o si el contenido duplica orientación existente. ## Declarar el uso de IA y revisar desde varios ángulos Declara la asistencia sustancial de IA en la descripción de la solicitud de cambio. Registra el nombre de la herramienta, la versión conocida y el prompt en la sección de declaración designada del repositorio. Este requisito se aplica a todas las herramientas de IA; su omisión puede invalidar la contribución. Revisa la orientación de seguridad en dimensiones distintas: corrección de seguridad, viabilidad para desarrolladores, calidad de fuentes y enlaces, duplicación y ubicación, y calidad lingüística. Los revisores especializados pueden trabajar de forma independiente, pero sus conclusiones deben consolidarse en un único veredicto basado en pruebas. Utiliza resultados explícitos, como aceptar, solicitar cambios o cerrar. Cita pruebas concretas para los hallazgos que bloqueen la aprobación, distingue los fallos mecánicos de los fallos de criterio y no apruebes únicamente porque existan citas o controles automatizados.