Automatyczne generowanie dokumentacji z Cursor Agent
Twoja biblioteka open-source właśnie osiągnęła 10 000 gwiazdek na GitHubie. Najczęściej głosowane issue? “Proszę, dodajcie dokumentację.” README ma jeden przykład kodu sprzed dwóch lat, nie ma dokumentacji API, architektura istnieje wyłącznie w głowie głównego programisty, a za tydzień wychodzi duże wydanie v2.0 z 40 zmianami łamiącymi kompatybilność. Potrzebujesz kompleksowej dokumentacji — referencja API, przewodnik startowy, przewodnik migracji, przegląd architektury — i potrzebujesz jej przed wydaniem.
Pisanie dokumentacji od zera to jedno z najbardziej żmudnych zadań w tworzeniu oprogramowania. Czytanie dokumentacji, którą ktoś inny powinien był napisać, to jedno z najbardziej frustrujących. Cursor wypełnia tę lukę, czytając twoją bazę kodu i generując dokładną, ustrukturyzowaną dokumentację, którą następnie możesz dopracować ludzkim osądem. AI obsługuje mechaniczną ekstrakcję — sygnatury funkcji, typy parametrów, wartości zwracane, generowanie przykładów — podczas gdy ty zajmujesz się pracą redakcyjną, aby dokumentacja była jasna i użyteczna.
Co wyniesiesz z tej lekcji
Dział zatytułowany „Co wyniesiesz z tej lekcji”- Prompt analizy bazy kodu, który identyfikuje każde publiczne API i generuje adnotacje JSDoc/TSDoc
- Prompt dokumentacji architektury, który produkuje diagramy Mermaid ze struktury kodu
- Generator przewodnika startowego, który tworzy krok po kroku tutoriale z działających testów
- Prompt przewodnika migracji, który porównuje dwie wersje i generuje dokument zmian łamiących kompatybilność
- Workflow monitorowania świeżości dokumentacji, który wykrywa, gdy dokumentacja rozjeżdża się z kodem
Workflow
Dział zatytułowany „Workflow”Krok 1: Przeprowadź audyt istniejących luk w dokumentacji
Dział zatytułowany „Krok 1: Przeprowadź audyt istniejących luk w dokumentacji”Zanim cokolwiek wygenerujesz, zrozum, co istnieje, a czego brakuje. Użyj trybu Ask do analizy luk.
Krok 2: Wygeneruj adnotacje JSDoc dla publicznego API
Dział zatytułowany „Krok 2: Wygeneruj adnotacje JSDoc dla publicznego API”Najszybsza wygrana w dokumentacji to dodanie dokumentacji inline do kodu źródłowego. Tryb Agent może przeczytać implementacje funkcji i wygenerować dokładne komentarze JSDoc.
Krok 3: Wygeneruj dokumentację architektury
Dział zatytułowany „Krok 3: Wygeneruj dokumentację architektury”Dokumentacja architektury starzeje się szybciej niż jakikolwiek inny typ dokumentacji, ponieważ wymaga zrozumienia systemu jako całości, a nie tylko poszczególnych funkcji. Sztuczka polega na generowaniu jej z samego kodu, aby można było ją regenerować, gdy architektura się zmieni.
@src
Wygeneruj dokumentację architektury w docs/architecture.md:
1. Przegląd systemu: Diagram Mermaid pokazujący główne moduły i ich zależności2. Przepływ danych: Jak dane przepływają przez system od wejścia do wyjścia3. Kluczowe abstrakcje: 5 najważniejszych interfejsów/typów i co reprezentują4. Punkty rozszerzenia: Gdzie użytkownicy mogą dostosowywać lub rozszerzać bibliotekę (pluginy, hooki, callbacki)5. Decyzje projektowe: Dlaczego kod jest tak ustrukturyzowany (wywnioskuj ze wzorców -- dlaczego używa architektury pipeline? dlaczego są osobne fazy parse i transform?)6. Charakterystyka wydajności: Złożoność Big-O kluczowych operacji, wzorce użycia pamięci
Użyj Mermaid dla wszystkich diagramów. Utrzymaj dokument poniżej 1000 słów -- dokumentacja architektury,której nikt nie czyta, jest gorsza niż brak dokumentacji architektury.Krok 4: Utwórz przewodnik startowy z testów
Dział zatytułowany „Krok 4: Utwórz przewodnik startowy z testów”Twój zestaw testów to kopalnia złota działających przykładów kodu. Agent może je wyekstrahować i zamienić w tutorial.
Krok 5: Wygeneruj przewodnik migracji dla zmian łamiących kompatybilność
Dział zatytułowany „Krok 5: Wygeneruj przewodnik migracji dla zmian łamiących kompatybilność”Dla wydań major, przewodnik migracji to różnica między użytkownikami, którzy sprawnie się aktualizują, a tymi, którzy zostają na starej wersji na zawsze.
@git
Wygeneruj przewodnik migracji v1-do-v2 w docs/migration-v2.md:
1. Uruchom `git diff v1.0.0..HEAD -- src/`, aby zobaczyć wszystkie zmiany w kodzie2. Zidentyfikuj każdą zmianę łamiącą kompatybilność: - Zmienione nazwy funkcji lub parametrów - Zmienione typy zwracane - Usunięte API - Zmienione wartości domyślne - Nowe wymagane parametry3. Dla każdej zmiany łamiącej kompatybilność pokaż: - Jak wyglądał kod v1 - Jak powinien wyglądać kod v2 - Jednozdaniowe wyjaśnienie, dlaczego zmiana została wprowadzona4. Pogrupuj zmiany według kategorii: zmiany API, zmiany typów, zmiany zachowania, usunięte funkcjonalności5. Dodaj sekcję "Szybka migracja" ze wzorcami find-and-replace dla najczęstszych zmian6. Dodaj sekcję "Codemods", jeśli jakiekolwiek zmiany można zautomatyzować
Uporządkuj od najczęstszych do najrzadszych -- zmiana, która dotyczy najwięcej użytkowników, idzie pierwsza.Krok 6: Skonfiguruj monitoring świeżości dokumentacji
Dział zatytułowany „Krok 6: Skonfiguruj monitoring świeżości dokumentacji”Dokumentacja, która rozjeżdża się z kodem, jest gorsza niż brak dokumentacji — aktywnie wprowadza w błąd. Skonfiguruj automatyczne sprawdzenia.
Generowanie diagramów z Mermaid
Dział zatytułowany „Generowanie diagramów z Mermaid”Cursor może generować diagramy Mermaid, które renderują się bezpośrednio w GitHub, GitLab i większości narzędzi dokumentacyjnych. Dla złożonych systemów rozbij diagramy na ukierunkowane widoki.
@src
Wygeneruj te diagramy Mermaid dla dokumentacji architektury:
1. Graf zależności modułów: Pokaż, które moduły importują z których innych modułów. Użyj subgrafów dla logicznych grupowań (core, plugins, utils).
2. Cykl życia żądania: Diagram sekwencji pokazujący, jak typowe żądanie przepływa przez system od entry pointu do odpowiedzi.
3. Maszyna stanów: Jeśli istnieją jakiekolwiek przejścia stanów (stany połączeń, stany transakcji itp.), wygeneruj diagram stanów.
4. Hierarchia klas: Pokaż relacje dziedziczenia i kompozycji między kluczowymi klasami/interfejsami.
Wynik jako ogrodzone bloki kodu mermaid, które mogę wkleić bezpośrednio do plików markdown.Kiedy to się psuje
Dział zatytułowany „Kiedy to się psuje”Wygenerowana dokumentacja opisuje, co kod robi, a nie dlaczego. AI może przeczytać implementację i wyjaśnić mechanikę, ale nie zna kontekstu biznesowego. Zawsze przeglądaj wygenerowaną dokumentację i dodawaj “dlaczego” samodzielnie — dlaczego ta funkcja istnieje? Jaki problem rozwiązuje? Kiedy użytkownik powinien sięgnąć po to zamiast po tamto?
Przykłady kodu tak naprawdę nie działają. AI generuje przykłady, które wyglądają poprawnie, ale mają błędy importu, brakujący kod konfiguracyjny lub zakładają kontekst, który nie istnieje. Sprawdzenie CI dokumentacji z Kroku 6 wyłapuje te problemy, ale podczas początkowej generacji zawsze przetestuj ręcznie kilka pierwszych przykładów.
Diagramy architektury stają się nieczytelne. Dla dużych baz kodu pełny graf zależności to nieczytelny kołtun. Powiedz AI, aby skupiło się na konkretnym podsystemie lub ograniczyło diagram do modułów najwyższego poziomu. “Pokaż mi 10 najczęściej importowanych modułów i ich relacje” jest bardziej użyteczne niż “pokaż mi wszystko.”
Przewodnik migracji pomija subtelne zmiany zachowania. AI wykrywa zmiany sygnatur API niezawodnie, ale ma trudności ze zmianami zachowania, gdzie sygnatura funkcji pozostaje taka sama, ale output się zmienia. Uzupełnij automatyczny przewodnik migracji o ręcznie napisaną sekcję “Zmiany zachowania” dla wszystkiego, o czym wiesz, że się zmieniło, a czego kod jawnie nie pokazuje.
Generowanie dokumentacji rozdyma bazę kodu. Wygenerowana dokumentacja bywa gadatliwa. Ustaw budżet słów w swoich promptach (“Utrzymaj poniżej 500 słów”) i edytuj agresywnie po wygenerowaniu. Zwięzła dokumentacja, którą ludzie faktycznie czytają, jest nieskończenie cenniejsza niż kompleksowa dokumentacja, której nikt nie otwiera.
Adnotacje JSDoc stają się nieaktualne. Dokumentacja inline starzeje się tak samo jak dokumentacja zewnętrzna. Hook pre-commit z Kroku 6 wykrywa, gdy sygnatury funkcji zmieniają się bez aktualizacji dokumentacji, ale nie potrafi wykryć, gdy zmienia się zachowanie przy zachowaniu tej samej sygnatury. Okresowa regeneracja (miesięczna lub per wydanie) wyłapuje rozbieżności.