AI и документация: практический воркфлоу, который наконец работает

Документация — как стоматолог: все знают, что надо, никто не хочет. AI это меняет. Не тем, что пишет идеальную документацию, а тем, что превращает полдня работы в полчаса. И результат часто лучше, потому что AI не пропускает «очевидные» детали.

Что AI умеет в документации

AI отлично генерирует первый черновик — а черновик это 80% работы. Вот что можно делегировать:

• JSDoc/docstrings из кода — AI читает функцию и пишет описание, параметры, возвращаемые значения
• README для модуля на основе API и структуры
• Changelog из git-истории
• Архитектурная документация из кода — потоки данных, зависимости, модули
• Перевод внутренних документов
• API-документация из эндпоинтов — форматы запросов/ответов, примеры

# Prompt for module documentation:

Read all files in src/services/payment/
and write documentation:

1. Overview — what the module does, one paragraph
2. Architecture — how files relate to each other
3. API — public functions with params and examples
4. Dependencies — what the module needs
5. Known limitations and tech debt

Format: Markdown, concise, no marketing.

Что AI не умеет в документации

Объяснить ЗАЧЕМ. Документация «эта функция делает X» бесполезна — это видно в коде. Документация «мы создали эту функцию, потому что предыдущий подход Y имел проблему Z» — AI не знает.

AI также не может надёжно документировать неявные знания команды: «Никогда не мигрируй эту таблицу в пятницу». «Этот эндпоинт использует другой auth flow». Это должен добавить человек.

Практический воркфлоу в три шага

Шаг 1: AI генерирует основу из кода

Дайте AI доступ к кодовой базе и скажите: «Напиши документацию для [модуль/функция/API]. Включи обзор, описание API, примеры использования и известные ограничения». AI прочитает код и сгенерирует первый черновик.

Шаг 2: Вы добавляете контекст, причины и нюансы

Просмотрите черновик и добавьте: почему сделали так, какие альтернативы рассматривали, подводные камни. Эту часть умеете только вы — и благодаря AI можете сосредоточиться исключительно на ней.

Шаг 3: AI форматирует и уточняет

После ваших правок дайте AI завершить: «Отформатируй единообразно. Добавь недостающие примеры. Проверь, что описания API соответствуют коду». AI доведёт до ума и поймает несоответствия.

Конкретные кейсы, которые работают

CLAUDE.md как живая документация

CLAUDE.md в корне проекта — документ для AI-агентов, но также отличная документация для новых людей. Содержит стек, команды сборки, конвенции, решения. И поскольку AI активно его использует, он остаётся актуальным — в отличие от вики.

# CLAUDE.md — living documentation example

## Stack
Next.js 16, TypeScript, Tailwind, Prisma

## Conventions
- Functions: camelCase, components: PascalCase
- Tests: vitest, files: *.test.ts
- Commit messages: conventional commits

## Key decisions
- Auth: JWT + httpOnly cookies (not sessions)
  Reason: microservices need stateless auth
- DB: Postgres + Prisma (not TypeORM)
  Reason: better type safety, simpler migrations

Автоматический changelog из git-истории

Вместо ручного написания: «Прочитай git log за 2 недели и сгенерируй changelog. Группируй по: features, fixes, refactoring. Описывай с точки зрения пользователя».

Руководство по онбордингу из кода

«Напиши руководство для нового разработчика. Включи: как запустить локально, ключевые файлы, обзор архитектуры, куда смотреть первым делом». AI прочитает проект и создаст руководство, которое вручную заняло бы полдня.

Результат: документация, которая существует

Существующая документация бесконечно лучше идеальной документации, которой не существует.

AI не снизит барьер до нуля — нужно добавить контекст и проверить точность. Но снизит настолько, что документация перестанет быть задачей, которую откладывают «на потом». И это меняет всё.