Apprends à garder la documentation technique synchronisée avec ta base de code en utilisant la commande init d'IBM Bob et un mode Docs Architect personnalisé dans des scénarios de développement réels — développement de fonctionnalités, révisions de code, intégration et maintenance continue.

La documentation est souvent traitée comme une réflexion après coup dans le développement logiciel — quelque chose que tu fais après que le code est « terminé ». Mais en pratique, la documentation doit évoluer continuellement aux côtés de ton code. Ce tutoriel te montre comment la documentation de code par IA fonctionne réellement dans un workflow de développement pratique avec IBM Bob.

Plutôt que de se concentrer sur la théorie, tu verras comment intégrer les capacités de documentation de Bob dans ton processus de développement quotidien : depuis la configuration initiale du projet jusqu'au développement de fonctionnalités, aux révisions de code et aux sorties de version. Tu utiliseras la commande /init pour établir un contexte lisible par l'IA et créer un mode Docs Architect personnalisé qui génère de la documentation lisible par les humains à chaque étape du développement.

Ce que tu accomplis

Dans ce tutoriel, tu apprends à :

Configurer la documentation de code par IA dans ton workflow de développement

Utiliser /init pour créer et maintenir un contexte de projet lisible par l'IA

Créer un mode Docs Architect personnalisé pour générer de la documentation destinée aux utilisateurs

Intégrer les mises à jour de documentation dans les cycles de développement de fonctionnalités

Maintenir la documentation à travers les révisions de code et les pull requests

Garder la documentation synchronisée avec les changements de code dans le contrôle de version

Prérequis

Pour compléter ce tutoriel, tu as besoin des éléments suivants :

Bob IDE installé.

Un dépôt Git que tu veux documenter. N'importe quel projet local ou dépôt open source fonctionne.

Comment fonctionne la documentation de code par IA en pratique

Les workflows de documentation traditionnels séparent l'écriture du code de l'écriture de la documentation. Les développeurs écrivent du code, puis (peut-être) mettent à jour la documentation plus tard. Cela crée un fossé où la documentation prend du retard, devient inexacte et finit par être ignorée.

IBM Bob est un IDE conçu pour prendre en charge l'ensemble du cycle de vie du développement logiciel — et cela inclut la documentation de code par IA. Bob rend la génération de documentation suffisamment rapide pour qu'elle se produise en parallèle des changements de code, de sorte que la documentation reste à jour plutôt que de prendre du retard. Voici comment ça fonctionne en pratique :

Le workflow de documentation par IA

L'IA apprend ta base de code : La commande /init analyse ton dépôt et crée des fichiers AGENTS.md — des résumés structurés qui servent de bases de connaissances pour le grand modèle de langage

L'IA génère de la documentation : Les modes personnalisés comme Docs Architect utilisent ce contexte pour générer de la documentation destinée aux utilisateurs (READMEs, guides, docs API)

Tu révises et affines : La documentation générée par l'IA est un point de départ ; tu la valides, la modifies et la commites avec le code

L'IA reste synchronisée : Relancer /init après les changements de code met à jour la compréhension de l'IA, permettant des mises à jour rapides de la documentation

Ce workflow intègre la documentation dans ton processus de développement plutôt que de la traiter comme une tâche séparée.

Scénarios du monde réel

Ce tutoriel présente des scénarios pratiques que tu rencontreras :

Démarrer un nouveau projet : Configurer la documentation de zéro

Ajouter une fonctionnalité : Mettre à jour les docs pendant le développement

Révision de code : Vérifier la documentation dans les pull requests

Intégration : Utiliser les docs générées par IA pour aider les nouveaux membres de l'équipe

Maintenance : Garder les docs à jour à mesure que la base de code évolue

Scénario 1 : Documentation initiale du projet

Tu as hérité d'un dépôt avec une documentation minimale. Les nouveaux membres de l'équipe ont du mal à comprendre la base de code, et tu dois créer une documentation complète rapidement.

Configurer ton espace de travail

Ouvre le dépôt dans IBM Bob IDE.
Ouvre l'interface de chat Bob : Option + Command + B (macOS) ou Ctrl + Alt + B (Windows)

Générer un contexte lisible par l'IA avec /init

La première étape consiste à donner à Bob des connaissances sur ton projet. Passe en mode Agent et exécute :

/init

Bob analyse ton dépôt et génère :

AGENTS.md à la racine du dépôt (contexte principal du projet)
.bob/rules-code/AGENTS-code.md (contexte spécifique au mode Agent)
.bob/rules-plan/AGENTS-plan.md (contexte spécifique au mode Plan)
.bob/rules-ask/AGENTS-ask.md (contexte spécifique au mode Ask)

Ces fichiers contiennent :

La structure du code et les répertoires clés
La stack technologique et les dépendances
Les commandes de build, test et lint
Les patterns de code et les conventions

Pourquoi c'est important : Ces fichiers AGENTS.md servent de bases de connaissances que Bob référence dans chaque conversation. Au lieu de réanalyser toute ta base de code à chaque fois, Bob a un contexte persistant sur ton projet.

Réviser le contexte généré

Ouvre AGENTS.md et révise ce que Bob a découvert :

cat AGENTS.md

Tu verras un résumé structuré de ton projet. Si Bob a manqué des détails importants (règles métier, conventions de déploiement, pratiques d'équipe), modifie AGENTS.md pour les ajouter. Ce fichier est fait pour être personnalisé.

Créer un mode Docs Architect

Crée maintenant un mode personnalisé qui génère de la documentation destinée aux utilisateurs. Ce mode utilisera le contexte AGENTS.md pour créer de la documentation pour les humains, pas pour l'IA.

Clique sur l'icône settings dans le panneau Bob pour ouvrir les paramètres.
Sélectionne l'onglet Modes.
Clique sur l'icône + pour créer un nouveau mode.
Remplis les valeurs suivantes :

Champ	Valeur
Name	Docs Architect
Slug	docs-architect
Role Definition	You are a documentation architect and writer who creates user-facing documentation. You work alongside AGENTS.md files (created by /init) which provide AI-readable technical context. Your role is to create human-readable documentation that complements, not duplicates, the AGENTS.md content. You focus on user needs: getting started guides, conceptual overviews, tutorials, and onboarding materials. Include code snippets with clear explanations. Add JSDoc comments (JavaScript) or Javadoc (Java) and docstrings where helpful to improve code quality.
When to use	Use this mode for writing and maintaining user-facing documentation such as READMEs, onboarding guides, and API docs. Not for writing or modifying application code.
Available Tools	Read, Edit

Pour le champ Mode-specific Custom Instructions, copie et colle ce qui suit :

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

Clique sur Enregistrer.

Bob crée un fichier custom_modes.yaml dans .bob qui contient la configuration du mode Docs Architect. Tu peux modifier ce fichier directement pour faire de futures modifications.

Générer la documentation initiale

Passe en mode Docs Architect et demande :

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 génère des fichiers de documentation. Révise-les pour leur exactitude, fais des modifications, puis commite :

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

Résultat : Tu es passé d'une documentation minimale à une documentation complète en minutes, pas en heures.

Scénario 2 : Documenter une nouvelle fonctionnalité

Tu viens d'implémenter une nouvelle fonctionnalité. Le code fonctionne, mais ton README, ton guide de contribution et tes docs API décrivent toujours l'ancien état du projet. C'est le point le plus courant où la documentation prend du retard — la fonctionnalité est terminée, mais les docs n'ont pas rattrapé.

Voici comment combler ce fossé avec Bob.

Écrire la fonctionnalité avec l'aide de Bob

Pendant le développement, passe en mode Agent pour que Bob puisse aider à l'implémentation. Parce que Bob a déjà le contexte du projet depuis le /init que tu as exécuté dans le Scénario 1, il comprend ta structure de code, tes dépendances et tes conventions — rendant ses suggestions plus pertinentes que de partir de zéro.

Écris la fonctionnalité comme tu le ferais normalement, en utilisant Bob pour la complétion de code, le refactoring ou pour poser des questions sur la base de code existante.

Relancer /init pour mettre à jour le contexte IA

Une fois la fonctionnalité implémentée, le contexte de Bob est obsolète — il a été généré avant que ton nouveau code existe. Mets-le à jour :

/init

Bob réanalyse le dépôt et met à jour AGENTS.md pour refléter ce qui a changé — nouveaux modules, dépendances mises à jour et tous les nouveaux patterns de code qu'il détecte.

Confirme que la mise à jour a capturé tes changements :

git diff AGENTS.md .bob/

Si le diff montre ta nouvelle fonctionnalité, Bob est prêt à générer une documentation précise. Si quelque chose d'important manque, modifie AGENTS.md manuellement avant de continuer.

Générer la documentation pour la nouvelle fonctionnalité

Passe maintenant en mode Docs Architect. Puisque tu viens de mettre à jour AGENTS.md, Bob a une image précise de la nouvelle fonctionnalité et peut générer une documentation qui reflète l'implémentation réelle — pas une supposition.

Demande à Bob ce qui doit être mis à jour :

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.

Révise la documentation générée pour son exactitude — vérifie que les exemples de code correspondent réellement à ton implémentation — puis commite tout ensemble :

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

Résultat : Ta fonctionnalité et sa documentation sont développées ensemble et commitées dans le même pull request.

Scénario 3 : Révision de code avec vérifications de documentation

Un membre de l'équipe soumet un pull request qui ajoute un nouvel endpoint API. Tu dois t'assurer que la documentation est mise à jour.

Réviser les changements de code

git diff main feature-branch

Tu vois de nouveaux endpoints API mais aucune mise à jour de documentation.

Vérifier si /init a été exécuté

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

S'il n'y a pas de changements dans AGENTS.md, le développeur n'a pas exécuté /init. Demande-lui de :

Exécuter /init pour mettre à jour le contexte IA
Utiliser Docs Architect pour mettre à jour les docs destinées aux utilisateurs

Générer la documentation manquante

Si tu révises le PR, tu peux générer la documentation toi-même :

git checkout feature-branch

Dans Bob, exécute /init, puis passe en mode 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.

Commite les mises à jour de documentation :

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

Résultat : La documentation fait partie de ton processus de révision de code, pas une réflexion après coup.

Scénario 4 : Intégrer un nouveau membre de l'équipe

Un nouveau développeur rejoint ton équipe. Il doit comprendre rapidement la base de code.

Lui faire exécuter /init

Le nouveau développeur clone le dépôt et exécute :

/init

Bob génère des fichiers AGENTS.md frais qui reflètent l'état actuel de la base de code. Le nouveau développeur peut maintenant :

Lire AGENTS.md pour comprendre la structure du projet
Lire README.md pour les instructions de démarrage
Lire CONTRIBUTING.md pour le workflow de développement

Utiliser le mode Ask pour l'exploration

Le nouveau développeur peut utiliser le mode Ask de Bob pour explorer la base de code :

@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 répond en utilisant le contexte de AGENTS.md et le code source réel.

Générer des docs d'intégration personnalisées

Si ton projet manque de documentation d'intégration, utilise 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.

Résultat : Les nouveaux membres de l'équipe peuvent se mettre à niveau en heures plutôt qu'en jours.

Scénario 5 : Maintenir la documentation dans le temps

Ton projet est en développement depuis des mois. Le code a changé significativement et la documentation commence à dériver.

Détecter la dérive de documentation

Exécute /init pour voir ce qui a changé :

/init

Révise le diff :

git diff AGENTS.md .bob/

Les changements importants indiquent une évolution significative du code. C'est ton signal que la documentation destinée aux utilisateurs nécessite des mises à jour.

Mettre à jour la documentation de façon systématique

Utilise Docs Architect pour rafraîchir la documentation :

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.

Établir un calendrier de maintenance

Ajoute les mises à jour de documentation à ton workflow régulier :

Mensuel : Exécuter /init et réviser les changements
Avant les releases : Mettre à jour toute la documentation
Après les refactorings majeurs : Régénérer la documentation affectée
Dans les révisions de code : Vérifier si /init a été exécuté et si les docs ont été mises à jour

Automatiser la détection de dérive (avancé)

Pour les équipes qui veulent appliquer l'hygiène de documentation en CI, ajoute une vérification de pull request qui vérifie que AGENTS.md et .bob/ sont à jour. La vérification exécuterait /init sur la branche, puis échouerait si la sortie diffère de ce qui a été commité — signalant que le développeur a oublié de mettre à jour le contexte IA avant d'ouvrir le PR. Associe cela à la liste de contrôle du template PR de la section des bonnes pratiques pour faire des mises à jour de documentation une partie obligatoire de ton processus de révision.

Résultat : La documentation reste synchronisée avec le code grâce à une maintenance régulière.

Bonnes pratiques pour les workflows de documentation de code par IA

Intégrer /init dans ton processus de développement

Fais de /init une partie régulière de ton workflow :

Exécute-le après avoir ajouté de nouveaux modules ou fonctionnalités

Exécute-le après les refactorings majeurs

Exécute-le avant de créer des pull requests

Exécute-le mensuellement pour les projets actifs

Commiter le contexte IA et les docs utilisateurs ensemble

Commite toujours les fichiers AGENTS.md avec la documentation destinée aux utilisateurs :

git add AGENTS.md .bob/ README.md docs/
git commit -m "docs: update for [feature/change]"

Cela garde les deux couches synchronisées dans ton système de contrôle de version et rend ton dépôt auto-documenté pour des outils comme Mintlify qui génèrent de la documentation API à partir de fichiers source Markdown.

Traiter les docs générées par IA comme des brouillons

Les outils de documentation de code alimentés par IA génèrent des points de départ, pas des produits finis. Toujours :

Réviser pour l'exactitude

Vérifier que les exemples de code fonctionnent

Vérifier les détails techniques

Ajuster le ton et le style

Ajouter du contexte que l'IA pourrait manquer

Utiliser les mentions de contexte pour la précision

Quand tu mets à jour des parties spécifiques de la documentation, utilise les mentions @ :

@src/auth @docs/authentication.md Update the authentication documentation to reflect the new OAuth flow

Cela aide Bob à se concentrer sur le code et la documentation pertinents.

Inclure la documentation dans les révisions de code

Ajoute des vérifications de documentation à ton template de pull request :

## Documentation Checklist
- [ ] Ran `/init` to update AGENTS.md
- [ ] Updated README if user-facing changes
- [ ] Updated API docs if endpoints changed
- [ ] Added code examples for new features
- [ ] Verified all code snippets work

Maintenir la qualité du code avec les docstrings

Utilise Bob pour ajouter des docstrings et des commentaires JSDoc :

@src/api Review all functions in this directory and add JSDoc comments to any that lack them. Include parameter types, return types, and usage examples.

Cela améliore à la fois la qualité du code et la documentation.

Résolution des scénarios courants

La documentation ne correspond pas au code

Problème : La documentation générée décrit des fonctionnalités qui n'existent pas ou manque des changements récents.

Solution :

Exécuter /init pour mettre à jour le contexte IA

Réviser les changements AGENTS.md pour voir ce que Bob a détecté

Régénérer la documentation affectée avec Docs Architect

Vérifier manuellement que les exemples de code fonctionnent

/init manque du contexte important

Problème : AGENTS.md manque de détails spécifiques au projet comme les règles métier ou les conventions de déploiement.

Solution : Modifie AGENTS.md manuellement pour ajouter le contexte que /init ne pouvait pas détecter. Ce fichier est fait pour être personnalisé.

Les mises à jour de documentation prennent trop de temps

Problème : La régénération de la documentation pour les grands projets prend du temps.

Solution : Utilise les mentions de contexte pour mettre à jour des sections spécifiques :

@docs/api.md @src/api/users.ts Update only the user API documentation to reflect the new endpoints

Les membres de l'équipe oublient de mettre à jour les docs

Problème : Les pull requests manquent de mises à jour de documentation.

Solution :

Ajouter des vérifications de documentation au template PR

Configurer des vérifications CI qui vérifient que /init a été exécuté

Faire de la révision de documentation une partie du processus de révision de code

L'IA génère des exemples de code incorrects

Problème : Les snippets de code dans la documentation ne fonctionnent pas ou utilisent des APIs obsolètes.

Solution :

Toujours tester les exemples de code générés

Utiliser les mentions de contexte pour pointer Bob vers le code actuel : @src/api/current-implementation.ts

Mettre à jour les instructions du mode Docs Architect pour mettre l'accent sur la précision

Prochaines étapes

Tu as appris comment la documentation de code par IA fonctionne en pratique avec IBM Bob. Tu as vu comment :

Intégrer /init dans ton workflow de développement

Utiliser des modes personnalisés pour générer de la documentation destinée aux utilisateurs

Maintenir la documentation à travers le développement de fonctionnalités et les révisions de code

Garder la documentation synchronisée avec les changements de code

Appliquer ce workflow à tes projets

Commencer avec /init : Exécute-le sur ton projet actuel

Créer ton mode : Personnalise Docs Architect selon les besoins de ton équipe

Documenter pendant le développement : Mets à jour les docs avec les changements de code

Réviser dans les PRs : Fais de la documentation une partie de la révision de code

Maintenir régulièrement : Planifie des exécutions mensuelles de /init

Garder la documentation synchronisée avec ta base de code

Sur cette page