Automaatne dokumentatsioon
Sellel lehel
Dokumenteerimine arendust katkestamata
Kõik on nõus, et dokumentatsioon on vajalik, kuid peaaegu keegi ei kirjuta seda. Miks? Sest kirjutamine toimub kõige halvemal võimalikul hetkel: funktsioon on valmis ja tähelepanu on juba mujale liikunud. Codex nihutab seda kulu. See analüüsib olemasolevat koodi ja loob tervikliku, ajakohase dokumentatsiooni, mis vastab tegelikule teostusele. See täpsus on otsustav tegur: väljamõeldud dokumentatsioon teeb rohkem kahju kui tühi leht, sest see tekitab vale kindlustunde.
Reasisene dokumentatsioon: JSDoc ja kommentaarid
Kõige enam kasutatav dokumentatsioon ilmub otse redaktori tööriistavihjesse, täpselt sinna, kus küsimus tekib.
"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."
Siin on see, mida Codex toodab hinna arvutamise funktsiooni jaoks:
/**
* 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 {
// ...
}
Siin on kaks teabetükki, mis kaaluvad üles kõik muu: ühik – sendid, mitte eurod – ja negatiivsete väärtuste korral visatav erind. Need on täpselt need kaks asja, mille arendaja tavaliselt tootmiskeskkonnas avastab, pärast seda, kui on klientidelt kümme korda vähem arvestanud kui plaanis. Codex ekstraheeris need teostusest, mitte üldisest kommentaarimallist.
README faili genereerimine
Uue projekti puhul või kui README on lahknevuse tõttu muutunud fiktsiooniks, loetle üles, mida lugeja peab pärast lugemist suutma teha.
"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 tugineb failile package.json, konfiguratsioonifailidele ja tegelikule kataloogipuule, et luua dokument, mis peegeldab projekti praegust seisundit. Juhis „ilma väärtusteta“ ei ole kapriis: ilma selleta võib agent, kes on just lugenud hästi täidetud .env.example faili, rõõmsalt kopeerida väärtused, mida sa versioonitud failis näha ei soovi.
API dokumentatsioon
REST API puhul on kuluefektiivseim dokumentatsioon see, mida teised tööriistad saavad tarbida ilma inimese sekkumiseta.
"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."
Kõik ekstraheeritakse koodist: marsruutide rajad, HTTP meetodid, valideerimisskeemid ja vastuse tüübid. Saadud spetsifikatsioon on seetõttu teostusele truu, võimaldades sinu tarbijatel tuletada tüübitud kliendi või testide kogumiku, ilma et nad peaksid sulle ühtegi küsimust esitama.
Arhitektuuri dokumentatsioon
Arhitektuuriotsuseid kirjutatakse harva üles. Kui seda tehakse, kirjeldavad need algset kavatsust, mitte reaalsust kolm aastat hiljem. Palu Codexil formaliseerida see, mis koodis tegelikult eksisteerib.
"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"
Sellel dokumendil on ootamatu kõrvalkasu: kirjeldades moodulite sõltuvusi nii, nagu need tegelikult on, paljastab see sidususi, mida keegi pole tunnistanud – näiteks arveldusteenus, mis impordib utiliidi autentimismoodulist.
Olemasoleva dokumentatsiooni uuendamine
Aegunud dokumentatsioon on halvem kui dokumentatsiooni puudumine, sest see raiskab aega autoriteetsuse varjus.
"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 seab iga README väite vastamisi tegeliku koodiga ja parandab lahknevused. Planeeri see ülesanne perioodiliselt, näiteks enne iga väljalaset, selle asemel, et avastada selle vajalikkust päeval, mil uus töötaja avastab, et ükski paigalduskäsk ei tööta.
Automatiseerimine faili AGENTS.md kaudu
Selleks, et lõpetada dokumentatsiooni käsitlemist eraldi kohustusena, tee sellest projekti püsiv piirang.
## 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
Nende kolme reegliga kannab iga arendusülesanne endas ka oma dokumentatsiooni uuendamist. Lõhe koodi ja kirjelduse vahel lõpetab vaikselt laienemise, mis on ainus jätkusuutlik viis selles lahingus võitmiseks.
Peamised punktid
- Codex genereerib dokumentatsiooni, mis on truu tegelikule koodile, mitte väljamõeldud
- Reasisene dokumentatsioon (JSDoc) on igapäevatööks kõige kasulikum
- Codex suudab luua README-faile, OpenAPI spetsifikatsioone ja arhitektuuri dokumentatsiooni
- Kasuta Codexit aegunud dokumentatsiooni tuvastamiseks ja parandamiseks
- Lisa dokumentatsioonireeglid faili AGENTS.md, et protsessi automatiseerida