Generowanie dokumentacji z Codex

Twoj projekt rozrosl sie z weekendowego prototypu do 12-serwisowego systemu produkcyjnego. Jedyna dokumentacja to README sprzed osmiu miesiecy, ktore odwoluje sie do endpointu API, ktory juz nie istnieje. Nowi pracownicy spedzaja pierwszy tydzien czytajac kod zrodlowy, zeby zrozumiec, co co robi. Mozesz zablokowac dwa sprinty na push dokumentacyjny. Albo mozesz zlecic Codex wygenerowanie dokladnej dokumentacji z rzeczywistej bazy kodu i skonfigurowac automatyzacje, ktore beda ja utrzymywac w aktualnosci.

Co wyniesiesz z tej lekcji

Prompty do generowania dokumentacji API, przewodnikow architektonicznych i dokumentacji onboardingowej z kodu zrodlowego
Workflow z worktree do generowania dokumentacji bez ruszania katalogu roboczego
Przepisy na automatyzacje cotygodniowych kontroli swiezosci dokumentacji
Techniki synchronizacji dokumentacji ze zmianami w kodzie z wykorzystaniem konwencji AGENTS.md

Workflow

Krok 1: Wygeneruj dokumentacje API

Dokumentacja API ma najwyzsza wartosc, poniewaz ma bezposredni, mierzalny wplyw na produktywnosc deweloperow. Uzyj CLI do szybkiego przebiegu generowania lub App do iteracyjnego dopracowywania.

Gotowy prompt do generowania dokumentacji API:

Generate comprehensive API documentation for all endpoints in src/routes/. For each endpoint include:

1. HTTP method and path
2. Description of what it does
3. Request headers (especially authentication)
4. Request body schema with types and validation rules (read the Zod schemas)
5. Response schema for success (200/201) and error cases (400, 401, 404, 500)
6. Example request and response using realistic data
7. Rate limiting details if applicable

Output as a single Markdown file (docs/API.md) organized by route group.
Read the actual route handlers and Zod schemas -- do not guess at the types.

Uruchom to w watku Worktree, aby wygenerowany plik nie trafil do twojego katalogu roboczego, dopoki go nie przejrzysz. Po przejrzeniu diffa w panelu recenzji App, zsynchronizuj lokalnie lub utworz branch i otworz PR.

Krok 2: Wygeneruj dokumentacje architektury

Dokumentacja architektury starzeje sie najszybciej, poniewaz opisuje relacje miedzy komponentami, a te relacje zmieniaja sie co sprint. Pozwol Codex generowac je z rzeczywistego kodu, nie z pamieci.

Gotowy prompt do dokumentacji architektury:

Analyze the codebase and generate docs/ARCHITECTURE.md covering:

1. System overview: what this project does, who uses it, what problems it solves
2. Component map: each service/module, its responsibility, and how it communicates with others
3. Data flow: how a request enters the system, which services it touches, and how the response is assembled
4. Database schema: tables, relationships, and key indexes (read the schema files)
5. External dependencies: third-party APIs, message queues, caches, and how we integrate with each
6. Key design decisions: patterns used (event sourcing, CQRS, etc.) and why

Use text-based diagrams (ASCII or Mermaid) for the component map and data flow.
Write for a mid-level developer joining the team. Be specific about file paths.
Keep it under 400 lines.

Krok 3: Wygeneruj dokumentacje inline w kodzie

Dla kodu, ktory jest wystarczajaco zlozony, aby wymagac wyjasnienia, wygeneruj komentarze JSDoc/TSDoc i opisy na poziomie modulow:

Add JSDoc documentation to all exported functions in src/services/ that are currently undocumented. For each function:

1. A one-line description of what it does
2. @param tags with types and descriptions
3. @returns description
4. @throws for any errors the function can throw
5. @example with a realistic usage example

Do NOT add documentation to private/internal functions or simple getters.
Follow the existing documentation style in the codebase (check if any functions already have JSDoc).

Krok 4: Aktualizuj dokumentacje za pomoca rozszerzenia IDE

Rozszerzenie IDE jest najlepsze do ukierunkowanych aktualizacji dokumentacji, gdy juz pracujesz w kodzie. Przy wlaczonym auto-kontekscie Codex widzi pliki, ktore masz otwarte i moze aktualizowac dokumentacje na podstawie tego, co wlasnie zmieniles.

Po zaimplementowaniu nowej funkcji:

I just added a new POST /api/subscriptions/upgrade endpoint. Update docs/API.md to include this endpoint. Match the format and level of detail used for existing endpoints in that file. Also verify that all links in the API doc are still valid.

Krok 5: Zautomatyzuj kontrole swiezosci dokumentacji

Prawdziwa sila tkwi w automatyzacji. Skonfiguruj cotygodniowa automatyzacje, ktora sprawdza, czy dokumentacja odpowiada bazie kodu:

Gotowy prompt automatyzacji do cotygodniowej kontroli dokumentacji:

Compare the documentation in docs/ against the actual codebase:

1. Check docs/API.md: Are all endpoints documented? Are any documented endpoints missing from the code? Do the request/response schemas match the current Zod schemas?
2. Check docs/ARCHITECTURE.md: Do the module descriptions match the current code structure? Are there new modules not mentioned? Are there mentioned modules that no longer exist?
3. Check README.md: Are the setup instructions still accurate? Do the listed scripts exist in package.json?

If any documentation is out of date, update it to match the current codebase. If everything is current, report that no updates are needed.

Ta automatyzacja dziala w dedykowanym worktree, wiec nigdy nie dotyka twojego katalogu roboczego. Wyniki pojawiaja sie w skrzynce automatyzacji. Jesli aktualizacje byly potrzebne, zobaczysz diff do przejrzenia.

Generowanie changelogow

Do dokumentacji wydaniowej Codex moze generowac changelogi z historii git. Sprawdza sie to dobrze jako zadanie w chmurze, poniewaz korzysta z odczytu pelnej historii commitow.

Generate a changelog for the upcoming release by analyzing all commits since the last git tag.

Group changes into:
- Features: new functionality
- Fixes: bug fixes
- Breaking changes: anything that changes the public API
- Internal: refactoring, dependency updates, CI changes

For each entry, write a user-facing description (not the commit message). Include the PR number if available. Highlight breaking changes with migration instructions.

Output as CHANGELOG.md in the standard Keep a Changelog format.

Gdy cos sie nie uda

Wygenerowana dokumentacja opisuje co kod robi, nie dlaczego. Codex czyta implementacje i opisuje ja dokladnie, ale nie potrafi wyjasnic kontekstu biznesowego ani historycznych decyzji. Dodaj komentarze w kodzie wyjasniajace “dlaczego” (nie “co”), a Codex je uwzgledni. Alternatywnie podaj kontekst w prompcie: “System ponownych prob webhookow zostal zaprojektowany pod katem ostatecznej spojnosci z systemami partnerow, ktore maja okna dostawy do 72 godzin.”

Dokumentacja API starzeje sie w ciagu tygodnia. Wygenerowana dokumentacja jest aktualna tylko do momentu ostatniego generowania. Przepis na automatyzacje z kroku 5 to wylapuje, ale dziala tylko jesli automatyzacja jest uruchamiana regularnie i faktycznie przegladasz wyniki. Przypnij automatyzacje w Codex App, aby nie zostala zarchiwizowana.

Linki w dokumentacji sie psuja. Jesli generujesz dokumentacje ze wzglednymi linkami do plikow zrodlowych, a potem przeniesiesz te pliki, linki sie po cichu zepsuja. Dodaj “verify that all file path references in the documentation point to files that actually exist” do promptu kontroli swiezosci.

Codex nadpisuje reczna dokumentacje. Jesli twoja dokumentacja zawiera recznie napisane wyjasnienia obok wygenerowanych sekcji, Codex moze nadpisac reczne czesci. Uzyj wyraznych znacznikow sekcji:  i powiedz Codex: “Only modify content between the generated section markers. Do not touch manually written sections.”

Co dalej

Rozwoj API z Codex Buduj API, ktore opisuje twoja dokumentacja

Automatyzacja zadan zaplanowanych Skonfiguruj wiecej automatyzacji dla powtarzalnych zadan poza dokumentacja