Документация, в которой находят. И люди, и агенты
База документации проекта вместо папки с md‑файлами: разделы, неизменяемые версии, поисковый индекс и права доступа для агентов. Агент не читает всё подряд: он ищет по индексу, получает список документов с фрагментами и открывает только нужный раздел. Вы читаете отформатированный документ в окне программы, агент дописывает его по ходу работы через cct docs.
Знакомая ситуация
Папка docs/ разрослась до сотни файлов, и большинство написал ИИ: после каждой задачи остаётся план, сводка, заметки, «итоговое решение». Никто их не сводит и не помечает устаревшими. Агент ищет grep‑ом, находит упоминание в прошлогоднем файле и строит на нём решение. Вы открываете Markdown в редакторе, не видите таблиц, не понимаете, какая версия актуальна, и спрашиваете у того, кто писал. Новый агент тратит первый час на чтение всего подряд. А если модулей несколько, правда о стыках между ними не лежит нигде.
Модуль «Документы» делает документацию общей памятью команды. Она лежит в одной базе с каркасом, индексом и правилами, которые агенты читают первыми. Агент за несколько команд находит и читает нужную главу, а вы видите в окне, что он записал, и правите текст там же.
Поиск по индексу: агент читает килобайты, а не мегабайты
меньше токенов на поиск ответа в документации по сравнению с чтением файлов целиком.По замерам на базе документации программы: 85 % против выборочного чтения пяти‑десяти файлов, 99,6 % против чтения всей папки. Подробности ниже.
Главное отличие от папки с файлами: документация индексируется в момент записи, и поиск идёт по индексу, а не по тексту. Агенту не нужно загружать документы в контекст, чтобы понять, где искать. Он задаёт слова, получает список документов с фрагментами вокруг совпадения и открывает только тот раздел, который нужен. Чем больше документация, тем заметнее разница.
Замер на реальной базе документации программы, 13 октября 2026: запрос резервн копи, затем оглавление найденной статьи и один её раздел. Против привычного сценария, когда агент ищет grep‑ом и открывает пять‑десять файлов целиком (35–70 КБ), экономия около 85 %; против чтения всей папки документации 99,6 %.
Что делает индекс
- Обновляется вместе с текстом. Запись документа и обновление индекса идут в одной транзакции: результат поиска никогда не отстаёт от документа.
- Понимает формы слов. Слова приводятся к основе для русского и английского, поэтому «резервн копи» находит «резервной копии» и «резервные копии». Идентификаторы вроде
docs_unavailableиappsettings.jsonиндексируются целиком и по частям. - Ставит нужный документ первым. Ранжирование BM25 с весами полей: совпадение в названии весит в восемь раз больше, чем в тексте, в кратком описании в четыре раза.
- Отдаёт фрагменты, а не тела. В ответе путь, краткое описание и до 240 символов вокруг лучшего совпадения. Текст документа агент запрашивает отдельно и только нужный раздел.
- Уважает права. Доступ к документам применяется при каждом запросе: агент не находит то, что ему не разрешено читать.
- Не вываливает сотню документов. Если все слова вместе не встречаются, частичные совпадения показываются отдельно и помечаются. Слишком общее начало слова просит уточнить запрос.
- Перестраивается в фоне. При смене движка новое поколение индекса строится порциями, не мешая записи, а поиск продолжает работать по старому, пока новое не готово.
Несколько модулей: правда о стыках лежит в одном месте
Сервер, клиент, командная строка, агент на рабочих станциях. Одно изменение в протоколе задевает всех. Агент, который правит сервер, должен знать контракт и найти, кто ещё его использует. Если документация каждого модуля живёт в своём репозитории, агент в соседнем её даже не видит, а правда о стыке размазана по чатам и личным заметкам.
Каркас «продукт → модуль → глава»
Режим «Компоненты» задаёт постоянную структуру: у каждого модуля папки «Для людей» и «Техническая», внутри технической: архитектура, справочник, эксплуатация, решения, изменения. Агент пишет в свой модуль по умолчанию: он назначается в профиле полем «Документы пишет в». Модулю можно дать до пяти других названий, чтобы backend находил «Server».
Контракты в одном разделе
Контракт между частями продукта лежит в разделе «Контракты» этого продукта, один на продукт: маршруты API, протоколы, схемы. Модули ссылаются на него, а не держат по копии. Статья на стыке живёт там, где выполняется действие, а из второго модуля на неё ведёт ссылка.
Правила для агентов в одном месте
«Описание правил для агентов» в настройках: куда писать, где чья ответственность, что считать технической документацией. Агенты читают его первой командой cct docs structure, поэтому новый агент в проекте ведёт себя так же, как опытный.
Поиск по всем модулям сразу
Запрос по идентификатору находит контракт и всех, кто его использует, в любом модуле. В примере ниже agent-signal найден в контрактах API, в документации cct и в документации программы, и нужный документ стоит первым.
Ссылки, которые не ломаются
Адрес документа отделён от названия: модуль или статью переименовали, ссылки из других модулей продолжают работать. Внутренние связи хранятся по идентификатору, а не по тексту пути.
Одна тема, одно название, одна фраза о сути
Правила записи: одна статья на одну тему, уникальное название, краткое описание в одно предложение, тип статьи определяет раздел. Проверка при записи ловит битые ссылки и пропущенный раздел «See also». Поэтому результат поиска читается без открытия документа.
Только изменения
cct docs changed отдаёт изменения с прошлой контрольной точки. Агент, вернувшийся к задаче через неделю, перечитывает только то, что изменилось, а не всю базу.
Одна база для всех машин
Агент на Linux‑сервере читает ту же документацию через cct, что и локальный. Документация принадлежит команде, а не репозиторию, и модуль на сервере видит контракты модуля на вашем компьютере.
Server-1 ❯ cct docs structure
Structure: components
Put documents into the component that owns the behavior; other components link to it. Technical = developers and agents: exact names, contracts, failure modes and code paths.
Server-1 ❯ cct docs find "agent-signal" --limit 4
Контракты (API)/HTTP API v1/Служебные маршруты: healthz, whoami, agent-signal
cct/Техническая/Справочник/Команды (CLI)/Служебные команды: whoami, names, profile, version…
Программа/Техническая/Справочник/API и контракты/HTTP API программы
cct/Техническая/Справочник/Данные/Локальные файлы cct
Server-1 ❯ cct docs read "documents/ai-terminal/contracts/http-api-v1/service.md" --headings
## Маршруты · ## Проверка доступности: GET /healthz · ## Личность токена: GET /v1/whoami · ## Сигнал агента: POST /v1/agent-signal · ## Файл cct для Linux …
Server-1 ❯ cct docs read "documents/ai-terminal/contracts/http-api-v1/service.md" --section "#сигнал-агента-post-v1agent-signal"
… 26 строк контракта: кто вызывает, что передаёт, какие ответы …
Как это устроено
Дерево разделов
Разделы и документы любой вложенности. Для крупных проектов режим «Компоненты»: продукт → модуль → глава, с папками «Для людей» и «Техническая». Правила для агентов, куда и что писать, задаются один раз в настройках, и агенты читают их первыми.
Редактор, в котором видно документ
Режим «Markdown» с живым предпросмотром и «Визуальный» с панелью форматирования. Таблицы, списки, врезки выглядят как документ, а не как разметка. Локальный черновик сохраняется на случай сбоя, и после перезапуска программа предложит его восстановить.
Версии, которые нельзя подделать
Каждое сохранение становится неизменяемой версией. История, сравнение с текущей и «Вернуть эту версию…». Если документ изменил кто‑то другой, пока вы правили, конфликт показывается явно, а не затирается.
Поиск, который понимает язык
Запрос резервн копи находит «резервной копии» и «резервные копии». Окончания русских и английских слов, начало слова, фраза в кавычках, идентификаторы вроде docs_unavailable. Результаты появляются при наборе, с подсветкой, путём по разделам и фильтрами по статусу и типу.
Доступ агентов к документу
По умолчанию агенты читают и изменяют всё. Для отдельного документа владелец задаёт «Читает и изменяет», «Только читает» или «Нет доступа», для всех агентов или по профилям. Агент без доступа документ не видит вовсе; агент без права записи получает понятный отказ.
Чтение слоями для агента
cct docs tree --summaries показывает темы с описаниями, cct docs find ищет по индексу, cct docs read --headings даёт оглавление, --section читает один раздел. Статью целиком агент открывает только тогда, когда она действительно нужна, и это записано в его встроенном гиде.
Агенты пишут документацию по ходу работы
cct docs write и cct docs update с проверкой версии. Встроенная проверка статьи ловит битые ссылки и отсутствующий раздел «See also». Черновики агентов живут в отдельных папках «Notes» и не смешиваются с документацией.
Защита и экспорт
Детектор секретов не даст записать токен в текст. Удаляет документы только владелец, с отменой в течение 10 секунд. Экспорт: «Копировать для ИИ», «Копировать Markdown», «Сохранить как HTML».
Как это выглядит для агента
Backend ❯ cct docs find "резервн копи" --in documents/project/server
Сервер/Техническая/Эксплуатация/Резервная копия и восстановление базы v3 published
summary: Как сделать копию базы вместе с WAL и восстановить её при закрытой программе.
Backend ❯ cct docs read "documents/project/server/technical/operations/backup-restore.md" --headings
## Что копировать · ## Автоматические копии · ## Восстановление · ## See also
Backend ❯ cct docs read "documents/project/server/technical/operations/backup-restore.md" --section "#восстановление"
… только нужный раздел, 40 строк вместо всего репозитория …Что это даёт
- Агент находит нужное, а не первое попавшееся. Поиск по индексу с морфологией и чтение по разделам вместо grep по сотне файлов.
- Контекст и токены уходят на работу, а не на чтение. Килобайты на поиск вместо мегабайтов на загрузку документации, и так на каждый вопрос агента.
- Вы видите документ как документ. Таблицы, списки, врезки, история версий, всё в окне программы.
- Документация пишется по ходу работы. Агент закрыл задачу и дописал главу; вы проверили глазами и опубликовали.
- Знания не утекают и не теряются. Права по документам, детектор секретов, версии, которые нельзя стереть.
В сравнении с обычным терминалом
| Ситуация | Папка docs/ | Модуль «Документы» |
|---|---|---|
| Агенту нужна одна глава | Читает несколько файлов целиком, тысячи токенов на каждый | Поиск по индексу и три команды до нужного раздела: около 9 КБ |
| Несколько модулей | В каждом репозитории своя папка docs/, агент видит только свою | Одна база на все модули, контракты в одном разделе, поиск по всем модулям сразу |
| ИИ дописывает документацию | Ещё один файл в корне, рядом с шестью похожими | Статья в своём модуле и разделе по типу, одна тема, уникальное название, проверка ссылок |
| Поиск по‑русски | grep по точной форме слова | Окончания, начало слова, фразы, идентификаторы; нужный документ первым |
| Кто и что менял | git blame, если файл в репозитории | История версий с автором и сравнением |
| Секрет в тексте | Уехал в репозиторий | Запись отклонена детектором |