Dokumentācijas automatizācija
Šajā lapā
Dokumentēšana, netraucējot izstrādi
Visi piekrīt, ka dokumentācija ir nepieciešama, taču gandrīz neviens to neraksta. Kāpēc? Tāpēc, ka rakstīšana notiek visneizdevīgākajā brīdī: funkcija ir pabeigta, un uzmanība jau ir novirzīta citur. Codex maina šo dinamiku. Tas analizē kodu tādu, kāds tas ir, un ģenerē pilnīgu, aktuālu dokumentāciju, kas atbilst faktiskajai implementācijai. Šī precizitāte ir izšķirošais faktors: izgudrota dokumentācija nodara lielāku ļaunumu nekā tukša lapa, jo tā rada maldīgu pārliecību.
Iekļautā dokumentācija: JSDoc un komentāri
Visbiežāk lietotā dokumentācija parādās tieši redaktora rīka padomā (tooltip), tieši tajā brīdī, kad rodas jautājums.
"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."
Lūk, ko Codex ģenerē cenas aprēķināšanas funkcijai:
/**
* 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 {
// ...
}
Šeit divas informācijas daļas ir vērtīgākas par pārējo: mērvienība (centi, nevis eiro) un izņēmums, kas tiek izmests negatīvu vērtību gadījumā. Tieši šīs divas lietas izstrādātājs parasti uzzina produkcijas vidē, pēc tam, kad klientiem ir izrakstīti rēķini par desmit reizēm mazākām summām, nekā paredzēts. Codex tās ieguva tieši no implementācijas, nevis no vispārīga komentāru šablona.
README ģenerēšana
Jaunam projektam vai README failam, kas noviržu dēļ kļuvis par fikciju, uzskaiti to, ko lasītājam jāspēj izdarīt, tiklīdz viņš ir beidzis lasīt.
"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 balstās uz package.json, konfigurācijas failiem un faktisko direktoriju koku, lai izveidotu dokumentu, kas atspoguļo projekta pašreizējo stāvokli. Instrukcija „bez vērtībām” nav kaprīze: bez tās aģents, kurš tikko izlasījis labi aizpildītu .env.example, varētu bez raizēm nokopēt vērtības, kuras tu nevēlies redzēt versiju kontrolē esošā failā.
API dokumentācija
REST API gadījumā visizdevīgākā dokumentācija ir tāda, ko citi rīki var izmantot bez cilvēka iejaukšanās.
"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."
Viss tiek iegūts no koda: maršrutu ceļi, HTTP metodes, validācijas shēmas un atbilžu tipi. Iegūtā specifikācija tādējādi precīzi atbilst implementācijai, ļaujot taviem lietotājiem izveidot tipizētu klientu vai testu kolekciju, neuzdodot tev nevienu jautājumu.
Arhitektūras dokumentācija
Lēmumi par arhitektūru reti tiek pierakstīti. Kad tie tomēr tiek fiksēti, tie apraksta sākotnējo nodomu, nevis realitāti trīs gadus vēlāk. Palūdz Codex formalizēt to, kas faktiski eksistē kodā.
"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"
Šim dokumentam ir negaidīts papildu ieguvums: aprakstot moduļu atkarības tādas, kādas tās patiesībā ir, tas atklāj saistījumus, ko neviens nebija atzinis – piemēram, rēķinu izrakstīšanas serviss, kas importē utilītu no autentifikācijas moduļa.
Esošās dokumentācijas atjaunināšana
Novecojusi dokumentācija ir sliktāka par dokumentācijas neesamību, jo tā tērē laiku, liekoties autoritatīvai.
"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 salīdzina katru README apgalvojumu ar faktisko kodu un labo neatbilstības. Ieplāno šo uzdevumu periodiski, piemēram, pirms katras laides, nevis atklāj tā nepieciešamību dienā, kad jaunais darbinieks konstatē, ka neviena no instalācijas komandām nedarbojas.
Automatizācija, izmantojot AGENTS.md
Lai pārtrauktu uzskatīt dokumentāciju par atsevišķu pienākumu, padari to par pastāvīgu projekta nosacījumu.
## 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
Ar šiem trim noteikumiem katrs izstrādes uzdevums sevī ietver arī dokumentācijas atjaunināšanu. Atstarpe starp kodu un tā aprakstu vairs netilpst klusi, kas ir vienīgais ilgtspējīgais veids, kā uzvarēt šajā cīņā.
Galvenās atziņas
- Codex ģenerē dokumentāciju, kas ir precīza attiecībā uz faktisko kodu, nevis izgudrota
- Iekļautā dokumentācija (JSDoc) ir visnoderīgākā ikdienas darbam
- Codex spēj izveidot README, OpenAPI specifikācijas un arhitektūras dokumentāciju
- Izmanto Codex, lai atklātu un labotu novecojušu dokumentāciju
- Pievieno dokumentācijas noteikumus failam AGENTS.md, lai automatizētu procesu