Automatická dokumentácia
Na tejto strane
Dokumentácia bez prerušenia vývoja
Všetci súhlasia, že dokumentácia je nevyhnutná, no takmer nikto ju nepíše. Prečo? Lebo k písaniu dochádza v najnevhodnejší možný čas: funkcia je hotová a pozornosť sa už presunula inam. Codex tento náklad presúva. Analyzuje kód tak, ako existuje, a vytvára úplnú, aktuálnu dokumentáciu, ktorá zodpovedá skutočnej implementácii. Táto vernosť je rozhodujúcim faktorom: vymyslená dokumentácia spôsobuje viac škody než prázdna stránka, pretože vyvoláva falošnú dôveru.
Vnorená dokumentácia: JSDoc a komentáre
Najčastejšie konzultovaná dokumentácia sa zobrazuje priamo v bublinovej nápovede editora, presne tam, kde vzniká otázka.
"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."
Tu je výsledok, ktorý Codex vyprodukoval pre funkciu výpočtu ceny:
/**
* 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 {
// ...
}
Dve informácie tu majú väčšiu váhu než všetko ostatné: jednotka – centy, nie eurá – a výnimka vyvolaná pri záporných hodnotách. Presne toto sú dve veci, ktoré vývojár zistí až v produkcii, potom, čo zákazníkom účtoval desaťkrát menej, než mal. Codex tieto údaje extrahoval priamo z implementácie, nie zo všeobecnej šablóny komentárov.
Generovanie súboru README
Pre nový projekt alebo pre súbor README, ktorý sa v dôsledku driftu stal fikciou, definuj, čo musí čitateľ vedieť urobiť po jeho prečítaní.
"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 sa opiera o súbor package.json, konfiguračné súbory a skutočnú štruktúru adresárov, aby vytvoril dokument odrážajúci aktuálny stav projektu. Pokyn „bez hodnôt“ nie je rozmar: bez neho by agent, ktorý práve čítal dobre vyplnený súbor .env.example, mohol pokojne skopírovať hodnoty, ktoré nechceš mať vo verzionovanom súbore.
Dokumentácia API
Pre REST API je najnákladovo efektívnejšou dokumentáciou tá, ktorú môžu iné nástroje spotrebovať bez ľudského zásahu.
"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."
Všetko sa extrahuje priamo z kódu: cesty trás, HTTP metódy, schémy validácie a typy odpovedí. Výsledná špecifikácia je preto verná implementácii, čo umožňuje tvojim konzumentom odvodiť typovaného klienta alebo kolekciu testov bez toho, aby ti položili jedinú otázku.
Dokumentácia architektúry
Rozhodnutia o architektúre sa zriedka zapisujú. Ak áno, opisujú pôvodný zámer, nie realitu o tri roky neskôr. Požiadaj Codex, aby formalizoval to, čo skutočne existuje v kóde.
"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"
Tento dokument má neočakávaný vedľajší benefit: opisom závislostí medzi modulmi tak, ako skutočne sú, odhaľuje väzby, ktoré nikto neuznal – napríklad fakt, že fakturačná služba importuje utilitu z autentifikačného modulu.
Aktualizácia existujúcej dokumentácie
Zastaraná dokumentácia je horšia než žiadna, pretože plytvá časom a pôsobí pritom autoritatívne.
"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ždé tvrdenie v súbore README so skutočným kódom a opravuje nezrovnalosti. Naplánuj si túto úlohu pravidelne, napríklad pred každým vydaním, namiesto toho, aby si na jej nevyhnutnosť prišiel v deň, keď nový zamestnanec zistí, že žiadny z inštalačných príkazov nefunguje.
Automatizácia prostredníctvom AGENTS.md
Aby si prestal považovať dokumentáciu za samostatnú povinnosť, urob z nej trvalé obmedzenie 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
S týmito tromi pravidlami so sebou každá vývojová úloha nesie aj aktualizáciu dokumentácie. Priepasť medzi kódom a popisom sa prestane ticho zväčšovať, čo je jediný udržateľný spôsob, ako túto bitku vyhrať.
Kľúčové poznatky
- Codex generuje dokumentáciu vernú skutočnému kódu, nie vymyslenú
- Vnorená dokumentácia (JSDoc) je najužitočnejšia pre dennú prácu
- Codex dokáže vytvoriť súbory README, špecifikácie OpenAPI a dokumentáciu architektúry
- Použi Codex na detekciu a opravu zastaranej dokumentácie
- Pridaj pravidlá pre dokumentáciu do súboru AGENTS.md, aby si automatizoval tento proces