Automatisk dokumentation
På denne side
Dokumentér uden at afbryde udviklingen
Alle er enige om, at dokumentation er nødvendig, men næsten ingen skriver den. Hvorfor? Fordi skrivningen sker på det værst tænkelige tidspunkt: funktionen er færdig, og opmærksomheden er allerede flyttet videre. Codex flytter denne omkostning. Det analyserer koden, som den eksisterer, og producerer komplet, opdateret dokumentation, der stemmer overens med den faktiske implementering. Denne nøjagtighed er afgørende: opfundet dokumentation gør mere skade end en tom side, fordi den skaber falsk tillid.
Indlejret dokumentation: JSDoc og kommentarer
Den mest konsulterede dokumentation vises direkte i editorens værktøjstip, præcis hvor spørgsmålet opstår.
"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."
Her er hvad Codex producerer for en funktion til prisberegning:
/**
* 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 {
// ...
}
To oplysninger her er mere værd end alt andet: enheden – cent, ikke euro – og undtagelsen, der kastes ved negative værdier. Det er præcis de to ting, en udvikler normalt opdager i produktion, efter at have faktureret kunder ti gange mindre end tilsigtet. Codex udtrak dem fra implementeringen, ikke fra en generisk kommentarskabelon.
Generering af en README
Til et nyt projekt, eller til en README, der er blevet fiktion på grund af afdrift, skal du liste op, hvad læseren skal kunne gøre, når han eller hun er færdig med at læse.
"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 bruger package.json, konfigurationsfiler og det faktiske目录træ til at producere et dokument, der afspejler projektets aktuelle tilstand. Instruktionen „uden værdier” er ikke et lune: uden den kunne en agent, der lige har læst en veludfyldt .env.example, gladeligt kopiere værdier, du ikke ønsker skal fremgå af en versionsstyret fil.
API-dokumentation
For et REST-API er den mest omkostningseffektive dokumentation den, som andre værktøjer kan forbruge uden menneskelig indgriben.
"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."
Alt udtrækkes fra koden: rutestier, HTTP-metoder, valideringsskemaer og responstyper. Den resulterende specifikation er derfor tro mod implementeringen, hvilket giver dine forbrugere mulighed for at udlede en typet klient eller en testsamling uden at stille dig et eneste spørgsmål.
Arkitekturdokumentation
Arkitekturelle beslutninger bliver sjældent skrevet ned. Når de gør, beskriver de den oprindelige hensigt snarere end virkeligheden tre år senere. Bed Codex om at formalisere det, der faktisk eksisterer i koden.
"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"
Dette dokument har en uventet sekundær fordel: Ved at beskrive modulafhængigheder, som de virkelig er, afslører det koblinger, som ingen havde anerkendt – såsom faktureringstjenesten, der importerer et hjælpeprogram fra autentificeringsmodulet.
Opdatering af eksisterende dokumentation
Forældet dokumentation er værre end ingen dokumentation, fordi den spilder tid med autoritet.
"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 konfronterer hver påstand i README’en med den faktiske kode og retter inkonsistenser. Planlæg denne opgave med jævne mellemrum, f.eks. før hver release, i stedet for at opdage nødvendigheden den dag, en ny medarbejder finder ud af, at ingen af installationskommandoerne virker.
Automatisering via AGENTS.md
For at holde op med at behandle dokumentation som en separat pligt, skal du gøre den til en permanent begrænsning for projektet.
## 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
Med disse tre regler bærer hver udviklingsopgave sin egen dokumentationsopdatering. Kløften mellem kode og beskrivelse holder op med at vokse i stilhed, hvilket er den eneste bæredygtige måde at vinde denne kamp på.
Vigtige pointer
- Codex genererer dokumentation, der er tro mod den faktiske kode, ikke opfundet
- Indlejret dokumentation (JSDoc) er mest nyttig til det daglige arbejde
- Codex kan producere README-filer, OpenAPI-specifikationer og arkitektur-dokumentation
- Brug Codex til at opdage og rette forældet dokumentation
- Tilføj dokumentationsregler til AGENTS.md for at automatisere processen