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.
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.
Ten prompt uruchom w trybie Agent — korzysta z git diff przez zintegrowany terminal, czego tryb Ask nie potrafi. Odwołaj się do folderu źródłowego przez @src/ (prawdziwą referencję kontekstu pliku/folderu) zamiast tokenu @git i pozwól, by Agent sam uruchomił diff.
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.
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.