Dokumentation mit deiner Codebasis synchron halten

Szenario 1: Initiale Projektdokumentation

Du hast ein Repository mit minimaler Dokumentation übernommen. Neue Teammitglieder haben Schwierigkeiten, die Codebasis zu verstehen, und du musst schnell umfassende Dokumentation erstellen.

Deinen Workspace einrichten

1. Öffne das Repository in IBM Bob IDE.
2. Öffne die Bob-Chat-Oberfläche: Option + Command + B (macOS) oder Ctrl + Alt + B (Windows)

KI-lesbaren Kontext mit /init generieren

Der erste Schritt besteht darin, Bob Wissen über dein Projekt zu geben. Wechsle in den Agenten-Modus und führe aus:

/init

Bob scannt dein Repository und generiert:

• AGENTS.md im Repository-Root (Haupt-Projektkontext)
• .bob/rules-code/AGENTS-code.md (Agenten-Modus-spezifischer Kontext)
• .bob/rules-plan/AGENTS-plan.md (Plan-Modus-spezifischer Kontext)
• .bob/rules-ask/AGENTS-ask.md (Ask-Modus-spezifischer Kontext)

Diese Dateien enthalten:

• Codestruktur und wichtige Verzeichnisse
• Technologie-Stack und Abhängigkeiten
• Build-, Test- und Lint-Befehle
• Code-Muster und Konventionen

Warum das wichtig ist: Diese AGENTS.md-Dateien dienen als Wissensbasen, auf die Bob in jeder Konversation verweist. Statt jedes Mal deine gesamte Codebasis neu zu analysieren, hat Bob persistenten Kontext über dein Projekt.

Den generierten Kontext überprüfen

Öffne AGENTS.md und überprüfe, was Bob entdeckt hat:

cat AGENTS.md

Du wirst eine strukturierte Zusammenfassung deines Projekts sehen. Wenn Bob wichtige Details verpasst hat (Geschäftsregeln, Deployment-Konventionen, Team-Praktiken), bearbeite AGENTS.md, um sie hinzuzufügen. Diese Datei ist zum Anpassen gedacht.

Einen Docs-Architect-Modus erstellen

Erstelle jetzt einen benutzerdefinierten Modus, der benutzerseitige Dokumentation generiert. Dieser Modus verwendet den AGENTS.md-Kontext, um Dokumentation für Menschen zu erstellen, nicht für KI.

1. Klicke auf das settings-Symbol im Bob-Panel, um die Einstellungen zu öffnen.
2. Wähle die Registerkarte Modi.
3. Klicke auf das +-Symbol, um einen neuen Modus zu erstellen.
4. Fülle folgende Werte aus:

Für das Feld Mode-specific Custom Instructions kopiere und füge Folgendes ein:

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

Klicke auf Speichern.

Bob erstellt eine custom_modes.yaml-Datei in .bob, die die Docs-Architect-Modus-Konfiguration enthält. Du kannst diese Datei direkt bearbeiten, um zukünftige Änderungen vorzunehmen.

Initiale Dokumentation generieren

Wechsle in den Docs-Architect-Modus und promte:

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 generiert Dokumentationsdateien. Überprüfe sie auf Richtigkeit, nimm Änderungen vor, dann committe:

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

Ergebnis: Du bist in Minuten statt in Stunden von minimaler Dokumentation zu umfassenden Docs gelangt.

Szenario 2: Ein neues Feature dokumentieren

Du hast gerade ein neues Feature implementiert. Der Code funktioniert, aber dein README, dein Contributing-Guide und deine API-Docs beschreiben noch den alten Projektzustand. Das ist der häufigste Punkt, an dem Dokumentation zurückfällt – das Feature ist fertig, aber die Docs haben nicht aufgeholt.

So schließt du diese Lücke mit Bob.

Das Feature mit Bobs Hilfe schreiben

Wechsle während der Entwicklung in den Agenten-Modus, damit Bob bei der Implementierung helfen kann. Da Bob bereits Projektkontext aus dem /init hat, das du in Szenario 1 ausgeführt hast, versteht er deine Codestruktur, Abhängigkeiten und Konventionen – wodurch seine Vorschläge relevanter sind als wenn man von vorne anfängt.

Schreibe das Feature wie gewohnt und nutze Bob für Code-Completion, Refactoring oder Fragen über die bestehende Codebasis.

/init erneut ausführen, um den KI-Kontext zu aktualisieren

Sobald das Feature implementiert ist, ist Bobs Kontext veraltet – er wurde vor dem Existieren deines neuen Codes generiert. Aktualisiere ihn:

/init

Bob scannt das Repository neu und aktualisiert AGENTS.md, um die Änderungen widerzuspiegeln – neue Module, aktualisierte Abhängigkeiten und alle neuen Code-Muster, die er erkennt.

Bestätige, dass die Aktualisierung deine Änderungen erfasst hat:

git diff AGENTS.md .bob/

Wenn der Diff dein neues Feature zeigt, ist Bob bereit, genaue Dokumentation zu generieren. Wenn etwas Wichtiges fehlt, bearbeite AGENTS.md manuell bevor du weitermachst.

Dokumentation für das neue Feature generieren

Wechsle jetzt in den Docs-Architect-Modus. Da du gerade AGENTS.md aktualisiert hast, hat Bob ein genaues Bild des neuen Features und kann Dokumentation generieren, die die tatsächliche Implementierung widerspiegelt – keine Schätzung.

Promte Bob mit dem, was aktualisiert werden muss:

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.

Überprüfe die generierte Dokumentation auf Richtigkeit – prüfe, ob die Code-Beispiele tatsächlich mit deiner Implementierung übereinstimmen – dann committe alles zusammen:

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

Ergebnis: Dein Feature und seine Dokumentation werden gemeinsam entwickelt und in demselben Pull Request committed.

Szenario 3: Code-Review mit Dokumentationsprüfungen

Ein Teammitglied reicht einen Pull Request ein, der einen neuen API-Endpunkt hinzufügt. Du musst sicherstellen, dass die Dokumentation aktualisiert wird.

Die Code-Änderungen überprüfen

git diff main feature-branch

Du siehst neue API-Endpunkte, aber keine Dokumentationsaktualisierungen.

Prüfen, ob /init ausgeführt wurde

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

Wenn es keine Änderungen an AGENTS.md gibt, hat der Entwickler /init nicht ausgeführt. Bitte ihn:

1. /init ausführen, um den KI-Kontext zu aktualisieren
2. Docs Architect verwenden, um benutzerseitige Docs zu aktualisieren

Fehlende Dokumentation generieren

Wenn du den PR reviewst, kannst du die Dokumentation selbst generieren:

git checkout feature-branch

Führe in Bob /init aus, dann wechsle in den Docs-Architect-Modus:

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.

Committe die Dokumentationsaktualisierungen:

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

Ergebnis: Dokumentation ist Teil deines Code-Review-Prozesses, keine nachträgliche Überlegung.

Szenario 4: Onboarding eines neuen Teammitglieds

Ein neuer Entwickler kommt in dein Team. Er muss die Codebasis schnell verstehen.

/init ausführen lassen

Der neue Entwickler klont das Repository und führt aus:

/init

Bob generiert frische AGENTS.md-Dateien, die den aktuellen Zustand der Codebasis widerspiegeln. Der neue Entwickler kann jetzt:

1. AGENTS.md lesen, um die Projektstruktur zu verstehen
2. README.md lesen für Getting-Started-Anweisungen
3. CONTRIBUTING.md lesen für den Entwicklungs-Workflow

Ask-Modus zur Erkundung verwenden

Der neue Entwickler kann Bobs Ask-Modus nutzen, um die Codebasis zu erkunden:

@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 antwortet mit dem Kontext aus AGENTS.md und dem tatsächlichen Quellcode.

Personalisierte Onboarding-Docs generieren

Wenn dein Projekt keine Onboarding-Dokumentation hat, verwende 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.

Ergebnis: Neue Teammitglieder können sich in Stunden statt Tagen einarbeiten.

Szenario 5: Dokumentation über Zeit pflegen

Dein Projekt befindet sich seit Monaten in der Entwicklung. Der Code hat sich erheblich verändert, und die Dokumentation beginnt zu driften.

Dokumentationsdrift erkennen

Führe /init aus, um zu sehen, was sich geändert hat:

/init

Überprüfe den Diff:

git diff AGENTS.md .bob/

Große Änderungen weisen auf eine erhebliche Code-Evolution hin. Das ist dein Signal, dass benutzerseitige Dokumentation aktualisiert werden muss.

Dokumentation systematisch aktualisieren

Verwende Docs Architect, um die Dokumentation aufzufrischen:

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.

Einen Wartungsplan etablieren

Füge Dokumentationsaktualisierungen zu deinem regulären Workflow hinzu:

• Monatlich: /init ausführen und Änderungen überprüfen
• Vor Releases: Alle Dokumentation aktualisieren
• Nach großen Refactorings: Betroffene Dokumentation neu generieren
• In Code-Reviews: Prüfen, ob /init ausgeführt wurde und Docs aktualisiert wurden

Drift-Erkennung automatisieren (fortgeschritten)

Für Teams, die Dokumentationshygiene in CI durchsetzen wollen: Füge eine Pull-Request-Prüfung hinzu, die verifiziert, dass AGENTS.md und .bob/ auf dem neuesten Stand sind. Die Prüfung würde /init gegen den Branch ausführen und fehlschlagen, wenn die Ausgabe von dem abweicht, was committed wurde – was signalisiert, dass der Entwickler vergessen hat, den KI-Kontext zu aktualisieren, bevor der PR eröffnet wurde. Kombiniere dies mit der PR-Template-Checkliste aus dem Abschnitt Best Practices, um Dokumentationsaktualisierungen zu einem erforderlichen Teil deines Review-Prozesses zu machen.

Ergebnis: Dokumentation bleibt durch regelmäßige Wartung synchron mit dem Code.