truthmark/README.ru.md

Truthmark это слой истины для разработки ПО с ИИ.

English | Deutsch | 中文 | Español | Русский ИИ-агенты для разработки уже неплохо пишут код. Но они все еще плохо восстанавливают намерения продукта, архитектурные границы и зоны ответственности в репозитории по устаревшей документации, разрозненным чатам и недолговечной памяти инструментов. Truthmark решает эту проблему: он превращает истину репозитория, локальную для ветки, в полноценную поверхность выполнения для агентов. Он устанавливает прямо в репозиторий Git-native слой истины с областью действия в пределах ветки, задает агентам явные границы маршрутизации и рабочих процессов и делает так, чтобы эта истина двигалась вместе с кодом, который действительно будет поставлен. Это не более удачная инженерия промптов. Это более управляемый способ использовать ИИ в настоящей кодовой базе: меньше повторных решений, меньше устаревшей документации, чище передача работы и сессии с ИИ, после которых остаются проверяемые инженерные записи, а не только следы в истории промптов или непрозрачном состоянии инструментов. Для команд, которые уже знают, что агенты умеют генерировать код, и теперь хотят, чтобы сам репозиторий оставался понятным, проверяемым и управляемым. Начать писать код с ИИ сейчас легко, но управлять этим дорого. Как только агенты начинают быстро писать код, истина репозитория становится поверхностью управления. Этот сбой проявляется предсказуемо: требования остаются в чатах, архитектурные решения принимаются заново, агенты трогают не те области, а ветки наследуют контекст, который ревьюеры не могут надежно проверить. Код может двигаться быстро, но репозиторию становится труднее доверять. Truthmark меняет рабочую модель:

• Истина, локальная для ветки, путешествует вместе с веткой, а не живет в приватном хранилище инструмента.
• Git делает эту истину проверяемой, сравнимой в diff и доступной всей команде.
• Документация следует за кодом, а не тихо превращается в вымысел.
• Маршрутизация остается явной в docs/truthmark/areas.md и делегированных дочерних файлах маршрутов, чтобы агенты понимали, какая документация отвечает за какой код.
• Активные продуктовые и архитектурные решения живут в канонических документах, которыми они управляют, а не в планировочных журналах с временными метками.
• Local-first рабочие процессы не требуют демона, базы данных, удаленного сервиса или MCP-зависимости.
• Модель работает в кодовых базах на JavaScript, TypeScript, Go, Python, C# и Java. Для технических лидеров ценность в управлении без показухи: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.

Где уместен Truthmark

Truthmark не пытается заменить все остальные инструменты для ИИ-процессов. Он занимает конкретный слой в стеке:

Если вам нужно	Лучший выбор
Лучшие результаты в одной сессии разработки	Более точные промпты и лучше очерченная задача
Удобная преемственность между сессиями для одного агента или оператора	Инструменты памяти
Spec-first планирование новых функций	Инструменты спецификаций, например Spec Kit
Проверяемая истина репозитория с областью действия в пределах ветки, которая идет вместе с кодом	Truthmark
Смысл не в том, что промпты, память или спецификации бесполезны. Смысл в том, что ни один из этих подходов сам по себе не превращает истину репозитория в зафиксированный в Git, проверяемый актив, который переживает передачу работы, ревью и расхождение веток.

• Что решает Truthmark
• Где уместен Truthmark
• Начало работы
• Как он работает
• Что он устанавливает
• Команды
• Зачем он существует
• Статус проекта
• Документация
• Не-цели
• Лицензия

Что решает Truthmark

Truthmark превращает истину репозитория в явную рабочую поверхность для агентов:

• TRUTHMARK.md определяет контракт рабочего процесса, локальный для ветки.
• docs/truthmark/areas.md и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
• Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
• Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
• truthmark check валидирует получившиеся артефакты истины.
• Вся модель остается local-first и Git-native. Главное обещание такое: контекст агента становится зафиксированным состоянием репозитория, а не приватным артефактом отдельной сессии.

Начало работы

Чтобы попробовать Truthmark на другом локальном репозитории до публикации пакета где-либо еще:

cd /path/to/truthmark
npm install
npm run build
cd /path/to/your-repo
node /path/to/truthmark/dist/main.js config
node /path/to/truthmark/dist/main.js init
node /path/to/truthmark/dist/main.js check

Как он работает

Проверьте .truthmark/config.yml перед init; это зафиксированный в Git контракт иерархии. После init проверьте сгенерированную рабочую поверхность и файлы маршрутов, чтобы маршрутизированная документация действительно совпадала с документами, которые отвечают за ваш код:

.truthmark/config.yml
TRUTHMARK.md
docs/truthmark/areas.md
docs/truthmark/areas/repository.md
docs/features/README.md
docs/features/repository/README.md
docs/features/repository/overview.md
AGENTS.md
CLAUDE.md
skills/truthmark-structure/SKILL.md
skills/truthmark-sync/SKILL.md
skills/truthmark-realize/SKILL.md
skills/truthmark-check/SKILL.md

Если вы включите дополнительные платформы в .truthmark/config.yml, Truthmark обновит соответствующие управляемые поверхности при следующем init. Стандартная шаблонная структура использует README.md функциональных разделов как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например docs/features/repository/overview.md. Truthmark не задает, какой именно подагент должен запускать Truth Sync. Действующий агент и среда хоста сами решают, делегировать работу или выполнить процесс на месте. Большинству пользователей не нужно вызывать Truth Sync напрямую. Нормальный путь выглядит так:

агент изменяет функциональный код
запускаются релевантные тесты
Truth Sync срабатывает до завершения работы агента
если был создан diff документов истины, он проверяется
работа коммитится или передается дальше

Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача быть автоматической финальной проверкой, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса. Пользователи Codex могут вызывать его через /truthmark-sync или $truthmark-sync. Хосты в стиле OpenCode могут использовать /skill truthmark-sync. Используйте этот путь, когда продуктовое или архитектурное решение начинается в документации:

пользователь редактирует документы истины
пользователь явно вызывает Truth Realize
агент читает документы истины и связанный код
агент обновляет только код
запускаются релевантные тесты
работа коммитится или передается дальше

Truth Realize это ручной процесс по принципу doc-first: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует. Пользователи Codex могут вызывать его через /truthmark-realize или $truthmark-realize. Хосты в стиле OpenCode могут использовать /skill truthmark-realize.

Что он устанавливает

Truthmark намеренно держит постоянную рабочую поверхность маленькой:

• .truthmark/config.yml для машиночитаемой конфигурации
• TRUTHMARK.md для контракта рабочего процесса, локального для ветки
• docs/truthmark/areas.md для корневого индекса маршрутов
• docs/truthmark/areas/**/*.md для делегированных дочерних файлов маршрутов
• управляемые блоки инструкций для настроенных платформ, таких как AGENTS.md, CLAUDE.md, правила Cursor, инструкции Copilot и GEMINI.md
• Codex- и repo-local skills для Truth Structure, Truth Sync, Truth Realize и Truth Check Установленные рабочие поверхности и есть среда выполнения:
• Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
• Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
• Truth Realize обновляет код так, чтобы он соответствовал документам истины.
• Truth Check аудитирует здоровье истины репозитория. README.md функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения. Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через truthmark init.

Команды

Truthmark V1 намеренно держит CLI небольшим. В нижестоящих репозиториях truthmark config создает зафиксированный контракт иерархии, truthmark init устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, а truthmark check валидирует артефакты истины для ручных аудитов, CI или отладки.

truthmark config
truthmark init
truthmark check
truthmark config --json
truthmark check --json

config пишет только .truthmark/config.yml, если не используется --stdout. init требует .truthmark/config.yml, а затем устанавливает или обновляет локальные файлы рабочих процессов. check валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия. Truth Structure, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.

Зачем он существует

Большинство ИИ-процессов для разработки оптимизируют следующий ответ. Truthmark оптимизирует следующую передачу работы. Он исходит из того, что серьезным командам нужны:

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

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

Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности. V1 сейчас предоставляет:

• truthmark config
• truthmark init
• truthmark check
• управляемые инструкции рабочих процессов в AGENTS.md
• сгенерированные skill-поверхности Truth Structure, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
• метаданные области ветки
• диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия Не следует считать, что пакет truthmark без scope уже опубликован.

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

Корневой README предназначен для людей, которые оценивают и пробуют пакет. Подробные функциональные и бизнес-спецификации находятся в docs/:

• Индекс документации
• Обзор архитектуры
• Контракты API и CLI
• Поведение init и scaffold
• Диагностика check
• Установленные workflow
• Руководство по поддержанию истины репозитория Текущее поведение должно жить в каноническом дереве документации выше.

Не-цели

Truthmark V1 не является:

• размещенным сервисом
• MCP-сервером
• векторной базой данных
• генератором сайтов документации
• продуктом принудительного контроля для CI или PR
• заменой тестов, code review или технического лидерства
• автономным движком для переписывания кода Это легкий способ заставить локальных ИИ-агентов для разработки уважать истину, которую ваша команда хранит в Git.

Лицензия

MIT. См. LICENSE.