AI Documentation Agent: Docs That Write Themselves

The Problem

Engineering teams ship code faster than they write docs. When a PR merges, documentation is either written days later (if at all), inconsistently formatted, or delegated to a developer who would rather be coding. The result: outdated docs, frustrated users, and a support burden that compounds over time.

The ask: an agent that watches the development workflow and writes the first draft automatically, triggered by the same event that ships the code.

What It Does

• Detects when code ships: Listens for Linear issues labeled "Docs" that transition to a completed state (PR merged). No polling — event-driven from the moment a PR closes.
• Fetches the diff automatically: Queries the GitHub API to retrieve the merged PR diff for the relevant files. If no PR link is attached to the Linear issue, the agent searches GitHub for PRs referencing the issue identifier.
• Generates structured documentation: Sends the diff to Claude with a structured prompt that produces a formatted, ready-to-review documentation draft — not a summary, a real doc page.
• Opens a PR in the docs repo: Commits the generated content to the Mintlify documentation repository and opens a pull request for a human to review and merge.
• Human stays in control: The agent handles the grunt work. The team owns quality — one review pass instead of a blank page.

How It Was Built

• FastAPI: Webhook listener that receives Linear events and orchestrates the full pipeline — validation, GitHub fetch, Claude generation, Mintlify PR.
• Linear API: Receives webhook payloads, reads issue metadata, labels, and completion state to determine whether a doc generation should trigger.
• GitHub API: Fetches merged PR diffs scoped to relevant directories. Includes a fallback search for PRs that reference the Linear issue identifier when no direct link exists.
• Claude API (Anthropic): Core intelligence — takes raw code diffs and produces structured, human-readable documentation drafts with consistent formatting.
• Mintlify: Target documentation platform. The agent opens PRs directly to the docs repository using the GitHub API.
• Google Cloud Run: Fully managed, event-driven deployment. Scales to zero between webhook events — no idle compute cost.

Results

First end-to-end test confirmed: a Linear issue with a "Docs" label transitioned to completed, the agent fetched the associated PR diff from GitHub, generated a documentation draft with Claude, and opened a PR in the docs repository — triggered automatically, no human action required after initial setup.

Setup time for a new codebase: one day. Ongoing maintenance: near zero. Every merged PR with a "Docs" label becomes a documentation PR.