Manter a documentação sincronizada com a tua base de código

Cenário 1: Documentação inicial do projeto

Herdaste um repositório com documentação mínima. Os novos membros da equipa têm dificuldade em entender a base de código e precisas criar documentação abrangente rapidamente.

Configurar o teu workspace

1. Abre o repositório no IBM Bob IDE.
2. Abre a interface de chat do Bob: Option + Command + B (macOS) ou Ctrl + Alt + B (Windows)

Gerar contexto legível por IA com /init

O primeiro passo é dar ao Bob conhecimento sobre o teu projeto. Muda para o modo Agent e executa:

/init

O Bob analisa o teu repositório e gera:

• AGENTS.md na raiz do repositório (contexto principal do projeto)
• .bob/rules-code/AGENTS-code.md (contexto específico do modo Agent)
• .bob/rules-plan/AGENTS-plan.md (contexto específico do modo Plan)
• .bob/rules-ask/AGENTS-ask.md (contexto específico do modo Ask)

Estes ficheiros contêm:

• Estrutura do código e diretórios chave
• Stack tecnológico e dependências
• Comandos de build, test e lint
• Padrões de código e convenções

Por que importa: Estes ficheiros AGENTS.md servem como bases de conhecimento que o Bob referencia em cada conversa. Em vez de reanalisar toda a tua base de código cada vez, o Bob tem contexto persistente sobre o teu projeto.

Rever o contexto gerado

Abre AGENTS.md e revê o que o Bob descobriu:

cat AGENTS.md

Verás um resumo estruturado do teu projeto. Se o Bob perdeu detalhes importantes (regras de negócio, convenções de deployment, práticas da equipa), edita AGENTS.md para adicioná-los. Este ficheiro foi concebido para ser personalizado.

Criar um modo Docs Architect

Cria agora um modo personalizado que gera documentação orientada a utilizadores. Este modo usará o contexto AGENTS.md para criar documentação para humanos, não para IA.

1. Clica no ícone settings no painel do Bob para abrir as Definições.
2. Seleciona o separador Modes.
3. Clica no ícone + para criar um novo modo.
4. Preenche os seguintes valores:

Para o campo Mode-specific Custom Instructions, copia e cola o seguinte:

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

Clica em Guardar.

O Bob cria um ficheiro custom_modes.yaml em .bob que contém a configuração do modo Docs Architect. Podes editar este ficheiro diretamente para fazer alterações futuras.

Gerar documentação inicial

Muda para o modo Docs Architect e escreve:

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.

O Bob gera ficheiros de documentação. Revê-os para verificar a sua precisão, faz edições e depois commita:

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

Resultado: Passaste de documentação mínima para docs abrangentes em minutos, não horas.

Cenário 2: Documentar uma nova funcionalidade

Acabaste de implementar uma nova funcionalidade. O código funciona, mas o teu README, guia de contribuição e docs de API ainda descrevem o estado antigo do projeto. Este é o ponto mais comum onde a documentação fica para trás — a funcionalidade está feita, mas os docs ainda não alcançaram.

Veja como fechar essa lacuna usando o Bob.

Escrever a funcionalidade com a ajuda do Bob

Durante o desenvolvimento, muda para o modo Agent para que o Bob possa ajudar com a implementação. Como o Bob já tem contexto do projeto do /init que executaste no Cenário 1, entende a estrutura do teu código, dependências e convenções — tornando as suas sugestões mais relevantes do que começar do zero.

Escreve a funcionalidade como normalmente farias, usando o Bob para completar código, refatorizar ou fazer perguntas sobre a base de código existente.

Executar novamente /init para atualizar o contexto IA

Uma vez implementada a funcionalidade, o contexto do Bob está desatualizado — foi gerado antes de o teu novo código existir. Atualiza-o:

/init

O Bob reanalisa o repositório e atualiza AGENTS.md para refletir o que mudou — novos módulos, dependências atualizadas e quaisquer novos padrões de código que deteta.

Confirma que a atualização capturou as tuas alterações:

git diff AGENTS.md .bob/

Se o diff mostrar a tua nova funcionalidade, o Bob está pronto para gerar documentação precisa. Se algo importante estiver em falta, edita AGENTS.md manualmente antes de continuar.

Gerar documentação para a nova funcionalidade

Agora muda para o modo Docs Architect. Como acabaste de atualizar AGENTS.md, o Bob tem uma imagem precisa da nova funcionalidade e pode gerar documentação que reflete a implementação real — não uma suposição.

Pede ao Bob o que precisa de ser atualizado:

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.

Revê a documentação gerada para verificar a sua precisão — verifica que os exemplos de código correspondem à tua implementação — depois commita tudo junto:

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

Resultado: A tua funcionalidade e a sua documentação são desenvolvidas juntas e committadas na mesma pull request.

Cenário 3: Revisão de código com verificações de documentação

Um membro da equipa envia uma pull request que adiciona um novo endpoint de API. Precisas garantir que a documentação seja atualizada.

Rever as alterações de código

git diff main feature-branch

Vês novos endpoints de API mas sem atualizações de documentação.

Verificar se /init foi executado

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

Se não há alterações em AGENTS.md, o programador não executou /init. Pede-lhe para:

1. Executar /init para atualizar o contexto IA
2. Usar o Docs Architect para atualizar os docs orientados a utilizadores

Gerar documentação em falta

Se estás a rever a PR, podes gerar a documentação tu mesmo:

git checkout feature-branch

No Bob, executa /init, depois muda para o 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.

Commita as atualizações de documentação:

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: A documentação faz parte do teu processo de revisão de código, não um pensamento secundário.

Cenário 4: Integrar um novo membro da equipa

Um novo programador junta-se à tua equipa. Precisa entender rapidamente a base de código.

Fazê-lo executar /init

O novo programador clona o repositório e executa:

/init

O Bob gera novos ficheiros AGENTS.md que refletem o estado atual da base de código. O novo programador pode agora:

1. Ler AGENTS.md para entender a estrutura do projeto
2. Ler README.md para instruções de início
3. Ler CONTRIBUTING.md para o workflow de desenvolvimento

Usar o modo Ask para exploração

O novo programador pode usar o modo Ask do Bob para explorar a 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?

O Bob responde usando o contexto de AGENTS.md e o código-fonte real.

Gerar docs de integração personalizados

Se o teu projeto não tem documentação de integração, usa o 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: Os novos membros da equipa podem ficar a par em horas em vez de dias.

Cenário 5: Manter a documentação ao longo do tempo

O teu projeto está em desenvolvimento há meses. O código mudou significativamente e a documentação está a começar a divergir.

Detetar divergência na documentação

Executa /init para ver o que mudou:

/init

Revê o diff:

git diff AGENTS.md .bob/

Grandes alterações indicam evolução significativa do código. Este é o teu sinal de que a documentação orientada a utilizadores precisa de atualizações.

Atualizar a documentação sistematicamente

Usa o Docs Architect para atualizar a documentação:

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.

Estabelecer um calendário de manutenção

Adiciona atualizações de documentação ao teu workflow regular:

• Mensal: Executar /init e rever as alterações
• Antes dos lançamentos: Atualizar toda a documentação
• Após refatorações importantes: Regenerar a documentação afetada
• Nas revisões de código: Verificar se /init foi executado e se os docs foram atualizados

Automatizar a deteção de divergência (avançado)

Para equipas que querem aplicar a higiene da documentação em CI, adiciona uma verificação de pull request que verifique se AGENTS.md e .bob/ estão atualizados. A verificação executaria /init na branch e falharia se o output difere do que foi committado — sinalizando que o programador se esqueceu de atualizar o contexto IA antes de abrir a PR. Combina isso com a checklist do template de PR da secção de boas práticas para tornar as atualizações de documentação uma parte obrigatória do teu processo de revisão.

Resultado: A documentação mantém-se sincronizada com o código através da manutenção regular.