Generowanie i utrzymanie dokumentacji z Codex

Codex generuje referencję API, dokumenty architektury, komentarze TSDoc i szkice changelogów z kodu źródłowego i historii gita w izolowanym worktree Gita, więc nic nie trafia do głównego katalogu roboczego bez przeglądu. Generowanie to łatwiejsza połowa. Dokumentacja pozostaje prawdziwa dzięki deterministycznym bramkom i cyklicznemu raportowi rozjazdów z codex exec, który zwraca JSON zgodny ze schematem, na którym CI może przerwać build.

Ta strona jest dla programistów odpowiedzialnych za dokumentację serwisu i dla tech leadów, którzy chcą, żeby dokumentacja przestała obciążać code review. Znasz ten obrazek: docs/API.md wciąż wymienia endpoint usunięty dwa sprinty temu, polecenie instalacji z README pada na czystej maszynie, a każda nowa osoba zadaje te same pytania, bo ARCHITECTURE.md opisuje system sprzed ostatniej refaktoryzacji. Nikt nie aktualizuje dokumentacji ręcznie, więc rozwiązaniem jest workflow, który ją regeneruje, i bramka, która pada, gdy dokumentacja się rozjedzie.

Co zyskasz, prowadząc dokumentację w Codex

• Tabelę decyzyjną: które dokumenty Codex ma generować, które tylko szkicować i jaka kontrola dowodzi poprawności każdego z nich.
• Sekcję AGENTS.md i skill repozytorium, dzięki którym każda sesja Codex pisze dokumentację tak samo.
• Prompty do skopiowania: referencja API z testem kontraktowym, ARCHITECTURE.md z cytowaniami i szkic changelogu.
• Raport rozjazdów z codex exec --output-schema w trybie tylko do odczytu, który zamienia „dokumentacja chyba jest OK” w kod wyjścia.
• Listę typowych awarii wraz ze sposobem naprawy każdej.

Zanim zaczniesz, zainstaluj Codex i dodaj AGENTS.md w katalogu głównym repozytorium; podstawy opisuje konfiguracja AGENTS.md dla Codex. Polecenia na tej stronie sprawdzono na Codex CLI 0.157.1.

Którą dokumentację powinien pisać Codex?

Codex jest wiarygodny tam, gdzie odpowiedź jest w kodzie, i zawodny tam, gdzie odpowiedź jest w czyjejś głowie. Zdecyduj osobno dla każdego typu dokumentu, zanim napiszesz prompt:

Dokument	Źródło prawdy	Rola Codex	Co dowodzi poprawności
TSDoc / JSDoc eksportowanych symboli	Sygnatury, typy, rzucane błędy	Generuje	Walidacja TypeDoc pada przy każdym nieudokumentowanym eksporcie
Referencja API (openapi.yaml lub API.md)	Handlery tras, schematy walidacji, middleware	Generuje	Lint Redocly i test kontraktowy porównujący opisane trasy z zarejestrowanymi
ARCHITECTURE.md	Układ katalogów, punkty wejścia, przepływ danych	Generuje z cytowaniami	Skrypt sprawdza, czy każda cytowana ścieżka istnieje
Sekcja instalacji w README	Skrypty, które naprawdę działają	Generuje, potem uruchamia	CI wykonuje polecenia instalacji na czystym checkoucie
Changelog	git log między tagami	Szkicuje	Właściciel wydania poprawia treść i ją zatwierdza
Zapisy decyzji („dlaczego wybraliśmy X”)	Rozumowanie ludzi	Tylko wywiad i szkic	Właściciel decyzji pisze lub zatwierdza każde uzasadnienie

Ostatni wiersz jest najważniejszy. Zapytany, dlaczego moduł korzysta z kolejki, Codex napisze wiarygodnie brzmiący powód niezależnie od tego, czy taki istnieje. Uzasadnienia zostaw ludziom i korzystaj z wywiadu opisanego w decyzjach architektonicznych, za którymi agent potrafi pójść.

Najpierw dodaj bramki do repozytorium

Dodaj kontrole przed pierwszym wygenerowanym dokumentem, żeby już pierwszy diff był zweryfikowany. W serwisie TypeScript zainstaluj TypeDoc i Redocly CLI (0.28.20 i 2.54.3 w npm na 2026-09-26):

npm install -D typedoc @redocly/cli

Następnie dodaj do package.json jeden skrypt docs:check. --emit none waliduje bez generowania HTML, a --treatValidationWarningsAsErrors sprawia, że TypeDoc kończy się błędem, gdy którykolwiek eksportowany symbol w src/ nie ma dokumentacji:

{
  "scripts": {
    "docs:check": "typedoc --emit none --entryPointStrategy expand --entryPoints src --validation.notDocumented --treatValidationWarningsAsErrors && redocly lint docs/openapi.yaml && bash scripts/check-doc-citations.sh"
  }
}

Kontrola cytowań łapie najczęstszą postać zmyślonej prozy: twierdzenie powołujące się na plik, który nie istnieje. Zapisz ją jako scripts/check-doc-citations.sh:

#!/usr/bin/env bash
# Fail when a doc cites a repository path that does not exist.
# A line suffix such as `src/routes/billing.ts:42` is checked as the bare path.
set -uo pipefail
missing=0
for doc in docs/ARCHITECTURE.md docs/API.md README.md; do
  [ -f "$doc" ] || continue
  for path in $(grep -oE '`(src|scripts|tests|docs|config)/[A-Za-z0-9_./-]+(:[0-9]+)?`' "$doc" \
      | tr -d '`' | sed -E 's/:[0-9]+$//' | sort -u); do
    if [ ! -e "$path" ]; then
      echo "$doc cites a missing path: $path"
      missing=1
    fi
  done
done
exit "$missing"

Trzy bramki są połączone przez &&, więc npm run docs:check zatrzymuje się na pierwszej, która padnie, a redocly lint i tak pada, dopóki nie istnieje docs/openapi.yaml. Żeby zbudować backlog, uruchom je raz osobno i zachowaj wszystkie błędy:

npx typedoc --emit none --entryPointStrategy expand --entryPoints src --validation.notDocumented --treatValidationWarningsAsErrors; \
  npx redocly lint docs/openapi.yaml; \
  bash scripts/check-doc-citations.sh

Ta lista to backlog, który przekazujesz Codex, jeden katalog na zadanie. Bramki TypeDoc i wykonywania README nie zależą od narzędzia; przewodnik po dokumentacji w Claude Code pokazuje krok CI, który uruchamia blok szybkiego startu z README w czystym kontenerze.

Naucz Codex zasad dokumentacji raz

Codex czyta AGENTS.md, zanim zacznie jakąkolwiek pracę, więc zapisane tam konwencje obowiązują w każdej sesji, także w wątkach w worktree i w zaplanowanych uruchomieniach. Dodaj krótką sekcję do głównego AGENTS.md:

## Documentation
- API reference: docs/openapi.yaml. Architecture: docs/ARCHITECTURE.md. Changelog: CHANGELOG.md.
- Cite every claim about the code as a repo-relative path in backticks, for example `src/routes/billing.ts`.
- Never write rationale ("we chose X because") that is not in a code comment, docs/adr/ or the prompt.
  Write "(rationale: ask the owner)" instead.
- In hand-written docs, edit only between <!-- generated:start --> and <!-- generated:end -->.
- Before finishing any change to docs/ or to an exported API, run `npm run docs:check` and fix failures.

Wpisuj tam tylko zasady, które dotyczą każdego zadania. Wieloetapowa procedura pełnego przeglądu dokumentacji należy do skilla, który Codex wczytuje dopiero wtedy, gdy zadanie go potrzebuje. Zapisz go jako .agents/skills/docs-sync/SKILL.md:

---
name: docs-sync
description: Bring docs/ back in line with the code after a change. Use when a task changes routes, exported APIs, scripts or directory layout.
---

1. Run `git diff --name-only origin/main...HEAD` and list the changed routes, exports and scripts.
2. For each change, find every place in docs/, README.md and docs/openapi.yaml that describes it.
3. Update only those passages. Cite the file each claim comes from.
4. Run `npm run docs:check`. Fix documentation, never code, until it passes.
5. Report: each doc changed, the code change that caused it, and the final docs:check output.

Wywołaj go przez $docs-sync w prompcie albo przejrzyj zainstalowane skille poleceniem /skills. Jeśli skill się nie pojawia, optymalizacja AGENTS.md i skilli w Codex pokazuje, jak sprawdzić, co dokładnie Codex wczytał.

Generuj dokumentację referencyjną w zadaniu w worktree

Worktree trzyma wygenerowane pliki z dala od twojego katalogu roboczego, dopóki ich nie sprawdzisz, i pozwala zadaniu dokumentacyjnemu działać równolegle z pracą nad funkcją.

1. Uruchom zadanie we własnym worktree. Najpierw zrób commit albo stash: worktree startuje ze stanu zatwierdzonego, więc niezacommitowanych zmian w nim nie ma.

   Codex CLI

   codex --worktree

   --worktree uruchamia sesję w nowym, zarządzanym worktree Gita (obsługa worktree jest domyślnie włączona od Codex CLI 0.156.0).

   Aplikacja desktopowa Codex

   Rozpocznij nowy wątek w projekcie i jako miejsce działania wybierz Worktree. Aplikacja działa na macOS i Windows; codex app otwiera ją z terminala.

2. Zainstaluj zależności w worktree (npm ci), bo inaczej bramki padną z powodu, który nie ma nic wspólnego z dokumentacją.

3. Wklej jeden z poniższych promptów, jeden dokument albo jeden katalog na zadanie. Małe zadania dają diffy, które sprawdzisz wyrywkowo w minutę.

4. Niech zdecydują bramki. Prompt kończy się uruchomieniem npm run docs:check. Zielony wynik oznacza, że każdy eksport ma dokumentację, specyfikacja się parsuje, a każde cytowanie prowadzi do istniejącego pliku. Nie oznacza, że proza jest prawdziwa, i dlatego istnieje test kontraktowy.

5. Przepuść diff przez review. Wpisz /review w sesji albo uruchom codex exec review --uncommitted, żeby dostać wbudowane review. Żeby zastosować instrukcje review dokumentacji podane niżej, uruchom je jako codex exec w trybie tylko do odczytu (zobacz sekcję o review).

6. Wróć z pracą przez Gita. Zrób commit w worktree i otwórz pull request. Izolowane zadania Codex w worktree Gita opisują scalanie i sprzątanie.

Prompt do skopiowania: referencja OpenAPI z testem kontraktowym

Generate docs/openapi.yaml (OpenAPI 3.1) from the route handlers in src/routes/.
Derive request and response schemas from the Zod schemas each handler uses; do not
guess types. Before writing, read the middleware in src/middleware/ and record which
routes require auth (401/403), which add rate-limit headers, and the error shape
src/middleware/error-handler.ts returns. Document all of it.
Then write tests/contract/openapi-routes.test.ts: load the spec, list every route
registered on the router, and fail if a route is missing from the spec or the spec
lists a path the router does not serve.
Run `npx redocly lint docs/openapi.yaml`, the new test, and `npm run docs:check`.
Report all three results and list any route whose behaviour you could not determine.

Od tej chwili wyrocznią jest test kontraktowy: trasa dodana bez wpisu w specyfikacji zmienia CI na czerwone, niezależnie od tego, kto ją dodał. Resztę workflow „najpierw kontrakt” opisuje budowanie API z Codex.

Prompt do skopiowania: ARCHITECTURE.md z cytowaniami

Write docs/ARCHITECTURE.md, under 200 lines, for a developer on their first week:
system overview (one paragraph), tech stack with versions read from the lockfile,
directory map, the lifecycle of one HTTP request, background jobs, external services,
and how authentication works end to end.
Cite a file for every claim as a repo-relative path in backticks.
Mark anything you inferred rather than read as (inferred).
Use one Mermaid diagram for the request lifecycle and no other diagrams.
Where the code and existing docs disagree, trust the code and list each disagreement
at the end under "Drift found". Run `npm run docs:check` before you finish.

Lista „Drift found” bywa cenniejsza niż sam dokument: to audyt dokumentacji, którą już masz. Sprawdź każdy znacznik (inferred); każdy z nich to twierdzenie, którego nie potwierdza żaden plik.

Przy TSDoc wskaż Codex ostrzeżenia TypeDoc dla jednego katalogu i dodaj dwa ograniczenia: „follow the style already used in src/lib/database.ts” oraz „keep each comment shorter than the function body it documents”. Drugie ogranicza najczęstszą wadę generowanych komentarzy, czyli powtarzanie kodu słowami.

Przygotuj szkic changelogu z historii gita

Changelog to komunikat dla użytkowników, więc Codex go szkicuje, a treść należy do człowieka. Uruchom to w zwykłym lokalnym wątku; zadanie tylko czyta historię i zapisuje jeden plik.

Prompt do skopiowania: szkic changelogu od ostatniego tagu

Draft the next release section of CHANGELOG.md in Keep a Changelog format.
Read the commits with `git log $(git describe --tags --abbrev=0)..HEAD --no-merges`
and open the diff of any commit whose message is unclear.
Group entries under Added, Changed, Deprecated, Removed, Fixed and Security.
Write each entry for a user of the API, not as the commit message, and add the
PR number when the commit message contains one.
List every breaking change first, with a one-line migration step.
Put commits that change nothing a user can see (CI, refactors, dependency bumps
without behaviour change) in a separate "Not user-facing" list at the end so I can
confirm and delete it. Do not bump the version number.

Lista „Not user-facing” sprawia, że klasyfikację agenta da się sprawdzić. Właściciel wydania czyta tę listę i zmiany łamiące zgodność, a nie każdy wpis.

Wykrywaj rozjazdy dokumentacji za pomocą codex exec

Wygenerowana dokumentacja jest prawdziwa w dniu wygenerowania. Prawdziwą utrzymuje ją raport rozjazdów: uruchomienie codex exec tylko do odczytu, które porównuje dokumentację z kodem i zwraca JSON o stałym kształcie.

Zapisz schemat jako scripts/docs-drift/schema.json. --output-schema działa w trybie strict, więc każdy obiekt wymienia wszystkie swoje właściwości w required i ustawia additionalProperties na false:

{
  "type": "object",
  "properties": {
    "verdict": { "type": "string", "enum": ["current", "drift"] },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "doc": { "type": "string" },
          "claim": { "type": "string" },
          "code_evidence": { "type": "string" },
          "kind": { "type": "string", "enum": ["missing", "stale", "wrong", "dead-reference"] }
        },
        "required": ["doc", "claim", "code_evidence", "kind"],
        "additionalProperties": false
      }
    }
  },
  "required": ["verdict", "findings"],
  "additionalProperties": false
}

Prompt zapisz jako scripts/docs-drift/prompt.md:

Prompt do skopiowania: raport rozjazdów dokumentacji (scripts/docs-drift/prompt.md)

Compare the documentation with the code. Do not edit any file.
1. docs/openapi.yaml: every route registered in src/routes/ must be documented, and
   every documented path must exist. Compare request and response fields with the Zod schemas.
2. docs/ARCHITECTURE.md: every module in the directory map must exist; every top-level
   directory under src/ must appear in the map.
3. README.md: every npm script it mentions must exist in package.json; every
   environment variable it lists must be read somewhere in src/.
For each problem, give the doc, the exact claim, and the file and line in the code
that contradicts it (code_evidence). Report only problems you can point to in code.
Set kind: missing = the code has it, the doc does not; stale = the doc describes old
behaviour; wrong = the doc never matched the code; dead-reference = the doc cites a
file or symbol that does not exist.
Set verdict to "drift" if there is at least one finding, otherwise "current".

Uruchom go z katalogu głównego repozytorium i pozwól, żeby jq -e zamienił odpowiedź w kod wyjścia:

codex exec -c default_permissions=":read-only" \
  --output-schema scripts/docs-drift/schema.json -o drift.json \
  "$(cat scripts/docs-drift/prompt.md)"
jq -e '.verdict == "current"' drift.json > /dev/null || {
  jq -r '.findings[] | "\(.doc): \(.claim) <- \(.code_evidence)"' drift.json
  exit 1
}

:read-only to wbudowany profil uprawnień (beta od Codex CLI 0.138.0); jego starszy odpowiednik to --sandbox read-only. Użyj jednego albo drugiego, nie obu naraz, bo według OpenAI te dwa systemy się nie łączą. Schemat gwarantuje kształt odpowiedzi, nie jej prawdziwość: pole code_evidence istnieje po to, żeby sprawdzić znalezisko, otwierając jeden plik, a nie czytając dokumentację od nowa.

Gdzie uruchamiać kontrolę rozjazdów?

Automatyzacja w aplikacji

Utwórz automatyzację w aplikacji desktopowej Codex z powyższym promptem, wybierz projekt i ustaw harmonogram tygodniowy. Działa tylko wtedy, gdy komputer nie śpi, a wyniki trafiają do skrzynki w aplikacji. Zanim ustawisz harmonogram, przetestuj prompt ręcznie dwa razy; procedurę i wybór sandboxa opisuje przewodnik po zaplanowanych automatyzacjach Codex.

Harmonogram w CI

Uruchamiaj to samo polecenie codex exec w zaplanowanym jobie GitHub Actions na gałęzi domyślnej, nigdy na gałęzi kontrybutora, gdy klucz API jest w środowisku. Utwardzoną konfigurację z openai/codex-action@v1, minimalnymi uprawnieniami i kluczem trzymanym poza powłoką agenta opisuje CI/CD z GitHub Action dla Codex. Opublikuj drift.json jako podsumowanie joba albo utwórz na jego podstawie issue.

Gdy raport pokaże rozjazd, uruchom zadanie w worktree z $docs-sync i wklej znaleziska do promptu. Poprawka przechodzi wtedy przez te same bramki co każda inna zmiana w dokumentacji.

Przeglądaj diff dokumentacji bez czytania każdej linii

Diffy dokumentacji są długie i brzmią wiarygodnie, więc czytanie ich linia po linii to najgorszy możliwy sposób przeglądu. Czytanie zostaw bramkom i ukierunkowanemu review, a uwagę człowieka zachowaj dla twierdzeń, których żadna bramka nie sprawdzi.

Prompt do skopiowania: instrukcje review dla zmiany w dokumentacji

Review the changes in `git diff origin/main...HEAD` as a documentation reviewer.
For every changed sentence that describes code behaviour,
open the cited file and confirm the claim. Flag: claims
with no citation, citations to files that do not support the claim, rationale that
does not appear in code comments or docs/adr/, commands that do not exist in
package.json, and any edit outside generated markers in hand-written docs.
Do not comment on wording or style.

Zapisz go jako scripts/docs-drift/review.md i uruchom jako codex exec w trybie tylko do odczytu; prompt sam wskazuje diff do przejrzenia:

codex exec -c default_permissions=":read-only" "$(cat scripts/docs-drift/review.md)"

Wbudowane review bez własnych instrukcji uruchomisz poleceniem codex exec review --base main. W Codex CLI 0.157.1 flag --base, --uncommitted i --commit nie można łączyć z własnymi instrukcjami; CLI kończy się błędem „cannot be used with ‘[PROMPT]’”.

Odpowiedzialność za zatwierdzenie jest jasno przypisana:

Zmiana	Sprawdza	Zatwierdza
TSDoc, OpenAPI, cytowania	npm run docs:check, test kontraktowy	Właściciel kodu zmienionych ścieżek, na podstawie wyników bramek
ARCHITECTURE.md	Kontrola cytowań, znaczniki (inferred), review	Tech lead czyta listę „Drift found” i każdą linię (inferred)
Changelog	Człowiek	Właściciel wydania
Uzasadnienia i zapisy decyzji	Człowiek	Właściciel decyzji

Dowody, które pull request powinien zawierać, żeby recenzent mógł go zatwierdzić na ich podstawie, opisuje pakiet dowodów.

Co psuje się w dokumentacji generowanej przez Codex?

Dokumentacja wyjaśnia „dlaczego”, a powody są zmyślone. Codex wypełnia luki wiarygodnie brzmiącym uzasadnieniem. Naprawa: reguła z AGENTS.md powyżej każe mu pisać „(rationale: ask the owner)”; przeszukaj diff pod kątem „because” i „in order to” i potwierdź źródło każdego wystąpienia.

Codex przepisuje sekcje napisane ręcznie. Regeneracja całego pliku spłaszcza akapity, które napisał człowiek. Naprawa: otocz generowane fragmenty znacznikami <!-- generated:start --> i <!-- generated:end -->, zapisz regułę w AGENTS.md i dodaj kontrolę, która pada, gdy diff dotyka linii poza znacznikami.

Bramki padają w worktree z powodów niezwiązanych z dokumentacją. Świeże worktree nie ma node_modules ani twoich lokalnych plików z .gitignore. Naprawa: najpierw uruchom npm ci albo dodaj instalację do konfiguracji worktree opisanej w przewodniku po worktree.

Codex ignoruje twoje zasady dokumentacji. Od Codex CLI 0.150.0 niezaufane projekty nie dostarczają instrukcji z projektowego AGENTS.md. Naprawa: oznacz projekt jako zaufany, gdy Codex o to zapyta, a potem potwierdź poleceniem codex debug prompt-input, że reguły zostały wczytane.

Raport rozjazdów zmienia się co tydzień bez żadnej zmiany w kodzie. Nieprecyzyjny prompt daje przy każdym uruchomieniu inną listę. Naprawa: uruchom go ręcznie dwa razy; jeśli znaleziska się różnią, zawęź zakres (jeden dokument na kontrolę) i wymagaj code_evidence dla każdego znaleziska, co schemat już wymusza.

Job rozjazdów sam „poprawia” dokumentację. Zaplanowany job, który zapisuje pliki, wprowadza zmiany, o które nikt nie prosił. Naprawa: trzymaj raport na :read-only, a poprawki rób w osobnym zadaniu w worktree, które przechodzi review.

Cytowania plików psują się po przeniesieniu. Zmiana nazwy src/services/ na src/domain/ po cichu unieważnia każde cytowanie. Naprawa: kontrola cytowań przerywa build; wskaż Codex jej wynik z poleceniem „update the citations in docs/ to the new paths, do not change code”. Kontrola cytowań nie sprawdza względnych linków Markdown, takich jak [setup](../setup.md); do nich potrzebny jest link checker w CI, na przykład markdown-link-check (3.15.0 w npm): find docs -name '*.md' -print0 | xargs -0 -n1 npx markdown-link-check, a odwołania wewnątrz specyfikacji OpenAPI obejmuje redocly lint.

Co dalej z dokumentacją w Codex

• Budowanie API z Codex: workflow „najpierw kontrakt”, który dokumentuje referencja API.
• Zaplanowane automatyzacje Codex: harmonogram dla raportu rozjazdów i innych cyklicznych kontroli.
• Codex bez interakcji z codex exec: pełny zestaw flag, zdarzenia JSONL i uwierzytelnianie w CI.
• Dokumentacja jako kontekst dla agentów AI: pisanie dokumentacji, którą czyta sam agent.
• Do dokumentacji bibliotek zewnętrznych podłącz Context7 poleceniem codex mcp add context7 -- npx -y @upstash/context7-mcp, żeby generowane przykłady korzystały z aktualnych API; zobacz konfigurację MCP w Codex.
• Pracujesz w innym narzędziu? Ten sam workflow dla Claude Code i dla Cursora.