Generowanie dokumentacji z Codex

Twój projekt rozrósł się z weekendowego prototypu do 12-serwisowego systemu produkcyjnego. Jedyna dokumentacja to README sprzed ośmiu miesięcy, które odwołuje się do endpointu API, który już nie istnieje. Nowi pracownicy spędzają pierwszy tydzień czytając kod źródłowy, żeby zrozumieć, co co robi. Możesz zablokować dwa sprinty na push dokumentacyjny. Albo możesz zlecić Codex wygenerowanie dokładnej dokumentacji z rzeczywistej bazy kodu i skonfigurować automatyzacje, które będą ją utrzymywać w aktualności.

Co wyniesiesz z tej lekcji

Prompty do generowania dokumentacji API, przewodników architektonicznych i dokumentacji onboardingowej z kodu źródłowego
Workflow z worktree do generowania dokumentacji bez ruszania katalogu roboczego
Przepisy na automatyzacje cotygodniowych kontroli świeżości dokumentacji
Techniki synchronizacji dokumentacji ze zmianami w kodzie z wykorzystaniem konwencji AGENTS.md

Workflow

Krok 1: Wygeneruj dokumentację API

Dokumentacja API ma najwyższą wartość, ponieważ ma bezpośredni, mierzalny wpływ na produktywność deweloperów. Użyj 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 wątku Worktree, aby wygenerowany plik nie trafił do twojego katalogu roboczego, dopóki go nie przejrzysz. Po przejrzeniu diffa w panelu recenzji App, zsynchronizuj lokalnie lub utwórz branch i otwórz PR.

Krok 2: Wygeneruj dokumentację architektury

Dokumentacja architektury starzeje się najszybciej, ponieważ opisuje relacje między komponentami, a te relacje zmieniają się co sprint. Pozwól Codex generować je z rzeczywistego kodu, nie z pamięci.

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 dokumentację inline w kodzie

Dla kodu, który jest wystarczająco złożony, aby wymagać wyjaśnienia, wygeneruj komentarze JSDoc/TSDoc i opisy na poziomie modułów:

Gotowy prompt do generowania inline JSDoc:

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 dokumentację za pomocą rozszerzenia IDE

Rozszerzenie IDE jest najlepsze do ukierunkowanych aktualizacji dokumentacji, gdy już pracujesz w kodzie. Przy włączonym auto-kontekście Codex widzi pliki, które masz otwarte i może aktualizować dokumentację na podstawie tego, co właśnie zmieniłeś.

Po zaimplementowaniu nowej funkcji:

Gotowy prompt do ukierunkowanych aktualizacji dokumentacji z IDE:

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 świeżości dokumentacji

Prawdziwa siła tkwi w automatyzacji. Skonfiguruj cotygodniową automatyzację, która 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 działa w dedykowanym worktree, więc nigdy nie dotyka twojego katalogu roboczego. Wyniki pojawiają się w skrzynce automatyzacji. Jeśli aktualizacje były potrzebne, zobaczysz diff do przejrzenia.

Generowanie changelogów

Do dokumentacji wydaniowej Codex może generować changelogi z historii git. Sprawdza się to dobrze jako zadanie w chmurze, ponieważ korzysta z odczytu pełnej historii commitów.

Gotowy prompt do generowania changeloga:

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 coś się nie uda

Wygenerowana dokumentacja opisuje co kod robi, nie dlaczego. Codex czyta implementację i opisuje ją dokładnie, ale nie potrafi wyjaśnić kontekstu biznesowego ani historycznych decyzji. Dodaj komentarze w kodzie wyjaśniające “dlaczego” (nie “co”), a Codex je uwzględni. Alternatywnie podaj kontekst w prompcie: “System ponownych prób webhooków został zaprojektowany pod kątem ostatecznej spójności z systemami partnerów, które mają okna dostawy do 72 godzin.”

Dokumentacja API starzeje się w ciągu tygodnia. Wygenerowana dokumentacja jest aktualna tylko do momentu ostatniego generowania. Przepis na automatyzację z kroku 5 to wyłapuje, ale działa tylko jeśli automatyzacja jest uruchamiana regularnie i faktycznie przeglądasz wyniki. Przypnij automatyzację w Codex App, aby nie została zarchiwizowana.

Linki w dokumentacji się psują. Jeśli generujesz dokumentację ze względnymi linkami do plików źródłowych, a potem przeniesiesz te pliki, linki się po cichu zepsują. Dodaj “verify that all file path references in the documentation point to files that actually exist” do promptu kontroli świeżości.

Codex nadpisuje ręczną dokumentację. Jeśli twoja dokumentacja zawiera ręcznie napisane wyjaśnienia obok wygenerowanych sekcji, Codex może nadpisać ręczne części. Użyj wyraźnych znaczników sekcji:  i powiedz Codex: “Only modify content between the generated section markers. Do not touch manually written sections.”

Co dalej

Rozwój API z Codex Buduj API, które opisuje twoja dokumentacja

Automatyzacja zadań zaplanowanych Skonfiguruj więcej automatyzacji dla powtarzalnych zadań poza dokumentacją