13 KiB
Truthmark
Twoi agenci piszą kod. Truthmark dba o dokumentację dla ludzi, gotową do przeglądu w Git.
Truthmark instaluje natywne dla Git przepływy pracy, dzięki którym agenci programistyczni AI tworzą nową dokumentację produktu i inżynierii na podstawie istniejącego kodu i testów, aktualizują ją po każdej zmianie kodu oraz przekazują Ci zwykłe diffy Markdown do przeglądu.
Zacznij · Strona internetowa · Przewodnik użytkownika · GitHub
Przeczytaj ten plik README w jednym z 16 języków
🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇹 Italiano | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇬🇷 Ελληνικά
Twórz dokumentację od podstaw. Dbaj, by pozostawała prawdziwa.
Większość narzędzi do dokumentacji kończy pracę po jej wygenerowaniu. Truthmark zapewnia agentom pełny cykl życia dokumentacji wewnątrz repozytorium:
- Twórz nową dokumentację na podstawie działającego oprogramowania. Truth Document odczytuje kod i testy, a następnie tworzy precyzyjnie ograniczoną dokumentację produktu lub inżynierii.
- Automatycznie utrzymuj zgodność dokumentacji. Truth Sync uruchamia się przy przekazaniu pracy przez agenta po zmianach kodu funkcjonalnego i aktualizuje prawdę repozytorium przed zakończeniem zadania.
- Zamieniaj dokumentację z powrotem w kod. Truth Realize implementuje zatwierdzone dokumenty truth, zachowując przejrzysty przepływ pracy doc-first.
- Naprawiaj własność wraz z rozwojem bazy kodu. Truth Structure tworzy precyzyjne trasy i dokumenty startowe dla nowych lub przeciążonych obszarów.
- Przeglądaj wszystko w Git. Kod, decyzje, kontrakty, architektura, operacje i zachowanie podążają razem z gałęzią.
Bez hostowanej bazy wiedzy. Bez prywatnej pamięci agenta. Bez dokumentacji uwięzionej w historii czatu.
Szybki start: utwórz swój pierwszy dokument truth
Wymagania: Node.js 24 lub nowszy, repozytorium Git oraz obsługiwany host programistyczny AI do przepływów pracy agentów.
Uruchom poniższe polecenia w repozytorium, którym ma zarządzać Truthmark:
cd /path/to/your-repo
npm install -g truthmark
truthmark init
truthmark init pozwala wybrać Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor albo konfigurację interfejsu wiersza poleceń niezależną od hosta.
Teraz poproś skonfigurowanego agenta o udokumentowanie jednego rzeczywistego zachowania:
/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts
Truth Document tworzy nowy, precyzyjnie ograniczony dokument truth, jeśli taki jeszcze nie istnieje, aktualizuje istniejącego właściciela, gdy już istnieje, i w razie potrzeby aktualizuje routing. Nie zmienia kodu funkcjonalnego.
Przejrzyj rezultat:
truthmark check
git status --short --untracked-files=all
git diff
Powinny teraz istnieć:
docs/truthmark/engineering/behaviors/session-timeout.md
docs/truthmark/routes/areas/authentication.md
Dokładne ścieżki wynikają ze struktury własności w Twoim repozytorium. Nowe pliki pojawiają się w git status, a zmiany w śledzonych plikach — w git diff.
Sposób wywołania zależy od hosta. OpenCode używa /skill truthmark-document, Antigravity używa @truthmark-document, a pozostałe obsługiwane hosty korzystają ze swoich natywnych umiejętności lub poleceń z ukośnikiem. Dokładne polecenia znajdziesz w tabeli platform.
W skryptach i ciągłej integracji jawnie przekaż wybrane platformy:
truthmark init --platform codex --platform cursor
truthmark init --json
Wybierz interaktywnie none albo uruchom truthmark init --clear-platforms, aby uzyskać repozytorium niezależne od hosta. Platformy agentów możesz dodać później, ponownie uruchamiając truthmark init.
Aby uzyskać diagnostykę aktualności względem gałęzi, przekaż bazę Git:
truthmark check --base <base-ref>
Jak działa Truthmark
Interfejs wiersza poleceń Truthmark instaluje i sprawdza kontrakt repozytorium. Twój agent programistyczny analizuje dowody i wykonuje pracę dokumentacyjną za pomocą zainstalowanych, natywnych dla hosta przepływów pracy.
Typowa zmiana kodu przebiega w jednej prostej pętli:
- Agent zmienia kod funkcjonalny.
- Uruchamiane są odpowiednie testy.
- Truth Sync sprawdza zmapowaną dokumentację.
- Gdy prawda repozytorium się zmieniła, agent tworzy lub aktualizuje dokumentację oraz routing.
- Wspólnie przeglądasz diff kodu i diff dokumentów truth.
Przepływy pracy
| Przepływ pracy | Kiedy go używać | Rezultat |
|---|---|---|
| Truth Document | Istniejący kod wymaga dokumentacji | Tworzy lub aktualizuje opartą na dowodach dokumentację produktu i inżynierii |
| Truth Sync | Zmienił się kod funkcjonalny | Przed przekazaniem pracy utrzymuje zgodność zmapowanej dokumentacji i routingu |
| Truth Structure | Nowy obszar potrzebuje właściciela albo istniejąca dokumentacja jest zbyt szeroka | Tworzy precyzyjne trasy i szkieletowe dokumenty startowe |
| Truth Realize | Zatwierdzony dokument truth powinien stać się działającym oprogramowaniem | Aktualizuje kod funkcjonalny na podstawie dokumentacji |
| Truth Check | Prawda repozytorium wymaga audytu | Zgłasza problemy z routingiem, własnością, dowodami i dokumentacją |
| Truthmark Portal | Zespół potrzebuje witryny z dokumentacją do wygodnego przeglądania | Generuje zatwierdzoną statyczną prezentację HTML z dokumentów truth w Markdown |
Truthmark instaluje te przepływy pracy jako natywne powierzchnie repozytorium dla Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor.
Co otrzymujesz
Dokumentację, która zaczyna od rzeczywistości
Truthmark potrafi tworzyć dokumentację możliwości produktu, zachowania implementacji, interfejsów programistycznych aplikacji, architektury, przepływów pracy, operacji i testów. Kod i testy dostarczają dowodów, a precyzyjnie ograniczone dokumenty Markdown utrwalają wynik.
Dokumentację, która przetrwa kolejną zmianę
Trasy łączą obszary kodu z kanonicznymi dokumentami. Kiedy agenci zmieniają zachowanie, Truth Sync wie, gdzie należy zapisać odpowiadającą mu prawdę, i utrzymuje przekazanie pracy w formie gotowej do przeglądu.
Prawdę produktu i inżynierii w osobnych obszarach
Prawda produktu obejmuje obietnice dla użytkowników, granice, decyzje i kryteria akceptacji. Prawda inżynierii obejmuje bieżące zachowanie, kontrakty, architekturę, przepływy pracy, operacje oraz zachowanie testów.
Współpracę natywną dla Git
Wszystko, co ważne, znajduje się w zatwierdzonych plikach repozytorium. Prawda podąża za gałęzią, współpracuje ze zwykłymi pull requestami i pozostaje widoczna dla każdego opiekuna oraz agenta programistycznego.
Działanie local-first
Truthmark nie potrzebuje hostowanej usługi, demona, bazy danych, magazynu wektorowego ani serwera Model Context Protocol. Repozytorium zawiera własny przepływ pracy dokumentacyjnej.
Gdzie pasuje Truthmark
| Potrzeba | Najlepsze rozwiązanie |
|---|---|
| Lepszy wynik z jednej sesji agenta | Lepszy prompt |
| Ciągłość osobista lub na poziomie sesji | Narzędzie pamięci |
| Praca nad funkcją rozpoczynana od planu | Przepływ pracy specyfikacji |
| Dokumentacja w zakresie gałęzi, która podąża za kodem | Truthmark |
| Poprawność zachowania | Testy i przegląd kodu |
| Dokumentacja wspierana przez AI i gotowa do przeglądu | Truthmark + przegląd w Git |
Truthmark powstał dla opiekunów i zespołów inżynierskich, które już korzystają z agentów programistycznych AI i chcą, aby repozytorium nadążało z prawdą za każdą zmianą kodu.
Obsługiwane hosty i wiersz poleceń
Obsługiwane hosty agentów:
- Codex
- Claude Code
- GitHub Copilot
- OpenCode
- Antigravity
- Cursor
Dokumentacja wiersza poleceń
| Polecenie | Zastosowanie |
|---|---|
truthmark init |
Tworzy lub odświeża konfigurację, routing, szablony i przepływy pracy wybranych hostów |
truthmark check [--base <ref>] |
Sprawdza prawdę repozytorium i opcjonalnie uruchamia diagnostykę aktualności gałęzi |
truthmark index --json |
Wyświetla pochodne metadane repozytorium i routingu |
truthmark impact --base <ref> --json |
Mapuje zmienione pliki na dokumentację, właścicieli i pobliskie testy |
truthmark workflow status --workflow <id> [--base <ref>] --json |
Wyświetla zastosowanie przepływu pracy i jego cele |
truthmark validate ... |
Sprawdza raporty przepływów pracy i dzierżawy zapisu |
truthmark uninstall --dry-run|--apply |
Wyświetla podgląd lub usuwa wygenerowane powierzchnie hosta, zachowując utworzone dokumenty truth |
Strukturyzowane dane wyjściowe JSON są dostępne w całym interfejsie wiersza poleceń na potrzeby skryptów i ciągłej integracji.
Dowiedz się więcej
- Przewodnik użytkownika Truthmark
- Indeks dokumentacji
- Przegląd architektury
- Kontrakty konfiguracji, routingu i poleceń
- Utrzymywanie prawdy repozytorium
- Współtworzenie
Zainstaluj Truthmark, wybierz host programistyczny i już dziś zamień jedno rzeczywiste zachowanie w dokumentację.
Licencja
MIT. Zobacz LICENSE.