Documentation Generation with Codex

Your project has grown from a weekend prototype to a 12-service production system. The only documentation is a README from eight months ago that references an API endpoint that no longer exists. New hires spend their first week reading source code to figure out what anything does. You could block two sprints for a documentation push. Or you could have Codex generate accurate docs from the actual codebase and set up automations to keep them current.

What You’ll Walk Away With

• Prompts for generating API documentation, architecture guides, and onboarding docs from source code
• A worktree workflow for generating docs without touching your working directory
• Automation recipes for weekly documentation freshness checks
• Techniques for keeping docs in sync with code changes using AGENTS.md conventions

The Workflow

Step 1: Generate API Documentation

API docs are the highest-value documentation because they have direct, measurable impact on developer productivity. Use the CLI for a quick generation pass, or the App for iterative refinement.

Tip

Copy-paste prompt for API documentation generation:

Generate comprehensive API documentation for all endpoints in src/routes/. For each endpoint include:

1. HTTP method and path
2. Description of what it does
3. Request headers (especially authentication)
4. Request body schema with types and validation rules (read the Zod schemas)
5. Response schema for success (200/201) and error cases (400, 401, 404, 500)
6. Example request and response using realistic data
7. Rate limiting details if applicable

Output as a single Markdown file (docs/API.md) organized by route group.
Read the actual route handlers and Zod schemas -- do not guess at the types.

Run this in a Worktree thread so the generated file does not land in your working directory until you review it. After reviewing the diff in the App’s review pane, sync to local or create a branch and open a PR.

Step 2: Generate Architecture Documentation

Architecture docs go stale the fastest because they describe relationships between components, and those relationships change every sprint. Let Codex generate these from the actual code, not from memory.

Tip

Copy-paste prompt for architecture documentation:

Analyze the codebase and generate docs/ARCHITECTURE.md covering:

1. System overview: what this project does, who uses it, what problems it solves
2. Component map: each service/module, its responsibility, and how it communicates with others
3. Data flow: how a request enters the system, which services it touches, and how the response is assembled
4. Database schema: tables, relationships, and key indexes (read the schema files)
5. External dependencies: third-party APIs, message queues, caches, and how we integrate with each
6. Key design decisions: patterns used (event sourcing, CQRS, etc.) and why

Use text-based diagrams (ASCII or Mermaid) for the component map and data flow.
Write for a mid-level developer joining the team. Be specific about file paths.
Keep it under 400 lines.

Step 3: Generate Inline Code Documentation

For code that is complex enough to need explanation, generate JSDoc/TSDoc comments and module-level explanations:

Add JSDoc documentation to all exported functions in src/services/ that are currently undocumented. For each function:

1. A one-line description of what it does
2. @param tags with types and descriptions
3. @returns description
4. @throws for any errors the function can throw
5. @example with a realistic usage example

Do NOT add documentation to private/internal functions or simple getters.
Follow the existing documentation style in the codebase (check if any functions already have JSDoc).

Step 4: Update Documentation with the IDE Extension

The IDE extension is best for targeted documentation updates when you are already working in the code. With auto-context enabled, Codex sees the files you have open and can update docs based on what you just changed.

After implementing a new feature:

I just added a new POST /api/subscriptions/upgrade endpoint. Update docs/API.md to include this endpoint. Match the format and level of detail used for existing endpoints in that file. Also verify that all links in the API doc are still valid.

Step 5: Automate Documentation Freshness

The real power is in automation. Set up a weekly automation that checks whether your docs match the codebase:

Tip

Copy-paste automation prompt for weekly docs check:

Compare the documentation in docs/ against the actual codebase:

1. Check docs/API.md: Are all endpoints documented? Are any documented endpoints missing from the code? Do the request/response schemas match the current Zod schemas?
2. Check docs/ARCHITECTURE.md: Do the module descriptions match the current code structure? Are there new modules not mentioned? Are there mentioned modules that no longer exist?
3. Check README.md: Are the setup instructions still accurate? Do the listed scripts exist in package.json?

If any documentation is out of date, update it to match the current codebase. If everything is current, report that no updates are needed.

This automation runs in a dedicated worktree, so it never touches your working directory. Results appear in your automations inbox. If updates were needed, you will see a diff to review.

Generating Changelogs

For release documentation, Codex can generate changelogs from your git history. This works well as a cloud task since it benefits from reading the full commit history.

Generate a changelog for the upcoming release by analyzing all commits since the last git tag.

Group changes into:
- Features: new functionality
- Fixes: bug fixes
- Breaking changes: anything that changes the public API
- Internal: refactoring, dependency updates, CI changes

For each entry, write a user-facing description (not the commit message). Include the PR number if available. Highlight breaking changes with migration instructions.

Output as CHANGELOG.md in the standard Keep a Changelog format.

When This Breaks

Generated docs describe what the code does, not why. Codex reads the implementation and describes it accurately, but cannot explain business context or historical decisions. Add comments in your code explaining “why” (not “what”), and Codex will incorporate them. Alternatively, provide context in your prompt: “The webhook retry system was designed for eventual consistency with partner systems that have up to 72-hour delivery windows.”

API docs go stale within a week. Generated docs are only as current as the last time you generated them. The automation recipe in Step 5 catches this, but it only works if the automation runs regularly and you actually review the findings. Pin the automation in the Codex App so it does not get archived.

Documentation links break. If you generate docs with relative links to source files and then move those files, the links break silently. Include “verify that all file path references in the documentation point to files that actually exist” in your freshness check prompt.

Codex overwrites manual documentation. If your docs contain hand-written explanations alongside generated sections, Codex may overwrite the manual parts. Use clear section markers: <!-- Generated by Codex - do not edit below this line --> and tell Codex: “Only modify content between the generated section markers. Do not touch manually written sections.”

What’s Next

API Development with Codex Build the APIs that your documentation describes

Scheduled Task Automation Set up more automations for recurring tasks beyond documentation