Automatická dokumentace
Na této stránce
Dokumentace bez přerušování vývoje
Všichni se shodují, že dokumentace je nezbytná, přesto ji téměř nikdo nepíše. Proč? Protože k psaní dochází v ten nejnevhodnější okamžik: funkce je hotová a pozornost se již přesunula jinam. Codex tento náklad přesouvá. Analyzuje kód tak, jak existuje, a vytváří úplnou, aktuální dokumentaci, která odpovídá skutečné implementaci. Tato věrnost je rozhodujícím faktorem: vymyšlená dokumentace napáchá více škody než prázdná stránka, protože vyvolává falešnou důvěru.
Vložená dokumentace: JSDoc a komentáře
Nejpoužívanější dokumentace se zobrazuje přímo v bublinové nápovědě editoru, přesně tam, kde vyvstane 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."
Zde je výsledek, který Codex vytvořil pro funkci 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 {
// ...
}
Dvě informace zde mají větší cenu než vše ostatní: jednotka – centy, nikoliv eura – a výjimka vyhazovaná pro záporné hodnoty. Přesně toto jsou dvě věci, které vývojář obvykle zjistí až v produkci, poté, co zákazníkům naúčtoval desetkrát méně, než měl v úmyslu. Codex tyto údaje extrahoval přímo z implementace, nikoliv ze šablony obecného komentáře.
Generování souboru README
U nového projektu nebo u souboru README, který se vlivem driftu stal fikcí, definuj, co musí být čtenář schopen udělat, jakmile dokončí čtení.
"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 se opírá o soubor package.json, konfigurační soubory a skutečnou strukturu adresářů, aby vytvořil dokument odrážející aktuální stav projektu. Pokyn „bez hodnot“ není rozmar: bez něj by agent, který právě četl dobře vyplněný soubor .env.example, mohl s klidem zkopírovat hodnoty, které nechceš mít ve verzovaném souboru.
Dokumentace API
U REST API je nejnákladově efektivnější dokumentace ta, kterou mohou jiné nástroje spotřebovat bez lidské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še je extrahováno z kódu: cesty tras, HTTP metody, schémata validace a typy odpovědí. Výsledná specifikace je proto věrná implementaci, což umožňuje tvým konzumentům odvodit typovaného klienta nebo sadu testů, aniž by ti museli položit jedinou otázku.
Dokumentace architektury
Rozhodnutí o architektuře jsou zřídka zapisována. Pokud ano, popisují původní záměr, nikoliv realitu o tři roky později. Požádej Codex, aby formalizoval to, co skutečně existuje v kódu.
"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čekávaný vedlejší přínos: popisem závislostí modulů tak, jak skutečně jsou, odhaluje vazby, které nikdo neuznával – například fakt, že fakturační služba importuje utilitu z modulu autentizace.
Aktualizace stávající dokumentace
Zastaralá dokumentace je horší než žádná, protože plýtvá časem s autoritou.
"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é tvrzení v souboru README se skutečným kódem a opravuje nesrovnalosti. Naplánuj si tento úkol pravidelně, například před každým vydáním, abys nemusel zjistit jeho nutnost až ve chvíli, kdy nový zaměstnanec zjistí, že žádný z instalačních příkazů nefunguje.
Automatizace prostřednictvím AGENTS.md
Aby přestal být dokumentace považována za samostatnou povinnost, učiň z ní trvalé omezení 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 třemi pravidly nese každý vývojový úkol svou vlastní aktualizaci dokumentace. Rozdíl mezi kódem a popisem přestane tiše narůstat, což je jediný udržitelný způsob, jak tuto bitvu vyhrát.
Klíčové poznatky
- Codex generuje dokumentaci věrnou skutečnému kódu, nikoliv vymyšlenou
- Vložená dokumentace (JSDoc) je nejužitečnější pro denní práci
- Codex dokáže vytvářet soubory README, specifikace OpenAPI a dokumentaci architektury
- Použij Codex k detekci a opravě zastaralé dokumentace
- Přidej pravidla pro dokumentaci do souboru AGENTS.md pro automatizaci procesu