Как я обновил архитектуру голосового агента за один вечер

Работаю над проектом ai-agents-voice-agent — это голосовой ассистент, построенный на Claude API с поддержкой десктопной автоматизации. Недавно добавили новый модуль CUA (Computer Use Agent) на базе UI-TARS VLM, и документация отстала от реальности на несколько итераций.

Проблема классическая: разработчики добавляют функции, коммитят в main, но документация остаётся в статусе «to-do». Я открыл docs/architecture/ и понял — там старая структура, нет упоминания о CUA, а в CAPABILITY_ARCHITECTURE.md описана трёхуровневая архитектура, хотя фактически их уже четыре.

Решил обновить все критические файлы параллельно:

Переделал overview.md — добавил CUA в проекцию модулей, обновил граф зависимостей, расширил tech stack упоминанием UI-TARS. Теперь новый разработчик сразу видит, что есть desktop automation.

Переписал CAPABILITY_ARCHITECTURE.md — это был ключевой файл. Сменил 3-уровневую иерархию на 4-уровневую: веб-инструменты → десктоп-инструменты → встроенные модули → локальные пакеты. К четвёртому уровню добавил примеры (requests, pillow) и decision tree для выбора между слоями.

Обновил документацию TMA (tma/00-ARCHITECTURE.md) — убрал все пометки “(NEW)” (они потеряли смысл), переименовал секцию “Новые файлы” в “Файлы модуля” для фактичности.

Актуализировал 06-NEW-INTERFACES.md — это было больно. Там была информация о Tesseract OCR, которая вообще не использовалась. Заменил на CUA с описанием UI-TARS, добавил три забытых десктоп-инструмента (desktop_drag, desktop_scroll, desktop_wait). Фаза 3 теперь содержит 21 инструмент вместо старых 12.

Закрыл все задачи Фазы 3 в 02-TASK-LIST.md — просто поставил галочки рядом с пунктами 3.1–3.9. Формально это не мой долг, но документация о незавершённых делах раздражает.

Вся работа заняла около часа благодаря параллельному обновлению файлов. Главное — не оставлять документацию как груз, который весит на совести. Она либо актуальна, либо токсична.

---

Кстати, есть такая шутка в мире DevOps: Apache — единственная технология, где «это работает» считается полноценной документацией. 😄