truthmark/docs/readmes/README.ru.md

Truthmark

Ваши агенты пишут код. Truthmark поддерживает понятную людям документацию, которую можно проверять в Git.

🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇹 Italiano | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇬🇷 Ελληνικά

🚀 Быстрый старт: локальный запуск за пять минут

Выполните это внутри Git-репозитория, которым должен управлять Truthmark:

cd /path/to/your-repo
npm install -g truthmark
truthmark init
truthmark check
git diff

В интерактивном терминале truthmark init показывает нумерованный множественный выбор. Выберите ноль или несколько платформ либо введите none для нейтральной к хосту настройки только с CLI.

В скриптах и CI повторяйте --platform; --json никогда не показывает запрос:

truthmark init --platform codex --platform cursor
truthmark init --json

При первом неинтерактивном запуске без --platform настройка остаётся нейтральной; последующие запуски сохраняют выбор из .truthmark/config.yml.

Теперь попробуйте самый распространенный путь внедрения: задокументируйте одно существующее поведение по коду и тестам. В вашем AI-хосте для разработки попросите установленный рабочий процесс:

/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts

После этого пользователям обычно не следует напрямую вызывать Truth Sync. Продолжайте писать код через ваш AI-хост; установленные инструкции репозитория скажут агенту запускать релевантные тесты и выполнять проверку Truth Sync перед передачей, когда меняется функциональный код. Вы просматриваете получившийся diff кода вместе с diff truth-документов.

Если нужна только CLI-валидация, выберите none и выполните truthmark check; позже можно снова выполнить truthmark init и выбрать платформы.

💡 Проблема: разрыв в AI-документации

AI-агенты разработки невероятно быстро пишут код. Но эта скорость создает новый опасный режим отказа: история репозитория начинает расходиться с реальностью.

• Поведение теряется в эфемерных историях чатов.
• Архитектурная документация быстро устаревает.
• Продуктовые решения исчезают после передачи работы.
• Ревьюерам кода приходится изучать сырые diff кода без понимания «почему».
• Каждая новая AI-сессия вынуждена заново обнаруживать truth репозитория.

🎯 Решение: Truthmark

Truthmark устанавливает в ваш репозиторий Git-native слой рабочего процесса. Он исправляет ту часть AI-разработки, которая обычно ломается: помогает документации оставаться согласованной с кодом.

Вместо надежды на то, что люди и AI-агенты вспомнят об обновлении документации, Truthmark делает документирование системной и проверяемой привычкой прямо внутри репозитория.

✨ Почему Truthmark уникален

Truthmark — не просто очередной инструмент документации. Он глубоко интегрирован в AI workflow:

• 🚫 Никакой привязки к поставщику: нет hosted-сервисов, скрытых баз данных и дополнительных серверов для эксплуатации.
• 🌳 100% Git-native: всё находится в вашем репозитории. Truth движется вместе с веткой.
• 🤝 Контракт, принадлежащий людям и выполняемый агентами: Мейнтейнеры владеют контрактом репозитория; агенты следуют установленным инструкциям во время кодинга.
• ✅ Доверие через проверку: AI-работе проще доверять, потому что работа, меняющая поведение, включает human-reviewable решение или diff в truth-doc.

🔄 Как это работает

Когда AI-агент меняет ваш код, работа еще не завершена. Truthmark устанавливает guard рабочего процесса на момент завершения, которому агенты следуют перед передачей:

1. 💻 Код: агент изменяет функциональный код.
2. 🧪 Тест: выполняются релевантные тесты.
3. 🔍 Проверка: Truthmark проверяет сопоставленную документацию как часть установленного завершающего ревью.
4. 📝 Документирование: агент обновляет docs, когда truth репозитория изменился.
5. 👀 Ревью: человек проверяет diff кода + diff truth.

🛠 Как вы взаимодействуете с Truthmark

У Truthmark есть один локальный контракт репозитория и два способа его использовать.

Люди устанавливают и проверяют контракт

Мейнтейнеры и CI используют CLI:

• truthmark init - создаёт или обновляет конфигурацию, позволяет выбрать ноль или несколько платформ и устанавливает маршруты, scaffold для truth-doc и инструкции выбранных AI-хостов.
• truthmark check - проверяет truth репозитория из терминала.

Агенты следуют контракту во время кодинга

Truthmark устанавливает локальные инструкции репозитория для поддерживаемых AI coding hosts, таких как Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor.

Обычный цикл прост:

1. Попросите агента изменить код или задокументировать существующее поведение.
2. Установленные инструкции говорят агенту, когда тестировать, когда обновлять truth docs и когда остановиться для человеческого ревью.
3. Вы ревьюите обычные Git diff: код плюс любые изменения truth-doc.

Пользовательских запросов к агенту намеренно мало:

• /truthmark-document - документирует существующее реализованное поведение по коду и тестам.
• /truthmark-realize - реализует код из существующих truth docs.
• /truthmark-check - аудитирует truth репозитория.

Truth Sync — не обычный способ начать работу; это завершающее ревью после функциональных изменений кода. Truth Structure — не повседневная команда; она исправляет routing или ownership только тогда, когда это блокирует работу.

Что вы получаете

Возможность	Что она делает
Git-native truth	Хранит truth репозитория в закоммиченных Markdown и конфигурации.
Документация в пределах ветки	Truth движется с веткой, а не живет в приватной сессии.
CLI для людей	Дает мейнтейнерам команды настройки, обновления, валидации и инспекции.
Установленные инструкции агента	Говорит coding-агентам, когда документировать, тестировать, синхронизировать truth, аудитировать или останавливаться для ревью.
Явная маршрутизация	Сопоставляет области кода с каноническими truth-docs.
Проверяемая передача	Создает обычные Git diff как для кода, так и для truth-docs.
Local-first работа	Не требует hosted-сервиса, daemon, базы данных или MCP-сервера.
Более безопасные границы записи	Разделяет code-first, doc-first, read-only и doc-only workflows.
Валидация	Сообщает о проблемах routing, authority, frontmatter, links, generated-surface, branch-scope, freshness и coverage.
Опциональный Portal	Генерирует закоммиченный статический HTML-сайт презентации из Markdown truth-docs, когда он явно включен и запрошен.

Визуальный обзор

Возможности: что устанавливает Truthmark и как агенты используют локальные инструкции репозитория.

Позиция: где Truthmark находится относительно prompts, memory и spec workflows.

Поток синхронизации: как Truth Sync завершает обычные изменения кода перед передачей.

Почему команды выбирают его

Truthmark создан для команд, которые уже знают, что AI-агенты могут генерировать код.

Следующая проблема — governance.

Не governance как церемония. Governance как простой вопрос:

После этого AI-assisted изменения репозиторий все еще говорит truth?

Truthmark помогает командам отвечать на это с помощью закоммиченных файлов, явной маршрутизации и проверяемых diff.

Он полезен, когда вам нужны:

• меньший дрейф документации
• лучшая передача работы
• branch-specific продуктовая truth
• долговечная архитектурная и API-документация
• явное владение между docs и кодом
• более безопасные границы записи для агентов
• проверяемая документация вместо скрытой memory
• инструкции для агентов, которые продолжают работать из закоммиченных файлов репозитория

Где уместен Truthmark

Truthmark не заменяет prompts, memory, specs, tests или code review.

Он дает этим workflows долговечное место для фиксации в Git.

Потребность	Лучше подходит
Лучший результат из одной сессии агента	Лучший prompt
Персональная или сессионная непрерывность	Memory tool
Plan-first работа над функцией	Spec workflow
Branch-scoped truth, которая перемещается вместе с кодом	Truthmark
Проверка корректности поведения	Tests and review
Ревью изменений документации, выполненных с AI	Truthmark плюс Git review

Область Truthmark намеренно узкая:

make repository truth explicit
route it to code
установить вокруг нее инструкции для агентов
keep the result reviewable in Git

Подробнее

README — это витрина: быстрый контекст, быстрый старт и основная ментальная модель.

Для пошагового использования команд, сравнения поверхностей, деталей поддерживаемых платформ, конфигурации, маршрутизации, Portal и примеров читайте руководство пользователя Truthmark.

Статус проекта

Текущий релиз предоставляет:

• локальные CLI-команды для init, check, index, impact и workflow status
• сгенерированные локальные инструкции агента для Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor
• диагностику route, authority, frontmatter, links, freshness, generated-surface, branch-scope и coverage
• branch-scoped truth docs и производные артефакты repository intelligence

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

• Руководство пользователя
• Индекс документации
• Обзор архитектуры
• Контракты API и CLI
• Руководство по поддержанию repository truth

Команды для локальной разработки и участия см. в CONTRIBUTING.md.

Границы дизайна

Truthmark намеренно мал: локальный, закоммиченный, scoped по ветке и проверяемый.

Это не hosted-сервис, MCP-сервер, векторная база данных, скрытый слой memory, продукт для принудительного CI-контроля или автономный движок переписывания кода. Он помогает truth репозитория оставаться видимой; он не заменяет tests, code review или человеческое суждение.

Лицензия

MIT. См. LICENSE.

Безопасное удаление

Используйте truthmark uninstall --dry-run для проверки точно сгенерированных host-поверхностей, затем truthmark uninstall --apply для их удаления. Сформированные truth, конфигурация, шаблоны, вывод Portal, файлы Gemini и несвязанные пользовательские файлы сохраняются; глобальную установку npm удаляйте отдельно через менеджер пакетов.