Документация по коду одним вызовом Vibe Codex

Хорошая документация отвечает на «почему», а не на «что» — потому что «что» уже видно в коде.

Документация — это место, где AI-инструменты исторически опозорились: сгенерировали по сто страниц «вода-вода». Vibe Codex старается противоположное: писать коротко, ссылаться на реальные строки кода и явно подсвечивать места, в которых модель не уверена.

README за пять минут

$ vibe-codex docs readme
[opus] анализирую репозиторий...
[opus] язык: Go 1.22
[opus] точка входа: cmd/server/main.go
[opus] зависимости: 14 пакетов, в т. ч. fiber, pgx, redis
[opus] предполагаемое назначение: HTTP API для биллинга
[plan] README.md (новый), 84 строки

На выходе — не «awesome project», а конкретный README с четырьмя секциями: что делает, как запустить, как тестировать, как контрибьютить. Без «introduction», без эмодзи в заголовках, без бейджей-фантомов.

# billing-core

HTTP-сервис для выставления счетов и обработки платежей.

## Что делает

- POST /invoices: создать счёт по списку позиций
- POST /invoices/:id/refund: частичный или полный возврат
- GET /invoices/:id: статус счёта

Подробный OpenAPI: api/openapi.yaml

## Запуск

    docker compose up -d
    go run cmd/server

По умолчанию слушает :8080.

## Тесты

    go test -race ./...

Интеграционные используют Testcontainers с Postgres 16.

## Конфигурация

См. config/dev.yaml. Перекрытие через переменные окружения
с префиксом BILLING_*.

API-документация

Если у вас OpenAPI — Vibe Codex сверяет его с кодом и подсвечивает рассогласования.

$ vibe-codex docs api --check
[opus] 3 рассогласования:
  - openapi.yaml: GET /invoices/:id возвращает 200/404
    code: возвращает также 410 (для удалённых) — не описано
  - openapi.yaml: POST /invoices, поле dueDate optional
    code: на самом деле required, нет default
  - openapi.yaml: header X-Idempotency-Key не описан
    code: используется в InvoiceController.create

На --fix ассистент обновит OpenAPI и пересоберёт клиенты.

Архитектурный обзор

Для нового человека в проекте полезнее всего короткий ARCHITECTURE.md — на пять минут чтения. Vibe Codex генерирует его, прочитав структуру и выделив реальные слои.

$ vibe-codex docs architecture
[written] docs/ARCHITECTURE.md (118 строк)

# Architecture

## Слои

- internal/api      — HTTP-обработчики, валидация, маппинг DTO
- internal/service  — доменная логика (Invoice, Refund, Tax)
- internal/repo     — Postgres через pgx, без ORM
- internal/event    — публикация в Kafka, схема в proto/

## Данные

PostgreSQL 16, 12 таблиц. Миграции в db/migration/ (Flyway).
JSONB используется только в invoices.metadata — для гибких
полей от партнёров. Запросы через jsonb_extract_path,
не через operator `?`.

## Инварианты

- Idempotency-Key обязателен на всех write-операциях
- Refund не может превышать остаток invoice
- Все timestamp в UTC, конверсия только на API-границе

## Что не делать

- Не складировать бизнес-логику в repo/
- Не использовать pgx.Conn напрямую в API-слое
- Не создавать новые таблицы без миграции

Раздел «Что не делать» — самый ценный. Он сохраняет негласные правила в исполняемом виде.

«Хорошая документация — это contract с будущим собой. Плохая — это маркетинговый блёрб на главной репозитория».

Документация в коде

Doc-комментарии — Vibe Codex добавляет их только там, где функция не объясняет себя именем и сигнатурой. Не «// returns the user» поверх GetUser(), а реальные пояснения: контракт, предусловия, побочные эффекты.

// markPaid атомарно списывает баланс пользователя и переводит
// инвойс в статус PAID. Идемпотентен: повторный вызов с
// одним и тем же Idempotency-Key возвращает результат
// первого вызова без побочных эффектов.
//
// Возвращает ErrInsufficientFunds, если баланса не хватает.
// В этом случае инвойс остаётся в статусе AWAITING_PAYMENT.
func (s *InvoiceService) markPaid(ctx context.Context, id int64, key string) error

Чего НЕ делать

• Не генерировать «полную документацию по проекту» одной командой. Это всегда «вода»; читать никто не будет.
• Не описывать тривиальное. GetByID(id) returns the entity by ID — мусор.
• Не вставлять блоки «AI-сгенерировано» в заголовке. Раздражает.
• Не использовать ассистент для перевода доки на другие языки без ручного ревью. Технические термины он может перевести бессмысленно.

Один полезный ритуал

После каждого крупного рефакторинга — vibe-codex docs sync. Команда сверяет README, ARCHITECTURE и doc-комменты с актуальным кодом, подсвечивает устаревшие куски и предлагает правки. Это занимает 2 минуты, а спасает от «у нас в репозитории всё врёт».

$ vibe-codex docs sync --since=2w
[opus] 3 файла протухли:
  - README.md: упомянут endpoint /old-refund, был удалён 8 дней назад
  - docs/ARCHITECTURE.md: слой internal/cache переехал в pkg/cache
  - api/openapi.yaml: схема User не отражает поле addedAt

Где останавливаться

Документация — это место, где «достаточно» лучше, чем «всеобъемлюще». Если в репозитории есть короткий README, ARCHITECTURE и осмысленные doc-комменты на ключевые функции — этого хватит. Всё остальное стареет быстрее, чем читается.

Vibe Codex хорош в документации именно потому, что не пытается её писать «красиво». Пишет коротко, ссылается на код, признаётся в незнании. Этого, как ни странно, недостаёт большинству инструментов с AI на борту.