truthmark/README.ru.md

Truthmark

Truthmark устанавливает рабочие процессы истины репозитория для разработки ПО с ИИ.

English | Deutsch | 中文 | Español | Русский

ИИ-агенты уже быстро пишут код. Дорогая часть — удерживать истину репозитория в соответствии с тем, что реально изменилось.

Truthmark добавляет в этот процесс финальную защиту на уровне рабочего процесса. Обычный путь прост:

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

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

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

Это важно, потому что процесс живет вместе с веткой. После инициализации репозитория правила, маршрутизация и установленные рабочие поверхности путешествуют внутри репозитория, поэтому совместная работа и передача задач меньше зависят от локальной настройки одного человека.

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

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

Возможности Что устанавливает Truthmark и как устроена рабочая поверхность.	Позиционирование Где Truthmark находится относительно промптов, памяти и spec-first процессов.
Поток sync Как Truth Sync закрывает обычные изменения кода перед передачей работы.

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

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

• Установленный Truth Sync после изменений кода превращает поддержку документации в защиту рабочего процесса, а не в командную привычку.
• Истина, ограниченная веткой, движется вместе с кодом, поэтому ревьюеры могут проверять актуальную истину в обычных 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 превращает истину репозитория в явную рабочую поверхность для агентов:

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

Главное обещание такое: контекст агента становится зафиксированным состоянием репозитория, а не приватным артефактом отдельной сессии.

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

Установите Truthmark в репозитории, который хотите инициализировать:

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

Если вы хотите попробовать еще не выпущенные изменения из исходного checkout:

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
docs/truthmark/areas.md
docs/truthmark/areas/repository.md
docs/templates/behavior-doc.md
docs/truth/README.md
docs/truth/repository/README.md
docs/truth/repository/overview.md
AGENTS.md
CLAUDE.md
GEMINI.md

Поддерживаемые платформы: codex, opencode, claude-code, github-copilot и gemini-cli. Конфигурация по умолчанию включает их все; удалите из .truthmark/config.yml платформы, которыми не пользуетесь, перед повторным запуском truthmark init. Стандартная шаблонная структура использует truth-README.md как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например docs/truth/repository/overview.md.

Существующим репозиториям обычно нужен один этап очистки после init: запустите установленный рабочий процесс Truth Structure, если созданный маршрут repository слишком широкий, владение охватывает несколько продуктов или сервисов, либо файлы маршрутов все еще указывают на документы-заглушки. Truth Structure разделяет широкие маршруты, создает или исправляет начальные канонические документы истины и дает Truth Sync точные цели до начала работы с функциональным кодом. Codex, Claude Code и поддерживаемые IDE Copilot могут вызвать его через /truthmark-structure; хосты в стиле OpenCode могут использовать /skill truthmark-structure.

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

Сильная сторона Truthmark — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте.

Существующее поведение без документации

Используйте это, когда реализация уже есть, но канонические документы истины отсутствуют или слабы:

пользователь определяет реализованное поведение или api-эндпоинт
пользователь явно вызывает truth document
агент читает реализацию, тесты, маршрутизацию и существующие docs
агент пишет только truth docs и маршрутизацию
проверить diff truth docs

Truth Document — это ручной процесс с приоритетом реализации: код служит доказательством, документы истины создаются или исправляются, и функциональный код менять нельзя. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через /truthmark-document; хосты в стиле OpenCode могут использовать /skill truthmark-document.

/truthmark-document документирует реализованное поведение session timeout в docs/truth/authentication

Обычные изменения кода

Большинству пользователей не нужно напрямую вызывать Truth Sync. Главное, что установленный агентский процесс рассматривает Truth Sync как финальную защиту, когда менялся функциональный код. Нормальный путь выглядит так:

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

Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача - выполняться через установленный агентский процесс как финальная защита, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.

Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через /truthmark-sync. Хосты в стиле OpenCode могут использовать /skill truthmark-sync.

/truthmark-sync синхронизируй истину репозитория прямо сейчас перед передачей

Doc-first изменения

Используйте этот путь, когда продуктовое или архитектурное решение начинается в документации:

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

Truth Realize — это ручной doc-first процесс: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.

Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через /truthmark-realize. Хосты в стиле OpenCode могут использовать /skill truthmark-realize.

/truthmark-realize реализуй docs/truth/authentication/session-timeout.md в код

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

Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После truthmark init сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека.

Truthmark устанавливает два разных интерфейса:

• CLI-команды для людей, которые запускают люди или CI, чтобы настроить репозиторий, обновить установленные файлы, проверить артефакты истины и при необходимости создать производный контекст для ревью

• агентские рабочие поверхности, которые вызывают coding agents или агентские хосты во время реализации; это не дополнительные ежедневные терминальные команды для людей

• .truthmark/config.yml для машиночитаемого зафиксированного контракта иерархии

• docs/truthmark/areas.md для корневого индекса маршрутов

• docs/truthmark/areas/**/*.md для делегированных дочерних файлов маршрутов

• docs/templates/behavior-doc.md и другие шаблоны по видам под docs/templates/ для редактируемых стандартов truth docs, используемых сгенерированными рабочими процессами

• управляемые блоки инструкций для настроенных платформ, таких как AGENTS.md, CLAUDE.md, инструкции Copilot и GEMINI.md

• нативные для хоста skills, prompts или commands для Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check

• проектные проверяющие агенты Codex, Claude Code, GitHub Copilot и OpenCode в режиме только чтения, а также leased-агенты truth-doc-writer там, где хост поддерживает агентов, под .codex/agents/, .claude/agents/, .github/agents/ и .opencode/agents/ для аудитов, которыми владеет рабочий процесс, и для документных шардов, выданных родительским агентом

Установленные рабочие поверхности и есть среда выполнения:

• Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
• Truth Document создает или исправляет документы истины для уже реализованного поведения.
• Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
• Truth Preview предварительно показывает вероятную маршрутизацию рабочего процесса до правок без записи файлов.
• Truth Realize обновляет код так, чтобы он соответствовал документам истины.
• Truth Check аудитирует здоровье истины репозитория.

README.md функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения. Сгенерированные рабочие поверхности сохраняют приоритет правил репозитория, рассматривая код реализации и канонические документы истины как свидетельства текущего поведения.

Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через truthmark init.

Команды

Truthmark V1 держит терминальный CLI сфокусированным. Большинству людей нужны только настройка, обновление и проверка:

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

Остальные CLI-команды - необязательные помощники репозиторной аналитики. Они создают производный контекст для ревью активного checkout; они не являются источниками истины:

Необязательная CLI-команда	Назначение
truthmark index	Строит JSON RepoIndex и RouteMap для активного checkout.
truthmark impact --base <ref>	Сопоставляет измененные файлы с routed truth docs, owning routes, nearby tests и public symbols.
truthmark context --workflow <workflow> [--base <ref>]	Генерирует ограниченный ContextPack для Truth Sync, Truth Document или Truth Realize. --format markdown рендерит его в читаемый человеком вид.

Все CLI-команды выше поддерживают --json, когда структурированный вывод полезен для автоматизации.

Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.

Они запускаются через настроенные поверхности хоста агента, например Codex/Claude/Copilot /truthmark-*, OpenCode /skill truthmark-* или Gemini /truthmark:*.

Эти вызовы выглядят как команды, потому что агентские хосты предоставляют skills через slash-команды. Относитесь к ним как к инструкциям для агента, а не как к терминальным командам, которые должен запускать человек.

/truthmark-check проверь маршрутизацию и покрытие truth перед review

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

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

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

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

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

V1 сейчас предоставляет:

• truthmark config
• truthmark init
• truthmark check
• truthmark index
• truthmark impact
• truthmark context
• управляемые инструкции рабочих процессов в AGENTS.md
• сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check для настроенных агентских хостов
• метаданные области ветки
• диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
• производные артефакты RepoIndex, RouteMap, ImpactSet и ContextPack для более быстрой локальной проверки, когда CLI доступен

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

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

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

Текущее поведение должно жить в каноническом дереве документации выше.

Не-цели

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

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

Это легкий способ заставить локальных ИИ-агентов для разработки уважать истину, которую ваша команда хранит в Git.

Лицензия

MIT. См. LICENSE.