Mantener la documentación sincronizada con tu base de código

Escenario 1: Documentación inicial del proyecto

Has heredado un repositorio con documentación mínima. Los nuevos miembros del equipo tienen dificultades para entender la base de código y necesitas crear documentación completa rápidamente.

Configurar tu workspace

1. Abre el repositorio en IBM Bob IDE.
2. Abre la interfaz de chat de Bob: Option + Command + B (macOS) o Ctrl + Alt + B (Windows)

Generar contexto legible por IA con /init

El primer paso es darle a Bob conocimiento sobre tu proyecto. Cambia al modo Agent y ejecuta:

/init

Bob escanea tu repositorio y genera:

• AGENTS.md en la raíz del repositorio (contexto principal del proyecto)
• .bob/rules-code/AGENTS-code.md (contexto específico del modo Agent)
• .bob/rules-plan/AGENTS-plan.md (contexto específico del modo Plan)
• .bob/rules-ask/AGENTS-ask.md (contexto específico del modo Ask)

Estos archivos contienen:

• Estructura del código y directorios clave
• Stack tecnológico y dependencias
• Comandos de build, test y lint
• Patrones de código y convenciones

Por qué importa: Estos archivos AGENTS.md sirven como bases de conocimiento que Bob referencia en cada conversación. En lugar de re-analizar toda tu base de código cada vez, Bob tiene contexto persistente sobre tu proyecto.

Revisar el contexto generado

Abre AGENTS.md y revisa qué descubrió Bob:

cat AGENTS.md

Verás un resumen estructurado de tu proyecto. Si Bob omitió detalles importantes (reglas de negocio, convenciones de despliegue, prácticas del equipo), edita AGENTS.md para agregarlos. Este archivo está pensado para ser personalizado.

Crear un modo Docs Architect

Crea ahora un modo personalizado que genere documentación orientada a usuarios. Este modo usará el contexto AGENTS.md para crear documentación para humanos, no para IA.

1. Haz clic en el ícono settings en el panel de Bob para abrir Ajustes.
2. Selecciona la pestaña Modes.
3. Haz clic en el ícono + para crear un nuevo modo.
4. Rellena los siguientes valores:

Para el campo Mode-specific Custom Instructions, copia y pega lo siguiente:

When documenting a project:
1. Review AGENTS.md files to understand project structure and technical details
2. Create user-facing documentation (READMEs, getting started guides, tutorials)
3. Avoid duplicating technical details from AGENTS.md (build commands, code patterns)
4. Focus on user workflows, conceptual overviews, and practical code examples
5. Include code blocks with clear explanations
6. Add docstrings and JSDoc comments to improve code quality

Generate:
- README.md explaining project purpose and navigation
- CONTRIBUTING.md with onboarding steps for new contributors
- Getting started guide with code snippets
- Conceptual documentation explaining architectural decisions

Haz clic en Guardar.

Bob crea un archivo custom_modes.yaml en .bob que contiene la configuración del modo Docs Architect. Puedes editar este archivo directamente para hacer cambios futuros.

Generar documentación inicial

Cambia al modo Docs Architect y solicita:

I've run /init to establish project context. Please create comprehensive documentation for this project:

1. Review AGENTS.md to understand the project structure
2. Create a README.md with:
   - Project overview and purpose
   - Quick start guide with code examples
   - Project structure explanation
   - Links to additional documentation
3. Create CONTRIBUTING.md with:
   - Development setup instructions
   - How to run tests
   - How to submit a pull request
   - Code style guidelines
4. Identify gaps in the codebase that need better documentation (missing docstrings, unclear functions)

Focus on making the technical details from AGENTS.md accessible to new developers.

Bob genera archivos de documentación. Revísalos para verificar su precisión, haz ediciones y luego commitea:

git add AGENTS.md .bob/ README.md CONTRIBUTING.md
git commit -m "docs: initial project documentation with AI assistance"

Resultado: Has pasado de documentación mínima a docs completas en minutos, no en horas.

Escenario 2: Documentar una nueva funcionalidad

Acabas de implementar una nueva funcionalidad. El código funciona, pero tu README, guía de contribución y docs de API todavía describen el estado anterior del proyecto. Este es el punto más común donde la documentación se queda atrás — la funcionalidad está terminada, pero los docs no han alcanzado.

Así es como cerrar esa brecha usando Bob.

Escribir la funcionalidad con la ayuda de Bob

Mientras desarrollas, cambia al modo Agent para que Bob pueda ayudar con la implementación. Como Bob ya tiene contexto del proyecto desde el /init que ejecutaste en el Escenario 1, entiende la estructura de tu código, dependencias y convenciones — haciendo sus sugerencias más relevantes que empezar desde cero.

Escribe la funcionalidad como lo harías normalmente, usando Bob para completar código, refactorizar o hacer preguntas sobre la base de código existente.

Volver a ejecutar /init para actualizar el contexto IA

Una vez que la funcionalidad está implementada, el contexto de Bob está desactualizado — fue generado antes de que existiera tu nuevo código. Actualízalo:

/init

Bob vuelve a escanear el repositorio y actualiza AGENTS.md para reflejar lo que ha cambiado — nuevos módulos, dependencias actualizadas y cualquier nuevo patrón de código que detecte.

Confirma que la actualización capturó tus cambios:

git diff AGENTS.md .bob/

Si el diff muestra tu nueva funcionalidad, Bob está listo para generar documentación precisa. Si algo importante falta, edita AGENTS.md manualmente antes de continuar.

Generar documentación para la nueva funcionalidad

Ahora cambia al modo Docs Architect. Como acabas de actualizar AGENTS.md, Bob tiene una imagen precisa de la nueva funcionalidad y puede generar documentación que refleja la implementación real — no una suposición.

Solicita a Bob qué necesita actualizarse:

I've added a new feature to the project. Please update the documentation:

1. Add a section to README.md explaining:
   - What the feature does
   - How to configure and use it
   - A code snippet showing basic usage
2. Update CONTRIBUTING.md if the development workflow has changed
3. Create a dedicated docs page that covers:
   - How the feature works
   - Relevant API endpoints or interfaces
   - Code examples for common use cases
   - Code explanations for non-obvious logic
   - Troubleshooting tips

Include code blocks with clear explanations. Add docstrings to any functions that lack them.

Revisa la documentación generada para verificar su precisión — verifica que los ejemplos de código coincidan con tu implementación — luego commitea todo junto:

git add src/ AGENTS.md .bob/ README.md CONTRIBUTING.md docs/
git commit -m "feat: add [feature name] with documentation"

Resultado: Tu funcionalidad y su documentación se desarrollan juntas y se commitean en el mismo pull request.

Escenario 3: Revisión de código con verificaciones de documentación

Un miembro del equipo envía un pull request que agrega un nuevo endpoint de API. Necesitas asegurarte de que la documentación se actualiza.

Revisar los cambios de código

git diff main feature-branch

Ves nuevos endpoints de API pero ninguna actualización de documentación.

Verificar si se ejecutó /init

git diff main feature-branch -- AGENTS.md .bob/

Si no hay cambios en AGENTS.md, el desarrollador no ejecutó /init. Pídele que:

1. Ejecute /init para actualizar el contexto IA
2. Use Docs Architect para actualizar los docs orientados a usuarios

Generar documentación faltante

Si estás revisando el PR, puedes generar la documentación tú mismo:

git checkout feature-branch

En Bob, ejecuta /init, luego cambia al modo Docs Architect:

I'm reviewing a pull request that adds new API endpoints. Please update the documentation:

1. Review the new endpoints in src/api/
2. Update README.md with a brief mention of the new endpoints
3. Update docs/api.md with:
   - Endpoint descriptions
   - Request/response examples with code blocks
   - Authentication requirements
   - Error codes
4. Add JSDoc comments to the endpoint handlers if missing

Focus on making the API easy to understand for other developers.

Commitea las actualizaciones de documentación:

git add AGENTS.md .bob/ README.md docs/api.md src/api/
git commit -m "docs: add documentation for new API endpoints"
git push

Resultado: La documentación es parte de tu proceso de revisión de código, no una ocurrencia tardía.

Escenario 4: Incorporar a un nuevo miembro del equipo

Un nuevo desarrollador se une a tu equipo. Necesita entender la base de código rápidamente.

Hacer que ejecute /init

El nuevo desarrollador clona el repositorio y ejecuta:

/init

Bob genera archivos AGENTS.md frescos que reflejan el estado actual de la base de código. El nuevo desarrollador ahora puede:

1. Leer AGENTS.md para entender la estructura del proyecto
2. Leer README.md para instrucciones de inicio
3. Leer CONTRIBUTING.md para el workflow de desarrollo

Usar el modo Ask para explorar

El nuevo desarrollador puede usar el modo Ask de Bob para explorar la base de código:

@src/auth Explain how authentication works in this project

@src/api What API endpoints are available and what do they do?

@tests How do I run tests for a specific module?

Bob responde usando el contexto de AGENTS.md y el código fuente real.

Generar docs de incorporación personalizadas

Si tu proyecto carece de documentación de incorporación, usa Docs Architect:

Create an onboarding guide for new developers joining this project:

1. Prerequisites (tools, accounts, access)
2. Initial setup steps with code blocks
3. How to run the project locally
4. How to run tests
5. Overview of the codebase structure
6. Common development tasks with examples
7. Where to find help

Make it practical and include code snippets for each step.

Resultado: Los nuevos miembros del equipo pueden ponerse al día en horas en lugar de días.

Escenario 5: Mantener la documentación a lo largo del tiempo

Tu proyecto lleva meses en desarrollo. El código ha cambiado significativamente y la documentación está empezando a desviarse.

Detectar la desviación de documentación

Ejecuta /init para ver qué ha cambiado:

/init

Revisa el diff:

git diff AGENTS.md .bob/

Los cambios grandes indican una evolución significativa del código. Esta es tu señal de que la documentación orientada a usuarios necesita actualizaciones.

Actualizar la documentación sistemáticamente

Usa Docs Architect para actualizar la documentación:

I've run /init and noticed significant changes to the project structure. Please review and update the documentation:

1. Review AGENTS.md changes to understand what's different
2. Update README.md to reflect current project structure
3. Update CONTRIBUTING.md if development workflow has changed
4. Identify any new features that lack documentation
5. Remove documentation for deprecated features
6. Update code examples to match current API

Focus on accuracy—make sure documentation matches the current codebase.

Establecer un calendario de mantenimiento

Agrega actualizaciones de documentación a tu workflow regular:

• Mensual: Ejecutar /init y revisar cambios
• Antes de lanzamientos: Actualizar toda la documentación
• Después de refactorizaciones mayores: Regenerar la documentación afectada
• En revisiones de código: Verificar si se ejecutó /init y si los docs fueron actualizados

Automatizar la detección de desviación (avanzado)

Para equipos que quieren aplicar la higiene de documentación en CI, agrega una verificación de pull request que verifique que AGENTS.md y .bob/ estén actualizados. La verificación ejecutaría /init contra la rama y fallaría si la salida difiere de lo que se commitó — señalando que el desarrollador olvidó actualizar el contexto IA antes de abrir el PR. Combina esto con la lista de verificación del template de PR de la sección de mejores prácticas para hacer que las actualizaciones de documentación sean una parte requerida de tu proceso de revisión.

Resultado: La documentación se mantiene sincronizada con el código a través del mantenimiento regular.