README del Proyecto
Un README no es un manual de parámetros ni un anuncio. Es el camino más corto para ayudar a un nuevo lector a confiar en un proyecto y obtener un primer resultado.
No rellenes secciones por el simple hecho de hacerlo. Un lector debería poder responder tres preguntas: ¿Qué es esto? ¿Es adecuado para mí? ¿Puedo obtener un primer resultado y entender los límites de riesgo?
Principios Fundamentales
- Cada afirmación necesita evidencia. Omite afirmaciones que no puedan verificarse en el repositorio o confirmarse con el usuario; no suavices una suposición convirtiéndola en prosa vaga.
- Una Guía de inicio rápido es obligatoria: proporciona la ruta real más corta desde la instalación hasta un resultado útil. Si sus comandos no pueden verificarse, pregunta en lugar de dejar espacios en blanco o inventarlos.
- Cuando ya exista un README, pregunta si se debe reemplazar, conservar material seleccionado o extenderlo en su lugar. No adivines ni sobrescribas el contenido escrito por el usuario.
- Establece identidad y un punto de entrada en la parte superior (above the fold). Para proyectos públicos, usa el nombre/logo del proyecto, una descripción de una línea, insignias reales y navegación, luego coloca la Guía de inicio rápido inmediatamente después. Usa un GIF/captura de pantalla solo cuando transmita más que texto.
- Muestra en lugar de afirmar: la salida de terminal, capturas de pantalla, código y números verificados son más contundentes que los adjetivos.
- Organiza por tarea, no por parámetro. Explica “¿qué quiero hacer → qué comando lo hace”; deja las listas completas de opciones para
--help. - Elimina cualquier línea que no ayude al lector a decidir, confiar o actuar.
- Si el proyecto toca archivos locales, bases de datos, credenciales, redes o llamadas a modelos, explica qué lee, escribe y envía fuera del dispositivo, y su postura predeterminada de solo lectura/confirmación/respaldo/cierre ante fallos. No hagas promesas de seguridad sin evidencia en el código.
- Mantén el README como puerta de entrada; enlaza detalles profundos a
docs/oCONTRIBUTING.mden lugar de convertir el README en un manual. - Adáptate al proyecto; no fuerces una plantilla única para CLI, MCP, bibliotecas, aplicaciones y repositorios de investigación.
- Evita alardes no verificados como “líder de la industria”, “listo para producción” o “rendimiento extremo”. Consulta las barreras de seguridad en
content-writing.
Elige la Audiencia
Clasifica al lector del README para definir el nivel de detalle:
- Personal (proyecto personal, herramienta interna o script personal): el lector eres principalmente tú, incluyendo tu yo futuro. Requerido: una descripción de una línea, Guía de inicio rápido y limitaciones conocidas. Las insignias, guía de contribución, canales comunitarios, historial de estrellas y hoja de ruta son opcionales. La línea base es que puedas ejecutarlo tres meses después.
- Público (código abierto, software distribuido o compartido en equipo): el lector es un desconocido. Incluye descripción, valor, Guía de inicio rápido, uso, configuración, índice de documentación, contribución y licencia. Agrega insignias e información comunitaria solo cuando realmente existan.
Por defecto, usa público si el repositorio es público, está publicado en un gestor de paquetes o tiene usuarios externos; usa personal para proyectos personales privados y trabajos puntuales. Para casos mixtos, usa el nivel de detalle de público.
Elige el Modo
| Modo | Cuándo usarlo | Primer paso |
|---|---|---|
| crear | No existe README, o el usuario solicita explícitamente una reescritura | Inspeccionar el repositorio y recopilar hechos. |
| mejorar | Existe un README y necesita trabajo | Leerlo, preguntar cómo manejar el contenido existente, luego proceder. |
| auditar | El usuario solicita solo un diagnóstico | Verificar cada afirmación del README contra el repositorio e informar hallazgos. |
Puerta: Si existe un README, detente para que el usuario elija: (1) reemplazarlo por completo, (2) reescribirlo conservando material específico, o (3) extenderlo en su lugar. “Ayúdame a escribir un README” no implica la opción 1.
Parte Superior y Estilo para Herramientas de Desarrollo (Proyectos Públicos)
Los lectores deciden si continuar después de una pantalla. La primera pantalla debe mostrar qué hace el proyecto.
Para CLI, MCP y herramientas de desarrollo locales, prefiere documentación de desarrollador discreta y verificable:
<div align="center">
Logotipo opcional
# Nombre del proyecto
**Descripción de una línea**
Solo insignias reales
Selector de idioma (solo cuando existe el otro README)
Navegación con anclas (cuando el documento supera las 100 líneas)
</div>
---
Resumen de capacidades: comandos/herramientas reales, entradas, salidas y postura de seguridad predeterminada
Tres reglas:
- Descripción de una línea: Hazla memorable y de aproximadamente una línea: qué es, para quién es y su distinción factual más importante. Guarda principios y contexto para después.
- Resumen de capacidades: Enumera comandos/herramientas reales, entradas, salidas, objetos de lectura/escritura y la postura de seguridad predeterminada. Evita afirmaciones genéricas como “rápido, seguro e inteligente”.
- Guía de inicio rápido a continuación: Prefiere de 1 a 3 pasos cortos. El paso final debe verificar la instalación o el descubrimiento del servicio. Deja la configuración compleja para después.
El material visual es opcional. Elige GIFs/asciinema, capturas de pantalla y salida real del terminal solo cuando agreguen información. Si no hay un recurso de demostración, no inventes uno; proporciona comandos reales, salida esperada y pasos de verificación.
Los proyectos personales pueden omitir logotipos, insignias y navegación, pero una descripción de una línea y la salida visible siguen siendo útiles.
Escalera de Evidencia
Antes de escribir cada afirmación, clasifica su evidencia:
| Nivel | Fuente | Uso |
|---|---|---|
| 1 | En el repositorio: código fuente, pruebas, ejemplos, configuración, CI, etiquetas, capturas de pantalla | Escríbela directamente. |
| 2 | Confirmada por el usuario: posicionamiento, diferenciación, métricas, capturas de pantalla, casos | Escríbela directamente. |
| 3 | Verificable externamente: página del paquete, versión, benchmark público | Escríbela con un enlace. |
| 4 | Sin fuente | Omítela. Pregunta si es importante; de lo contrario, elimínala. |
Nunca inventes comandos de instalación, parámetros CLI, firmas de API, claves de configuración, variables de entorno, rutas, números de rendimiento, afirmaciones de compatibilidad, términos de licencia ni enlaces comunitarios.
Consulta references/evidence.md para el análisis del repositorio y las reglas de evidencia.
Flujo de Trabajo
- Clasificar audiencia y modo: personal/público y crear/mejorar/auditar. Si existe un README, pregunta cómo manejarlo antes de modificarlo.
- Recopilar evidencia del repositorio: inspeccionar metadatos del paquete, puntos de entrada, estructura, configuración, documentación, Git/CI, activos, rutas de lectura/escritura, credenciales, redes, llamadas a modelos y códigos de error. Esta etapa recopila hechos, no conclusiones; consulta
references/evidence.md. - Clasificar el proyecto y el lector: CLI, MCP, biblioteca, aplicación, proyecto de investigación, habilidad de agente o monorepo. Usa esto para seleccionar secciones; consulta
references/structure.md. - Verificar Guía de inicio rápido: encontrar y verificar el primer comando que produce un resultado útil después de la instalación. Si no puede verificarse, pregunta y no avances más allá de esta puerta.
- Planificar las secciones: seleccionar secciones según el tipo de proyecto e identificar evidencia para cada una. Omite las secciones sin soporte. También decide el diseño de la parte superior, la verificación de la Guía de inicio rápido y si se necesitan secciones de seguridad/flujo de datos, códigos de error o solución de problemas.
- Redactar: identidad y capacidades → Guía de inicio rápido → características → instalación/configuración → uso basado en tareas → fundamentos/contexto → límites de seguridad/privacidad → errores/solución de problemas → limitaciones conocidas → documentación de desarrollo/profunda. Explica los fundamentos después de que el lector tenga un camino funcional, no antes.
- Ejecutar la puerta de calidad: verificar cada elemento en
references/checklist.md, especialmente la precisión factual y los pasos ejecutables. - Entregar: proporciona un borrador en la conversación por defecto; escribe en disco solo cuando se solicite explícitamente. Vuelve a ejecutar la lista de verificación antes de escribir.
Salida
Expresa de manera concisa: (1) audiencia y modo; (2) tipo de proyecto y lector objetivo; (3) plan de secciones y fuente de evidencia para cada sección; (4) el borrador del README; (5) afirmaciones que requieren confirmación del usuario porque falta evidencia; y (6) omisiones conocidas. Nunca etiquetes una suposición como verificada. Enumera explícitamente las afirmaciones no respaldadas en lugar de disfrazarlas con lenguaje vago.
Señales de Alarma
- Falta o está en blanco la Guía de inicio rápido, o comandos inventados sin un punto de entrada en el repositorio.
- Sobrescribir un README existente sin preguntar cómo manejarlo.
- Afirmaciones no confirmadas de rendimiento, compatibilidad, número de usuarios o estrellas.
- Insignias que apuntan a CI, paquetes o licencias inexistentes.
- Rellenar secciones de plantilla con encabezados vacíos o “TODO/próximamente”.
- Incrustar un manual completo de la API en lugar de enlazarlo.
- Reproducir una tabla larga de
--helpen lugar de mostrar comandos basados en tareas. - Una pantalla de apertura con solo eslóganes o principios, sin un punto de entrada real ni resultado verificable.
- Omitir información de seguridad/flujo de datos para herramientas que tocan datos locales, credenciales, redes o llamadas a modelos.
- Prometer operación de solo lectura, sin fuga de datos, comportamiento de cierre ante fallos o configuración cero sin evidencia de código/pruebas.
- Solución de problemas que solo dice “reiniciar” sin un síntoma, código de error, causa y remedio.
- Una descripción de una línea que es un párrafo, o fundamentos que aparecen antes del primer camino ejecutable.
- Adjetivos como “potente”, “elegante”, “extremo” o “listo para usar” que reemplazan evidencia.
- Forzar guías de contribución, códigos de conducta o enlaces comunitarios en un proyecto personal cuando no existen.
- Diagramas de arquitectura que contienen componentes o relaciones de llamada inexistentes.
- Escribir archivos sin autorización del usuario.
Referencias
Lee solo lo necesario:
references/structure.md: flujo de lectura, selección de secciones por tipo de proyecto y guía para escribir secciones.references/evidence.md: análisis del repositorio, niveles de evidencia y afirmaciones que no deben inventarse.references/checklist.md: puerta de calidad previa a la escritura para hechos, usabilidad, presentación y lenguaje.