# Truthmark **Ваши агенты пишут код. Truthmark поддерживает понятную людям документацию, которую можно проверять в Git.** Truthmark устанавливает нативные для Git рабочие процессы, с помощью которых AI-агенты разработки создают новую продуктовую и инженерную документацию на основе существующего кода и тестов, актуализируют её после каждого изменения кода и предоставляют вам обычные Markdown-диффы для проверки. [![версия npm](https://img.shields.io/npm/v/truthmark?color=cb3837&label=npm)](https://www.npmjs.com/package/truthmark) [![CI](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml) [![Лицензия: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE) [![Node.js >=24](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](../../package.json) [Начать работу](#быстрый-старт-создайте-свой-первый-truth-документ) · [Сайт](https://merlinhu1.github.io/truthmark/) · [Руководство пользователя](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) · [GitHub](https://github.com/merlinhu1/truthmark)
Читайте этот README на 16 языках [🇺🇸 English](../../README.md) | [🇨🇳 简体中文](README.zh.md) | [🇯🇵 日本語](README.ja.md) | [🇰🇷 한국어](README.ko.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇪🇸 Español](README.es.md) | [🇧🇷 Português](README.pt.md) | [🇷🇺 Русский](README.ru.md) | [🇸🇦 العربية](README.ar.md) | [🇮🇹 Italiano](README.it.md) | [🇵🇱 Polski](README.pl.md) | [🇹🇷 Türkçe](README.tr.md) | [🇻🇳 Tiếng Việt](README.vi.md) | [🇮🇩 Bahasa Indonesia](README.id.md) | [🇬🇷 Ελληνικά](README.el.md)
## Создайте первые документы. Поддерживайте их достоверность. Большинство инструментов документирования останавливаются после генерации. Truthmark предоставляет агентам полный жизненный цикл документации прямо в вашем репозитории: - **Создавайте новую документацию на основе работающего ПО.** Truth Document анализирует код и тесты, а затем создаёт ограниченную по области продуктовую или инженерную документацию. - **Автоматически поддерживайте соответствие документации.** Truth Sync запускается при передаче работы агентом после функциональных изменений кода и обновляет достоверные сведения репозитория до завершения задачи. - **Превращайте документацию обратно в код.** Truth Realize реализует утверждённые truth-документы, сохраняя чистый подход от документации к коду. - **Восстанавливайте владение по мере роста кодовой базы.** Truth Structure создаёт ограниченные маршруты и начальные документы для новых или перегруженных областей. - **Проверяйте всё в Git.** Код, решения, контракты, архитектура, эксплуатация и поведение перемещаются вместе с веткой. Никаких размещённых в облаке баз знаний. Никакой закрытой памяти агентов. Никакой документации, запертой в истории чатов. ## Быстрый старт: создайте свой первый truth-документ **Требования:** Node.js 24 или новее, Git-репозиторий и поддерживаемый AI-хост разработки для агентских рабочих процессов. Выполните следующие команды в репозитории, которым должен управлять Truthmark: ```bash cd /path/to/your-repo npm install -g truthmark truthmark init ``` `truthmark init` позволяет выбрать Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor или нейтральную к хосту настройку интерфейса командной строки. Теперь попросите настроенного агента задокументировать одно реальное поведение: ```text /truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts ``` Truth Document создаёт новый ограниченный по области truth-документ, если его ещё нет, обновляет существующий документ-владелец, если он есть, и при необходимости обновляет маршрутизацию. Функциональный код при этом не изменяется. Проверьте результат: ```bash truthmark check git status --short --untracked-files=all git diff ``` Теперь у вас должны появиться: ```text 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-команд. Точные команды приведены в [таблице платформ](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md#supported-agent-platforms). Для скриптов и непрерывной интеграции передавайте выбранные платформы явно: ```bash truthmark init --platform codex --platform cursor truthmark init --json ``` Выберите `none` в интерактивном режиме или выполните `truthmark init --clear-platforms`, чтобы репозиторий оставался нейтральным к хосту. Платформы агентов можно добавить позже, повторно запустив `truthmark init`. Для диагностики актуальности относительно ветки передайте базовую ссылку Git: ```bash truthmark check --base ``` ## Как работает Truthmark Как работает Truthmark Интерфейс командной строки Truthmark устанавливает и проверяет контракт репозитория. Ваш агент разработки анализирует доказательства и работает с документацией через установленные нативные для хоста рабочие процессы. Обычное изменение кода проходит по простому циклу: 1. Агент изменяет функциональный код. 2. Запускаются соответствующие тесты. 3. Truth Sync проверяет связанную документацию. 4. Если достоверные сведения репозитория изменились, агент создаёт или обновляет документацию и маршрутизацию. 5. Вы вместе проверяете дифф кода и дифф достоверной документации. ## Рабочие процессы | Рабочий процесс | Когда использовать | Результат | | -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **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 ]` | Проверяет достоверность репозитория и при необходимости запускает диагностику актуальности ветки | | `truthmark index --json` | Показывает производные метаданные репозитория и маршрутизации | | `truthmark impact --base --json` | Сопоставляет изменённые файлы с документацией, владельцами и ближайшими тестами | | `truthmark workflow status --workflow [--base ] --json` | Показывает применимость и цели рабочего процесса | | `truthmark validate ...` | Проверяет отчёты рабочих процессов и разрешения на запись | | `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Предварительно показывает или удаляет созданные поверхности хостов, сохраняя авторскую truth-документацию | Структурированный вывод JSON доступен во всём интерфейсе командной строки для скриптов и непрерывной интеграции.
## Дополнительные материалы - [Руководство пользователя Truthmark](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md) - [Индекс документации](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md) - [Обзор архитектуры](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md) - [Контракты конфигурации, маршрутизации и команд](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md) - [Поддержание достоверности репозитория](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md) - [Участие в разработке](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md) **Установите Truthmark, выберите хост разработки и уже сегодня превратите реальное поведение в документацию.** ## Лицензия MIT. См. [LICENSE](../../LICENSE).