truthmark/README.ru.md

# Truthmark

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

[English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский

<img src="docs/assets/truthmark-banner.png" alt="Баннер Truthmark" width="100%" />

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

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

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

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

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

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

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

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

<table>
	<tr>
		<td align="center" width="50%">
			<img src="docs/assets/truthmark-features.png" alt="Возможности Truthmark" width="100%" />
			<br><strong>Возможности</strong><br>
			Что устанавливает Truthmark и как устроена рабочая поверхность.
		</td>
		<td align="center" width="50%">
			<img src="docs/assets/truthmark-position.png" alt="Позиционирование Truthmark" width="100%" />
			<br><strong>Позиционирование</strong><br>
			Где Truthmark находится относительно промптов, памяти и spec-first процессов.
		</td>
	</tr>
	<tr>
		<td align="center" colspan="2">
			<img src="docs/assets/truthmark-syncflow.png" alt="Поток sync в Truthmark" width="100%" />
			<br><strong>Поток sync</strong><br>
			Как Truth Sync закрывает обычные изменения кода перед передачей работы.
		</td>
	</tr>
</table>

## Почему команды выбирают 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)
- [Начало работы](#начало-работы)
- [Как он работает](#как-он-работает)
- [Что он устанавливает](#что-он-устанавливает)
- [Команды](#команды)
- [Зачем он существует](#зачем-он-существует)
- [Статус проекта](#статус-проекта)
- [Документация](#документация)
- [Не-цели](#не-цели)
- [Лицензия](#лицензия)

## Что решает Truthmark

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

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

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

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

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

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

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

```bash
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` проверьте сгенерированную рабочую поверхность и файлы маршрутов, чтобы маршрутизированная документация действительно совпадала с документами, которые отвечают за ваш код:

```text
.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 — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте.

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

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

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

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

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

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

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

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

- `.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 Realize и Truth Check

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

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

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

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

## Команды

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

```bash
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 Document, 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 Document, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
- метаданные области ветки
- диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия

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

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

- [Индекс документации](docs/README.md)
- [Обзор архитектуры](docs/architecture/overview.md)
- [Контракты API и CLI](docs/truth/contracts.md)
- [Поведение init и scaffold](docs/truth/init-and-scaffold.md)
- [Диагностика check](docs/truth/check-diagnostics.md)
- [Установленные workflow](docs/truth/workflows/overview.md)
- [Руководство по поддержанию истины репозитория](docs/standards/maintaining-repository-truth.md)

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

## Не-цели

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

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

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

## Лицензия

MIT. См. [LICENSE](LICENSE).