Generowanie i weryfikacja dokumentacji z agentem Cursora

Agent Cursora pisze dokumentację, czytając kod, który ta dokumentacja opisuje: TSDoc dla każdego publicznego eksportu, przewodnik „pierwsze kroki” zbudowany z przechodzących testów, diagramy architektury w Mermaid i przewodnik migracji oparty na git diff. Agent wykonuje ekstrakcję. Poprawności dowodzą mechaniczne bramki — walidacja TypeDoc, kompilowane przykłady, renderowane diagramy i sprawdzone linki — więc człowiek redaguje tylko „dlaczego”.

Ta strona jest dla programistów i tech leadów, którzy utrzymują bibliotekę albo serwis z dokumentacją nienadążającą za kodem. Wersja 2.0 wychodzi w przyszłym tygodniu z 40 zmianami łamiącymi kompatybilność, README wciąż pokazuje przykład z v1, a architektura istnieje tylko w głowie jednego seniora. Nie napiszesz czterech dokumentów ręcznie przed wydaniem, ale nie przeczytasz też linijka po linijce czterech wygenerowanych.

Co zyskujesz dzięki temu workflow

• Prompt audytowy tylko do odczytu, który szereguje nieudokumentowane eksporty według liczby importów w Twoim własnym kodzie.
• Prompty do TSDoc, przewodnika „pierwsze kroki”, przeglądu architektury i przewodnika migracji — każdy przywiązany do źródła prawdy, które agent musi przeczytać.
• Zadanie CI, które nie przechodzi, gdy eksport traci dokumentację, przykład przestaje się kompilować albo link się psuje.
• Jednolinijkowe sprawdzenie, że zmiana „tylko w dokumentacji” nie dotknęła kodu.
• Typowe awarie wygenerowanej dokumentacji i sposób wyjścia z każdej z nich.

Którą dokumentację powinien pisać agent i na podstawie czego?

Wygenerowana dokumentacja jest dokładnie tak wiarygodna jak źródło, z którego powstała. Zanim napiszesz prompt, zdecyduj, który artefakt jest źródłem prawdy dla każdego dokumentu i która bramka udowodni, że dokument nadal się z nim zgadza.

Dokument	Źródło prawdy, które czyta agent	Bramka, która to dowodzi	Co nadal pisze człowiek
TSDoc publicznych eksportów	Implementacja i jej testy	TypeDoc --validation.notDocumented	Intencja: kiedy tego używać, a kiedy nie
Przewodnik „pierwsze kroki”	Przechodzące testy	Typy wyekstrahowanych przykładów się zgadzają	Kolejność pojęć dla nowej osoby
Przegląd architektury	Graf importów i punkty wejścia	Diagramy się renderują; każde twierdzenie cytuje plik	Decyzje projektowe i odrzucone opcje
Przewodnik migracji	git diff między tagami wydań	Zestaw testów z v1 uruchomiony na v2; każda porażka to udokumentowane złamanie kompatybilności	Zmiany zachowania przy niezmienionej sygnaturze

Ostatnia kolumna to miejsce, na które idzie Twój czas przeglądu. Agent nie wie, po co istnieje dany moduł ani dlaczego odrzuciłeś oczywisty projekt, więc nie każ mu zgadywać. Każ mu zostawić oznaczoną lukę i uzupełnij ją sam.

Generowanie dokumentacji z agentem Cursora krok po kroku

Pracuj na gałęzi, jeden dokument na jedną rozmowę z agentem. Świeża rozmowa na każdy dokument utrzymuje mały kontekst, a każdy diff da się przejrzeć osobno.

Zrób audyt luk w dokumentacji, zanim cokolwiek wygenerujesz

Zacznij w Plan Mode, który Cursor opisuje jako tworzenie „detailed implementation plans before writing any code” (dokumentacja Cursora, sprawdzone 2026-08-28). Audyt czyta i raportuje bez zmieniania kodu, więc błędne założenie kosztuje Cię ponowne uruchomienie, a nie cofanie zmian.

Prompt do skopiowania: audyt luk w dokumentacji

Audit the documentation of this package. Do not edit any file.

1. List every symbol exported from src/index.ts (follow re-exports).
2. For each export, report: has a TSDoc summary (yes/no), documents every
   parameter (yes/no), has an @example (yes/no).
3. Count how many files in src/ and tests/ import each export, and sort the
   undocumented ones by that count, highest first.
4. Check README.md and docs/ for: installation, a first working example,
   an architecture overview, and a migration guide. Report which are missing
   and which reference symbols that no longer exist.

Output a table, then a prioritized list of the 10 exports to document first.
Cite a file path for every claim. If you cannot find evidence, say so
instead of guessing.

Liczba importów to przybliżenie wpływu na użytkowników, które agent potrafi policzyć z kodu. Reguła „cytuj ścieżkę pliku” sprawia, że każde ustalenie da się sprawdzić: otwierasz wskazany plik i twierdzenie albo tam jest, albo nie.

Ustaw regułę dokumentacji, żeby każda rozmowa trzymała ten sam standard

Przed przebiegami generowania zapisz swoje konwencje jako regułę projektu, żeby druga i dziesiąta rozmowa pisały tak samo jak pierwsza. Gdzie przechowywane są reguły i jak Cursor je stosuje, opisuje strona o regułach projektu w Cursorze, a wersje dla całego zespołu — własne reguły i szablony.

# Documentation standard

- Document exported symbols only. Never document private helpers.
- One-sentence summary in the present tense, then @param, @returns, @throws.
- Every @example imports from the package name, not from a relative path,
  and must compile as written.
- Never change executable code while documenting. If the code looks wrong,
  add a line to docs/doc-questions.md and move on.
- Where intent cannot be read from code, write TODO(docs-why) instead of guessing.

Zapisz to jako regułę projektu w ustawieniach reguł Cursora; lokalizację pliku podaje strona o regułach projektu.

Najważniejsze są dwie ostatnie linie. Pierwsza nie pozwala, by commity „z dokumentacją” ukrywały zmiany zachowania. Druga zamienia martwe pole agenta w listę, którą człowiek przeszuka podczas swojego przebiegu.

Wygeneruj TSDoc dla publicznego API

Do przebiegu zapisującego przełącz się na agenta i przekaż mu uszeregowaną listę z audytu.

Prompt do skopiowania: TSDoc dla 10 najważniejszych eksportów

Add TSDoc to the 10 exports listed below, following the documentation rule.

For each export:
- Read the implementation and every test that calls it before writing.
- Document each @throws by naming the exact error class the code throws.
- Write one @example that imports from the package name and would compile.
- Note non-obvious behaviour explicitly: mutation of arguments, default
  values, coercion, and async ordering.

Do not modify any executable line. When you finish, run:
npx typedoc --emit none --validation.notDocumented --treatValidationWarningsAsErrors src/index.ts
and fix every warning it reports for these 10 exports.

Exports: <paste the list from the audit>

TypeDoc 0.28 (sprawdzone 2026-09-26) ostrzega o każdym nieudokumentowanym eksporcie, gdy przekażesz --validation.notDocumented, a --treatValidationWarningsAsErrors zamienia te ostrzeżenia w niezerowy kod wyjścia. --emit none pomija generowanie strony HTML, więc polecenie działa jako bramka.

Następnie sprawdź, czy przebieg zmienił wyłącznie komentarze. Uruchom w terminalu na gałęzi agenta, po jego commicie:

git diff -U0 main...HEAD -- src | grep -E '^[+-][^+-]' | grep -vE '^[+-][[:space:]]*(\*|/\*\*|\*/|//)' || echo "comments only"

Każda wypisana linia to zmieniona linia kodu wewnątrz commitu „z dokumentacją”. Cofnij ten fragment albo przenieś go do osobnej, przejrzanej zmiany. To szybki filtr, nie dowód: pomija zmienione linie zaczynające się od + lub - (np. ++i;), więc i tak przejrzyj diff.

Zamień przechodzące testy w przewodnik „pierwsze kroki”

Twój zestaw testów zawiera już działające wywołania z realistycznymi danymi. To lepsze źródło przykładów do tutorialu niż wyobraźnia agenta.

Prompt do skopiowania: przewodnik „pierwsze kroki” z testów

Write docs/getting-started.md for a developer who knows TypeScript but has
never used this package. Build it only from code that runs today:

1. Installation with npm, pnpm, and yarn.
2. A first example: find the simplest passing test in tests/ that exercises
   the main entry point, and turn it into a runnable script with imports.
3. The five most common usage patterns across tests/, one section each.
4. Configuration: every option with its default, read from the source,
   not from the existing README.
5. Error handling: each error class the public API throws, and how to catch it.

Put every code sample in a Markdown code fence tagged ts. Under each sample,
add an HTML comment naming the test file it came from, for example
<!-- source: tests/parse.test.ts -->. Keep the guide under 1,200 words.

Komentarz ze źródłem pozwala recenzentowi sprawdzić przykład bez czytania go: otwiera wskazany test i potwierdza, że wywołanie się zgadza. Reguła o bloku kodu oznaczonym ts wyznacza to, co wyciąga sprawdzenie przykładów w CI opisane w następnej sekcji.

Wygeneruj przegląd architektury, który cytuje dowody

Dokumenty architektury starzeją się szybciej niż jakiekolwiek inne, bo żadna pojedyncza zmiana w kodzie nie wygląda na taką, która ich dotyczy. Generuj przegląd tak, żeby dało się go tanio wygenerować ponownie, i trzymaj go na tyle krótkim, żeby ludzie go czytali.

Prompt do skopiowania: przegląd architektury z Mermaid

Write docs/architecture.md, at most 900 words, for an engineer joining the team.

1. A Mermaid flowchart of the top-level modules in src/ and their import
   relationships. Show at most 12 nodes; group the rest into subgraphs.
2. A Mermaid sequence diagram of one typical request, from the public entry
   point to the returned value.
3. The five most important types or interfaces, one paragraph each.
4. Extension points: every place a user can plug in behaviour.
5. Design decisions: for each, cite the files that show the pattern. Where
   the reason is not visible in code, write TODO(docs-why) instead of a
   plausible explanation.

After each factual sentence, cite the file path in parentheses.

Wyrenderuj diagramy przed commitem. Mermaid CLI traktuje plik Markdown jako zbiór diagramów i renderuje każdy blok mermaid (@mermaid-js/mermaid-cli 12.0.0, sprawdzone 2026-09-26). Korzysta z bezgłowego Chrome’a przez Puppeteer, więc uruchamiaj je na maszynie albo obrazie CI, który go ma:

npx -p @mermaid-js/mermaid-cli mmdc -i docs/architecture.md -o /tmp/architecture-rendered.md

Diagram, który nie renderuje się tutaj, jest zepsuty dla większości czytelników — a dowiesz się o tym przed nimi. Głębszą pracę nad architekturą, w tym rekordy decyzji, opisuje strona o planowaniu architektury z Cursorem.

Zbuduj przewodnik migracji z diffu wydania

Uruchom to w agencie, nie w Plan Mode, bo prompt zapisuje plik docs/migration-v2.md. Zastąp oba tagi tagami swoich wydań.

Prompt do skopiowania: przewodnik migracji z v1 do v2

Write docs/migration-v2.md.

1. Run: git diff v1.9.0..HEAD --stat -- src
   then read the full diff for every file that changes an exported symbol.
2. List every breaking change: renamed or removed exports, changed parameter
   order or types, new required parameters, changed return types, changed
   defaults.
3. For each, show a v1 snippet, the v2 equivalent, and one line on what the
   user must do. Order by how many call sites in tests/ the change affects.
4. Add a "Search and replace" table for purely mechanical renames.
5. Add a "Behaviour changes" section listing any exported function whose
   body changed but whose signature did not. For each, write
   TODO(docs-why) and name the commit that changed it.

Do not describe a change you did not see in the diff.

To punkt 5 ratuje sytuację. Diff niezawodnie pokazuje zmiany sygnatur; funkcja, która zachowuje sygnaturę, a zwraca coś innego, to dokładnie to, co wygenerowany przewodnik przeoczy — dlatego prompt każe agentowi wypisać kandydatów, a Ty ich oceniasz. Duże aktualizacje własnych zależności, a nie zależności Twoich użytkowników, opisuje strona o migracjach frameworków i bibliotek z Cursorem.

Jak zweryfikować wygenerowaną dokumentację bez czytania każdej linii?

Przeglądaj wygenerowany tekst tam, gdzie potrzebny jest osąd, a całą resztę zostaw maszynom. Umieść te bramki w CI, żeby działały przy każdym pull requeście, a nie tylko w dniu generowania.

1. Pokrycie. Walidacja TypeDoc wywraca build, gdy nowy eksport trafia do kodu bez dokumentacji.
2. Przykłady się kompilują. Mały skrypt wyciąga każdy blok kodu oznaczony ts z docs/ i README.md i sprawdza jego typy względem źródeł pakietu (nazwa pakietu wskazuje na src/index.ts).
3. Linki działają. markdown-link-check nie przechodzi przy martwym linku, także takim, który wskazuje plik lub kotwicę, których nazwę zmieniłeś.
4. Diagramy się renderują. mmdc renderuje każdy blok Mermaid (zobacz sekcję o przeglądzie architektury).
5. Akceptacja człowieka. Właściciel modułu przegląda tylko luki TODO(docs-why), sekcję „Behaviour changes” i listę symboli, które według audytu już nie istnieją. To krótki, zawężony przegląd, a nie lektura każdej wygenerowanej strony.

Skrypt wyciągający przykłady zleć agentowi, bo to zwykły kod z jasnym kontraktem:

Prompt do skopiowania: sprawdzenia dokumentacji w CI

Create scripts/check-doc-examples.ts, runnable with `npx tsx`:

- Find every Markdown code fence tagged ts in README.md and docs/**/*.md.
- Write each one to its own file in a temporary directory, keeping the
  source file and line number in the file name.
- Type-check all of them with the TypeScript compiler API against this
  package's tsconfig, resolving the package name to src/index.ts.
- Print each failure as <markdown file>:<line>: <compiler message>,
  and exit with code 1 if there is any failure.

Then run it and fix the documentation (not the code) until it passes.
Add a test for the extractor in tests/scripts/ with one valid and one
invalid fence.

Następnie podepnij bramki pod workflow. To zadanie tylko czyta repozytorium, nie ma żadnych sekretów i nie uruchamia agenta:

.github/workflows/docs-check.yml

name: docs-check
on: pull_request
permissions:
  contents: read
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npm ci
      - run: npx typedoc --emit none --validation.notDocumented --treatValidationWarningsAsErrors src/index.ts
      - run: npx tsx scripts/check-doc-examples.ts
      - run: npx markdown-link-check -q -c .markdown-link-check.json README.md
      - run: find docs -name "*.md" -print0 | xargs -0 -n1 npx markdown-link-check -q -c .markdown-link-check.json

markdown-link-check (3.15.0) domyślnie odpytuje też zewnętrzne adresy URL, przez co bramka w pull requeście bywa niestabilna. Daj mu plik .markdown-link-check.json z wpisem ignorePatterns dla ^https?://, żeby ta bramka sprawdzała tylko lokalne pliki i kotwice, a linki zewnętrzne sprawdzaj w osobnym, nieblokującym zadaniu uruchamianym według harmonogramu.

Powyższe zadanie pomija bramkę Mermaid; dodaj polecenie mmdc z sekcji o przeglądzie architektury jako osobny krok, gdy Chrome instalowany przez Puppeteera zacznie działać na Twoim runnerze. Do przeglądu samego pull requesta Bugbot sprawdza diff jak każdą inną zmianę; nie zastępuje bramek opisanych wyżej.

Czego bramki nie wyłapią

Komentarz TSDoc, który istnieje, kompiluje się i opisuje stare zachowanie, przejdzie przez wszystkie powyższe sprawdzenia. Jedyną obroną jest powiązanie przykładów z testami: gdy zmiana zachowania psuje test, wygeneruj ponownie TSDoc i te sekcje przewodnika, które cytują ten test.

Kiedy dokumentacja pisana przez agenta się psuje

Agent opisuje zachowanie, którego kod nie ma. Wywnioskował znaczenie parametru z jego nazwy albo opisał ponawianie, którego nie ma. Naprawa: wymagaj ścieżki pliku przy każdym twierdzeniu, tak jak robią to powyższe prompty, i sprawdzaj wyrywkowo trzy cytowania na dokument. Jeśli jedno jest błędne, odrzuć sekcję i wygeneruj ją ponownie, podając w prompcie wprost plik z implementacją.

Przykłady wyglądają dobrze, ale się nie kompilują. Brakujące importy, ścieżki względne albo krok przygotowania, który test miał w beforeEach. Naprawa: skrypt sprawdzający przykłady podaje plik i linię; wklej jego wynik z powrotem agentowi z poleceniem „fix the documentation, not the code”.

Commit z dokumentacją zmienił kod. Agent „naprawił” błąd, który zauważył podczas czytania. Naprawa: opisane wyżej sprawdzenie „tylko komentarze” wypisze winne linie. Cofnij je, a podejrzewany błąd przenieś do docs/doc-questions.md jako osobną, przetestowaną zmianę.

Diagram architektury to nieczytelny kłębek. Pełny graf importów dużej bazy kodu ma setki krawędzi. Naprawa: ogranicz liczbę węzłów w prompcie, jak wyżej, i rysuj jeden diagram na podsystem zamiast jednego na wszystko.

Przewodnik migracji pomija zmianę zachowania. Sygnatura została ta sama, więc diff wyglądał niewinnie. Naprawa: uruchom zestaw testów z v1 na buildzie v2; każda porażka, która nie jest udokumentowanym złamaniem kompatybilności, należy do sekcji „Behaviour changes”.

Wygenerowana dokumentacja jest długa i nikt jej nie czyta. Agenci zapełniają miejsce, dopóki ich nie powstrzymasz. Naprawa: ustaw limit słów w każdym prompcie i przed scaleniem wytnij każdą sekcję, którą czytelnik by pominął.

Po trzech miesiącach dokumentacja znów się rozjeżdża. Naprawa: zostaw bramki CI włączone i generuj ponownie według harmonogramu. Automatyzacja w Cursorze (Automations) z wyzwalaczem Scheduled może co tydzień uruchamiać prompt audytowy; na tym, co wskaże, uruchom prompt TSDoc, a wynik przepuść przez te same bramki co zwykły pull request.

Co dalej z dokumentacją w Cursorze

Jeśli Twój przewodnik opisuje integracje z zewnętrznymi bibliotekami, serwer MCP z dokumentacją dostarczy agentowi ich aktualną dokumentację zamiast tego, co pamięta model.

Dokumentacja jako kontekst dla agenta Pisz dokumentację, która poprawia też pracę agenta w Twojej bazie kodu, a nie tylko służy czytelnikom.

Reguły projektu w Cursorze Zapisz standard dokumentacji tam, gdzie stosuje go każda rozmowa z agentem.

CI/CD z Cursorem Rozbuduj zadanie docs-check o resztę swojego pipeline'u.

Skille do dokumentacji i pisania Agent Skills, które dodają workflowy dokumentacji do Cursora, Claude Code i Codeksa.

Serwery MCP z dokumentacją Daj agentowi aktualną dokumentację zewnętrznych bibliotek, gdy Twój przewodnik opisuje integracje.

Dokumentacja z Claude Code To samo zadanie z terminala, z hookami i uruchomieniami headless.

Dokumentacja z Codeksem To samo zadanie z Codeksem i AGENTS.md.