Dokumentacja automatyczna
Na tej stronie
Dokumentuj bez przerywania pracy
Wszyscy zgadzają się, że dokumentacja jest konieczna, a jednak prawie nikt jej nie pisze. Dlaczego? Ponieważ pisanie odbywa się w najgorszym możliwym momencie: funkcjonalność jest gotowa, a uwaga już przeniosła się gdzie indziej. Codex przenosi ten koszt. Analizuje kod taki, jaki jest, i tworzy kompletną, aktualną dokumentację zgodną z rzeczywistą implementacją. Ta wierność stanowi czynnik rozstrzygający: zmyślona dokumentacja szkodzi bardziej niż pusta strona, ponieważ buduje fałszywe poczucie bezpieczeństwa.
Dokumentacja wbudowana: JSDoc i komentarze
Najczęściej czytana dokumentacja pojawia się bezpośrednio w dymku edytora, dokładnie tam, gdzie rodzi się pytanie.
"Add JSDoc documentation to all exported functions
and types in src/lib/. Include a description,
parameters, return type, and a usage example
for each function."
Oto co Codex generuje dla funkcji obliczającej cenę:
/**
* Calculates the total price after applying the discount.
*
* @param basePrice - Unit price in cents
* @param quantity - Number of units (minimum 1)
* @param discountPercent - Discount percentage (0-100)
* @returns The total price in cents, rounded to an integer
*
* @example
* calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
*
* @throws {ValidationError} If price or quantity is negative
*/
export function calculateTotal(
basePrice: number,
quantity: number,
discountPercent: number = 0
): number {
// ...
}
Dwie informacje zawarte tutaj są warte więcej niż wszystko inne: jednostka – centy, a nie euro – oraz wyjątek wyrzucany dla wartości ujemnych. To właśnie te dwie rzeczy programista odkrywa zazwyczaj na produkcji, po obciążeniu klientów kwotami dziesięciokrotnie niższymi niż zamierzono. Codex wydobył je z implementacji, a nie z ogólnego szablonu komentarzy.
Generowanie pliku README
W przypadku nowego projektu lub pliku README, który przez dryf stał się fikcją, określ, co czytelnik musi być w stanie zrobić po jego przeczytaniu.
"Generate a comprehensive README.md for this project. Include:
- Project description and purpose
- Prerequisites (Node.js, PostgreSQL, etc.)
- Step-by-step installation instructions
- Required environment variables (without values)
- Available commands (dev, test, build, lint)
- Project structure
- How to contribute"
Codex opiera się na pliku package.json, plikach konfiguracyjnych i rzeczywistej strukturze katalogów, aby wygenerować dokument odzwierciedlający aktualny stan projektu. Instrukcja „without values“ (bez wartości) nie jest kaprysem: bez niej agent, który właśnie przeczytał dobrze wypełniony .env.example, mógłby bez wahania skopiować wartości, których nie chcesz widzieć w pliku wersjonowanym.
Dokumentacja API
W przypadku interfejsu REST API najbardziej opłacalną dokumentacją jest ta, z której inne narzędzia mogą korzystać bez ludzkiej ingerencji.
"Analyze all routes in src/api/routes/ and generate
an openapi.yaml file. Include request and response
schemas based on existing TypeScript types and
Zod validations."
Wszystko jest ekstrahowane z kodu: ścieżki tras, metody HTTP, schematy walidacji i typy odpowiedzi. Powstała specyfikacja jest zatem wierna implementacji, pozwalając odbiorcom na wygenerowanie typowanego klienta lub kolekcji testów bez zadawania Ci ani jednego pytania.
Dokumentacja architektury
Decyzje architektoniczne rzadko są zapisywane. Gdy już się to dzieje, opisują one pierwotny zamiar, a nie rzeczywistość trzy lata później. Poproś Codex o sformalizowanie tego, co faktycznie istnieje w kodzie.
"Analyze the project architecture and create a
docs/architecture.md file documenting:
- Layers (API, services, repositories, models)
- Data flow for a typical request
- Patterns used (repository pattern, dependency injection)
- Dependencies between modules"
Dokument ten ma nieoczekiwany dodatkowy benefit: opisując zależności między modułami takimi, jakimi naprawdę są, ujawnia powiązania, których nikt wcześniej nie承认ł – na przykład fakt, że usługa rozliczeniowa importuje narzędzie z modułu uwierzytelniania.
Aktualizacja istniejącej dokumentacji
Przestarzała dokumentacja jest gorsza niż brak dokumentacji, ponieważ marnuje czas, powołując się na autorytet.
"Compare README.md with the current state of the project.
Identify outdated sections (commands that no longer exist,
removed dependencies, incorrect instructions).
Update the README accordingly."
Codex konfrontuje każde twierdzenie zawarte w pliku README z rzeczywistym kodem i koryguje niespójności. Zaplanuj to zadanie okresowo, na przykład przed każdym wydaniem, zamiast odkrywać jego konieczność w dniu, w którym nowy pracownik stwierdza, że żadna z komend instalacyjnych nie działa.
Automatyzacja poprzez AGENTS.md
Aby przestać traktować dokumentację jako osobne, uciążliwe zadanie, uczyń ją stałym ograniczeniem projektu.
## Documentation
- Every new exported function MUST have complete JSDoc
- API changes MUST update openapi.yaml
- Comment format: French for business logic, English for technical details
Dzięki tym trzem zasadom każde zadanie programistyczne niesie ze sobą własną aktualizację dokumentacji. Luka między kodem a opisem przestaje się cicho powiększać, co jest jedynym zrównoważonym sposobem na wygranie tej bitwy.
Kluczowe wnioski
- Codex generuje dokumentację wierną rzeczywistemu kodowi, a nie zmyśloną
- Dokumentacja wbudowana (JSDoc) jest najbardziej przydatna w codziennej pracy
- Codex potrafi tworzyć pliki README, specyfikacje OpenAPI oraz dokumentację architektury
- Używaj Codexa do wykrywania i korygowania przestarzałej dokumentacji
- Dodaj zasady dotyczące dokumentacji do pliku AGENTS.md, aby zautomatyzować ten proces