19 KiB
Truthmark
Ваши агенты пишут код. Truthmark поддерживает понятную людям документацию, которую можно проверять в Git.
Truthmark устанавливает нативные для Git рабочие процессы, с помощью которых AI-агенты разработки создают новую продуктовую и инженерную документацию на основе существующего кода и тестов, актуализируют её после каждого изменения кода и предоставляют вам обычные Markdown-диффы для проверки.
Начать работу · Сайт · Руководство пользователя · GitHub
Читайте этот README на 16 языках
🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇹 Italiano | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇬🇷 Ελληνικά
Создайте первые документы. Поддерживайте их достоверность.
Большинство инструментов документирования останавливаются после генерации. Truthmark предоставляет агентам полный жизненный цикл документации прямо в вашем репозитории:
- Создавайте новую документацию на основе работающего ПО. Truth Document анализирует код и тесты, а затем создаёт ограниченную по области продуктовую или инженерную документацию.
- Автоматически поддерживайте соответствие документации. Truth Sync запускается при передаче работы агентом после функциональных изменений кода и обновляет достоверные сведения репозитория до завершения задачи.
- Превращайте документацию обратно в код. Truth Realize реализует утверждённые truth-документы, сохраняя чистый подход от документации к коду.
- Восстанавливайте владение по мере роста кодовой базы. Truth Structure создаёт ограниченные маршруты и начальные документы для новых или перегруженных областей.
- Проверяйте всё в Git. Код, решения, контракты, архитектура, эксплуатация и поведение перемещаются вместе с веткой.
Никаких размещённых в облаке баз знаний. Никакой закрытой памяти агентов. Никакой документации, запертой в истории чатов.
Быстрый старт: создайте свой первый truth-документ
Требования: Node.js 24 или новее, Git-репозиторий и поддерживаемый AI-хост разработки для агентских рабочих процессов.
Выполните следующие команды в репозитории, которым должен управлять Truthmark:
cd /path/to/your-repo
npm install -g truthmark
truthmark init
truthmark init позволяет выбрать Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor или нейтральную к хосту настройку интерфейса командной строки.
Теперь попросите настроенного агента задокументировать одно реальное поведение:
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
Truth Document создаёт новый ограниченный по области truth-документ, если его ещё нет, обновляет существующий документ-владелец, если он есть, и при необходимости обновляет маршрутизацию. Функциональный код при этом не изменяется.
Проверьте результат:
truthmark check
git status --short --untracked-files=all
git diff
Теперь у вас должны появиться:
docs/truthmark/engineering/behaviors/session-timeout.md
docs/truthmark/routes/areas/authentication.md
Точные пути определяются структурой владения вашего репозитория. Новые файлы отображаются в git status, а изменения отслеживаемых файлов — в git diff.
Способ запуска зависит от хоста. OpenCode использует /skill truthmark-document, Antigravity — @truthmark-document, а другие поддерживаемые хосты используют свои нативные интерфейсы навыков или slash-команд. Точные команды приведены в таблице платформ.
Для скриптов и непрерывной интеграции передавайте выбранные платформы явно:
truthmark init --platform codex --platform cursor
truthmark init --json
Выберите none в интерактивном режиме или выполните truthmark init --clear-platforms, чтобы репозиторий оставался нейтральным к хосту. Платформы агентов можно добавить позже, повторно запустив truthmark init.
Для диагностики актуальности относительно ветки передайте базовую ссылку Git:
truthmark check --base <base-ref>
Как работает Truthmark
Интерфейс командной строки Truthmark устанавливает и проверяет контракт репозитория. Ваш агент разработки анализирует доказательства и работает с документацией через установленные нативные для хоста рабочие процессы.
Обычное изменение кода проходит по простому циклу:
- Агент изменяет функциональный код.
- Запускаются соответствующие тесты.
- Truth Sync проверяет связанную документацию.
- Если достоверные сведения репозитория изменились, агент создаёт или обновляет документацию и маршрутизацию.
- Вы вместе проверяете дифф кода и дифф достоверной документации.
Рабочие процессы
| Рабочий процесс | Когда использовать | Результат |
|---|---|---|
| Truth Document | Существующему коду нужна документация | Создаёт или обновляет продуктовую и инженерную документацию, основанную на доказательствах |
| Truth Sync | Изменился функциональный код | До передачи работы синхронизирует связанную документацию и маршрутизацию |
| Truth Structure | Новой области нужен владелец или существующая документация стала слишком широкой | Создаёт ограниченные маршруты и каркасы начальных документов |
| Truth Realize | Утверждённый truth-документ должен стать работающим ПО | Обновляет функциональный код на основе документации |
| Truth Check | Достоверность репозитория нужно проверить | Сообщает о проблемах маршрутизации, владения, доказательств и документации |
| Truthmark Portal | Команде нужен удобный для просмотра сайт документации | Создаёт версионируемое статическое HTML-представление на основе truth-документов Markdown |
Truthmark устанавливает эти рабочие процессы как нативные поверхности репозитория для Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor.
Что вы получаете
Документация, основанная на реальности
Truthmark умеет создавать документацию о возможностях продукта, поведении реализации, программных интерфейсах приложений, архитектуре, рабочих процессах, эксплуатации и тестах. Код и тесты дают доказательства, а ограниченные по области документы Markdown сохраняют результат.
Документация, которая переживает следующее изменение
Маршруты связывают области кода с канонической документацией. Когда агенты меняют поведение, Truth Sync знает, где должны находиться соответствующие достоверные сведения, и сохраняет результат удобным для проверки.
Продуктовая и инженерная истина в отдельных потоках
Продуктовая истина фиксирует обещания пользователям, границы, решения и критерии приёмки. Инженерная истина фиксирует текущее поведение, контракты, архитектуру, рабочие процессы, эксплуатацию и поведение тестов.
Нативная для Git совместная работа
Всё важное находится в версионируемых файлах репозитория. Истина следует за веткой, работает с обычными pull request и остаётся видимой каждому сопровождающему и агенту разработки.
Локальная работа прежде всего
Truthmark не нужны размещённый сервис, фоновый процесс, база данных, векторное хранилище или сервер Model Context Protocol. Репозиторий содержит собственный рабочий процесс документирования.
Где уместен Truthmark
| Потребность | Лучшее решение |
|---|---|
| Более качественный результат одной сессии агента | Улучшенный промпт |
| Непрерывность на личном уровне или уровне сессии | Инструмент памяти |
| Разработка функций, начинающаяся с плана | Рабочий процесс спецификаций |
| Документация в рамках ветки, которая перемещается вместе с кодом | Truthmark |
| Корректность поведения | Тесты и проверка кода |
| Проверяемая документация, созданная с помощью ИИ | Truthmark + проверка в Git |
Truthmark создан для сопровождающих и инженерных команд, которые уже используют AI-агентов разработки и хотят, чтобы репозиторий продолжал говорить правду так же быстро, как меняется код.
Поддерживаемые хосты и командная строка
Поддерживаемые хосты агентов:
- Codex
- Claude Code
- GitHub Copilot
- OpenCode
- Antigravity
- Cursor
Справочник командной строки
| Команда | Назначение |
|---|---|
truthmark init |
Создаёт или обновляет конфигурацию, маршрутизацию, шаблоны и рабочие процессы выбранных хостов |
truthmark check [--base <ref>] |
Проверяет достоверность репозитория и при необходимости запускает диагностику актуальности ветки |
truthmark index --json |
Показывает производные метаданные репозитория и маршрутизации |
truthmark impact --base <ref> --json |
Сопоставляет изменённые файлы с документацией, владельцами и ближайшими тестами |
truthmark workflow status --workflow <id> [--base <ref>] --json |
Показывает применимость и цели рабочего процесса |
truthmark validate ... |
Проверяет отчёты рабочих процессов и разрешения на запись |
truthmark uninstall --dry-run / truthmark uninstall --apply |
Предварительно показывает или удаляет созданные поверхности хостов, сохраняя авторскую truth-документацию |
Структурированный вывод JSON доступен во всём интерфейсе командной строки для скриптов и непрерывной интеграции.
Дополнительные материалы
- Руководство пользователя Truthmark
- Индекс документации
- Обзор архитектуры
- Контракты конфигурации, маршрутизации и команд
- Поддержание достоверности репозитория
- Участие в разработке
Установите Truthmark, выберите хост разработки и уже сегодня превратите реальное поведение в документацию.
Лицензия
MIT. См. LICENSE.