Utrzymywanie dokumentacji zsynchronizowanej z bazą kodu

Scenariusz 1: Wstępna dokumentacja projektu

Odziedziczyłeś repozytorium z minimalną dokumentacją. Nowi członkowie zespołu mają trudności ze zrozumieniem bazy kodu, a ty musisz szybko stworzyć kompleksową dokumentację.

Konfigurowanie workspace'u

1. Otwórz repozytorium w IBM Bob IDE.
2. Otwórz interfejs czatu Bob: Option + Command + B (macOS) lub Ctrl + Alt + B (Windows)

Generowanie kontekstu czytelnego dla AI za pomocą /init

Pierwszym krokiem jest przekazanie Bobowi wiedzy o twoim projekcie. Przełącz się na tryb Agent i uruchom:

/init

Bob skanuje twoje repozytorium i generuje:

• AGENTS.md w głównym katalogu repozytorium (główny kontekst projektu)
• .bob/rules-code/AGENTS-code.md (kontekst specyficzny dla trybu Agent)
• .bob/rules-plan/AGENTS-plan.md (kontekst specyficzny dla trybu Plan)
• .bob/rules-ask/AGENTS-ask.md (kontekst specyficzny dla trybu Ask)

Te pliki zawierają:

• Strukturę kodu i kluczowe katalogi
• Stack technologiczny i zależności
• Polecenia build, test i lint
• Wzorce kodu i konwencje

Dlaczego to ma znaczenie: Te pliki AGENTS.md służą jako bazy wiedzy, do których Bob odwołuje się w każdej rozmowie. Zamiast ponownie analizować całą bazę kodu za każdym razem, Bob ma trwały kontekst dotyczący twojego projektu.

Przeglądanie wygenerowanego kontekstu

Otwórz AGENTS.md i przejrzyj, co Bob odkrył:

cat AGENTS.md

Zobaczysz ustrukturyzowane podsumowanie swojego projektu. Jeśli Bob pominął ważne szczegóły (zasady biznesowe, konwencje wdrożeniowe, praktyki zespołu), edytuj AGENTS.md, aby je dodać. Ten plik jest przeznaczony do dostosowania.

Tworzenie trybu Docs Architect

Utwórz teraz niestandardowy tryb, który generuje dokumentację dla użytkowników. Ten tryb użyje kontekstu AGENTS.md do tworzenia dokumentacji dla ludzi, a nie dla AI.

1. Kliknij ikonę settings w panelu Boba, aby otworzyć Ustawienia.
2. Wybierz zakładkę Modes.
3. Kliknij ikonę +, aby utworzyć nowy tryb.
4. Wypełnij następujące wartości:

W polu Mode-specific Custom Instructions skopiuj i wklej następujące:

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

Kliknij Zapisz.

Bob tworzy plik custom_modes.yaml w .bob, który zawiera konfigurację trybu Docs Architect. Możesz edytować ten plik bezpośrednio, aby wprowadzać przyszłe zmiany.

Generowanie wstępnej dokumentacji

Przełącz się na tryb Docs Architect i napisz:

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 generuje pliki dokumentacji. Przejrzyj je pod kątem dokładności, wprowadź zmiany, a następnie commituj:

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

Wynik: W ciągu minut, a nie godzin, przeszedłeś od minimalnej dokumentacji do kompleksowych dokumentów.

Scenariusz 2: Dokumentowanie nowej funkcji

Właśnie zaimplementowałeś nową funkcję. Kod działa, ale twój plik README, przewodnik dla współpracowników i dokumentacja API nadal opisują stary stan projektu. To najczęstszy punkt, w którym dokumentacja zostaje w tyle — funkcja jest gotowa, ale dokumentacja za nią nie nadążyła.

Oto jak zamknąć tę lukę za pomocą Boba.

Pisanie funkcji z pomocą Boba

Podczas tworzenia przełącz się na tryb Agent, aby Bob mógł pomóc z implementacją. Ponieważ Bob już ma kontekst projektu z /init, który uruchomiłeś w Scenariuszu 1, rozumie strukturę twojego kodu, zależności i konwencje — dzięki czemu jego sugestie są bardziej trafne niż zaczynanie od zera.

Pisz funkcję tak jak normalnie, używając Boba do uzupełniania kodu, refaktoryzacji lub zadawania pytań dotyczących istniejącej bazy kodu.

Ponowne uruchomienie /init w celu aktualizacji kontekstu AI

Po zaimplementowaniu funkcji kontekst Boba jest nieaktualny — został wygenerowany przed istnieniem twojego nowego kodu. Zaktualizuj go:

/init

Bob ponownie skanuje repozytorium i aktualizuje AGENTS.md, aby odzwierciedlić zmiany — nowe moduły, zaktualizowane zależności i nowe wzorce kodu, które wykrywa.

Potwierdź, że aktualizacja uwzględniła twoje zmiany:

git diff AGENTS.md .bob/

Jeśli diff pokazuje twoją nową funkcję, Bob jest gotowy do wygenerowania dokładnej dokumentacji. Jeśli brakuje czegoś ważnego, edytuj AGENTS.md ręcznie przed kontynuowaniem.

Generowanie dokumentacji dla nowej funkcji

Teraz przełącz się na tryb Docs Architect. Ponieważ właśnie zaktualizowałeś AGENTS.md, Bob ma dokładny obraz nowej funkcji i może generować dokumentację odzwierciedlającą rzeczywistą implementację — a nie zgadywać.

Poproś Boba o zaktualizowanie tego, co wymaga zmian:

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.

Przejrzyj wygenerowaną dokumentację pod kątem dokładności — sprawdź, czy przykłady kodu faktycznie odpowiadają twojej implementacji — a następnie commituj wszystko razem:

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

Wynik: Twoja funkcja i jej dokumentacja są tworzone razem i commitowane w tym samym pull requeście.

Scenariusz 3: Przegląd kodu ze sprawdzaniem dokumentacji

Członek zespołu przesyła pull request, który dodaje nowy endpoint API. Musisz upewnić się, że dokumentacja jest zaktualizowana.

Przeglądanie zmian kodu

git diff main feature-branch

Widzisz nowe endpointy API, ale żadnych aktualizacji dokumentacji.

Sprawdzanie, czy /init został uruchomiony

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

Jeśli nie ma zmian w AGENTS.md, deweloper nie uruchomił /init. Poproś go, aby:

1. Uruchomił /init w celu aktualizacji kontekstu AI
2. Użył Docs Architect do aktualizacji dokumentacji dla użytkowników

Generowanie brakującej dokumentacji

Jeśli przeglądasz PR, możesz sam wygenerować dokumentację:

git checkout feature-branch

W Bobie uruchom /init, a następnie przełącz się na tryb 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.

Commituj aktualizacje dokumentacji:

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

Wynik: Dokumentacja jest częścią procesu przeglądu kodu, a nie sprawą drugorzędną.

Scenariusz 4: Onboarding nowego członka zespołu

Nowy deweloper dołącza do twojego zespołu. Musi szybko zrozumieć bazę kodu.

Polecenie uruchomienia /init

Nowy deweloper klonuje repozytorium i uruchamia:

/init

Bob generuje świeże pliki AGENTS.md odzwierciedlające aktualny stan bazy kodu. Nowy deweloper może teraz:

1. Przeczytać AGENTS.md, aby zrozumieć strukturę projektu
2. Przeczytać README.md w celu uzyskania instrukcji startowych
3. Przeczytać CONTRIBUTING.md, aby poznać przepływ pracy deweloperskiej

Używanie trybu Ask do eksploracji

Nowy deweloper może używać trybu Ask Boba do eksploracji bazy kodu:

@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 odpowiada, używając kontekstu z AGENTS.md i rzeczywistego kodu źródłowego.

Generowanie spersonalizowanej dokumentacji onboardingowej

Jeśli twojemu projektowi brakuje dokumentacji onboardingowej, użyj 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.

Wynik: Nowi członkowie zespołu mogą wdrożyć się w ciągu godzin zamiast dni.

Scenariusz 5: Utrzymywanie dokumentacji w czasie

Twój projekt jest w trakcie tworzenia od miesięcy. Kod znacznie się zmienił, a dokumentacja zaczyna odbiegać od rzeczywistości.

Wykrywanie rozbieżności dokumentacji

Uruchom /init, aby zobaczyć, co się zmieniło:

/init

Przejrzyj diff:

git diff AGENTS.md .bob/

Duże zmiany wskazują na znaczną ewolucję kodu. To sygnał, że dokumentacja dla użytkowników wymaga aktualizacji.

Systematyczna aktualizacja dokumentacji

Użyj Docs Architect do odświeżenia dokumentacji:

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.

Ustalanie harmonogramu konserwacji

Dodaj aktualizacje dokumentacji do swojego regularnego przepływu pracy:

• Co miesiąc: Uruchamiaj /init i przeglądaj zmiany
• Przed wydaniami: Aktualizuj całą dokumentację
• Po większych refaktoryzacjach: Regeneruj dokumentację dla zmienionych obszarów
• W przeglądach kodu: Sprawdzaj, czy /init był uruchomiony i czy dokumentacja została zaktualizowana

Automatyzacja wykrywania rozbieżności (zaawansowane)

Dla zespołów chcących egzekwować higienę dokumentacji w CI, dodaj sprawdzenie pull requesta, które weryfikuje, czy AGENTS.md i .bob/ są aktualne. Sprawdzenie uruchamiałoby /init na gałęzi, a następnie kończyłoby się niepowodzeniem, jeśli wynik różni się od tego, co zostało zacommitowane — sygnalizując, że deweloper zapomniał zaktualizować kontekst AI przed otwarciem PR. Połącz to z listą kontrolną szablonu PR z sekcji najlepszych praktyk, aby aktualizacje dokumentacji stały się wymaganą częścią procesu przeglądu.

Wynik: Dokumentacja pozostaje zsynchronizowana z kodem dzięki regularnemu utrzymaniu.