mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
196 lines
19 KiB
Markdown
196 lines
19 KiB
Markdown
# Truthmark
|
|
|
|
**Ваши агенты пишут код. Truthmark поддерживает понятную людям документацию, которую можно проверять в Git.**
|
|
|
|
Truthmark устанавливает нативные для Git рабочие процессы, с помощью которых AI-агенты разработки создают новую продуктовую и инженерную документацию на основе существующего кода и тестов, актуализируют её после каждого изменения кода и предоставляют вам обычные Markdown-диффы для проверки.
|
|
|
|
[](https://www.npmjs.com/package/truthmark)
|
|
[](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
|
|
[](../../LICENSE)
|
|
[](../../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)
|
|
|
|
<details>
|
|
<summary>Читайте этот README на 16 языках</summary>
|
|
|
|
[🇺🇸 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)
|
|
|
|
</details>
|
|
|
|
## Создайте первые документы. Поддерживайте их достоверность.
|
|
|
|
Большинство инструментов документирования останавливаются после генерации. 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 <base-ref>
|
|
```
|
|
|
|
## Как работает Truthmark
|
|
|
|
<picture>
|
|
<source media="(max-width: 700px)" srcset="../assets/truthmark-workflow-mobile.svg">
|
|
<img src="../assets/truthmark-workflow.svg" alt="Как работает Truthmark" width="1440">
|
|
</picture>
|
|
|
|
Интерфейс командной строки 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
|
|
|
|
<details>
|
|
<summary>Справочник командной строки</summary>
|
|
|
|
| Команда | Назначение |
|
|
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
| `truthmark init` | Создаёт или обновляет конфигурацию, маршрутизацию, шаблоны и рабочие процессы выбранных хостов |
|
|
| `truthmark check [--base <ref>]` | Проверяет достоверность репозитория и при необходимости запускает диагностику актуальности ветки |
|
|
| `truthmark index --json` | Показывает производные метаданные репозитория и маршрутизации |
|
|
| `truthmark impact --base <ref> --json` | Сопоставляет изменённые файлы с документацией, владельцами и ближайшими тестами |
|
|
| `truthmark workflow status --workflow <id> [--base <ref>] --json` | Показывает применимость и цели рабочего процесса |
|
|
| `truthmark validate ...` | Проверяет отчёты рабочих процессов и разрешения на запись |
|
|
| `truthmark uninstall --dry-run` / `truthmark uninstall --apply` | Предварительно показывает или удаляет созданные поверхности хостов, сохраняя авторскую truth-документацию |
|
|
|
|
Структурированный вывод JSON доступен во всём интерфейсе командной строки для скриптов и непрерывной интеграции.
|
|
|
|
</details>
|
|
|
|
## Дополнительные материалы
|
|
|
|
- [Руководство пользователя 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).
|