Automatikus dokumentáció
Ezen az oldalon
Dokumentálás a fejlesztés megszakítása nélkül
Mindenki egyetért abban, hogy a dokumentáció szükséges, mégis szinte senki nem írja meg. Miért? Mert az írásra a legrosszabbkor kerül sor: a funkció elkészült, és a figyelem már máshol jár. A Codex eltolja ezt a költséget. Elemzi a kódot annak jelenlegi állapotában, és teljes, naprakész dokumentációt készít, amely hűen tükrözi a tényleges megvalósítást. Ez a hűség a döntő tényező: a kitalált dokumentáció több kárt okoz, mint az üres lap, mert hamis biztonságérzetet kelt.
Beágyazott dokumentáció: JSDoc és megjegyzések
A leggyakrabban használt dokumentáció közvetlenül a szerkesztő eszköztippjében jelenik meg, pontosan ott, ahol a kérdés felmerül.
"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."
Íme, mit hoz létre a Codex egy árszámító függvényhez:
/**
* 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 {
// ...
}
Ebben a két információ többet ér minden másnál: a mértékegység (cent, nem euró) és a negatív értékek esetén dobott kivétel. Ezek pontosan azok a dolgok, amelyeket a fejlesztő általában éles környezetben fedez fel, miután az ügyfeleket a tervezett összeg tizedrészével számlázták meg. A Codex ezeket a megvalósításból nyerte ki, nem pedig egy általános megjegyzéssablonból.
README generálása
Egy új projektnél, vagy ha a README a drift miatt már fikcióvá vált, sorold fel, mit kell tudnia csinálnia az olvasónak az elolvasás után.
"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"
A Codex a package.json-ra, a konfigurációs fájlokra és a tényleges könyvtárszerkezetre támaszkodik, hogy olyan dokumentumot hozzon létre, amely a projekt aktuális állapotát tükrözi. A „értékek nélkül“ utasítás nem szeszély: enélkül egy ügynök, amely éppen elolvasott egy jól kitöltött .env.example fájlt, vidáman másolhatna olyan értékeket, amelyeket nem szeretnél, ha verziókezelt fájlban szerepelnének.
API dokumentáció
REST API esetén a legköltséghatékonyabb dokumentáció az, amelyet más eszközök emberi beavatkozás nélkül képesek fogyasztani.
"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."
Minden a kódból származik: útvonalak, HTTP metódusok, validációs sémák és válasz típusok. Az így kapott specifikáció ezért hű a megvalósításhoz, lehetővé téve a fogyasztóid számára, hogy típusos klienst vagy tesztgyűjteményt vezessenek le belőle anélkül, hogy egyetlen kérdést is feltennének neked.
Architektúra dokumentáció
Az architektúrális döntéseket ritkán jegyzik le. Ha mégis, azok a kezdeti szándékot írják le, nem pedig a három évvel későbbi valóságot. Kérd meg a Codexet, hogy formalizálja azt, ami ténylegesen létezik a kódban.
"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"
Ennek a dokumentumnak van egy váratlan mellékhaszna: a modulfüggőségek valós leírásával feltár olyan csatolásokat, amelyeket senki nem ismert el – például, hogy a számlázási szolgáltatás importál egy segédprogramot a hitelesítési modulból.
Meglévő dokumentáció frissítése
Az elavult dokumentáció rosszabb, mint a semmilyen, mert tekintéllyel pazarolja az időt.
"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."
A Codex szembesíti a README minden állítását a tényleges kóddal, és kijavítja az inkonzisztenciákat. Ütemezd ezt a feladatot időszakosan, például minden kiadás előtt, ahelyett, hogy csak akkor döbbennél rá a szükségességére, amikor egy új munkatárs rájön, hogy a telepítési parancsok egyike sem működik.
Automatizálás az AGENTS.md segítségével
Ahhoz, hogy a dokumentációt ne külön feladatként kezeld, tedd a projekt állandó korlátozásává.
## 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
Ezzel a három szabállyal minden fejlesztési feladat magában hordozza a saját dokumentációs frissítését. A kód és a leírás közötti szakadék不再 növekszik csendben, és ez az egyetlen fenntartható módja ennek a harcnak a megnyerésére.
Főbb megállapítások
- A Codex a tényleges kódhoz hű dokumentációt generál, nem kitaláltat
- A beágyazott dokumentáció (JSDoc) a napi munka szempontjából a leghasznosabb
- A Codex képes README, OpenAPI specifikációk és architektúra dokumentáció létrehozására
- Használd a Codexet az elavult dokumentáció észlelésére és javítására
- Vegyél fel dokumentációs szabályokat az AGENTS.md fájlba a folyamat automatizálásához