truthmark/docs/readmes/README.pt.md

Truthmark

Seus agentes escrevem código. O Truthmark mantém a documentação voltada para pessoas e revisável no Git.

O Truthmark instala fluxos de trabalho nativos do Git que permitem que agentes de programação com IA criem nova documentação de produto e engenharia a partir de código e testes existentes, mantenham-na atualizada após cada mudança de código e entreguem diffs comuns de Markdown para sua revisão.

Comece agora · Site · Guia do usuário · GitHub

Leia este README em 16 idiomas

🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇹 Italiano | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇬🇷 Ελληνικά

Crie os primeiros documentos. Mantenha-os verdadeiros.

A maioria das ferramentas de documentação para depois da geração. O Truthmark oferece aos agentes um ciclo de vida completo da documentação dentro do seu repositório:

• Crie novos documentos a partir de software funcional. O Truth Document lê código e testes e, em seguida, cria documentação delimitada de produto ou engenharia.
• Mantenha os documentos alinhados automaticamente. O Truth Sync é executado na entrega do agente após mudanças funcionais no código e atualiza a verdade do repositório antes que o trabalho seja concluído.
• Transforme documentos de volta em código. O Truth Realize implementa documentos de verdade aprovados e preserva um fluxo de trabalho limpo que começa pela documentação.
• Repare a propriedade conforme a base de código cresce. O Truth Structure cria rotas delimitadas e documentos iniciais para áreas novas ou sobrecarregadas.
• Revise tudo no Git. Código, decisões, contratos, arquitetura, operações e comportamento viajam juntos com a branch.

Sem base de conhecimento hospedada. Sem memória privada de agentes. Sem documentação presa no histórico de chats.

Início rápido: crie seu primeiro documento de verdade

Requisitos: Node.js 24 ou mais recente, um repositório Git e um host de programação com IA compatível com fluxos de trabalho de agentes.

Execute isto dentro do repositório que você quer que o Truthmark gerencie:

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

truthmark init permite selecionar Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor ou uma configuração de interface de linha de comando neutra em relação ao host.

Agora peça ao agente configurado que documente um comportamento real:

/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts

O Truth Document cria um novo documento de verdade delimitado quando nenhum existe, atualiza o proprietário existente quando ele já existe e atualiza o roteamento quando necessário. Ele não altera o código funcional.

Revise o resultado:

truthmark check
git status --short --untracked-files=all
git diff

Agora você deve ter:

docs/truthmark/engineering/behaviors/session-timeout.md
docs/truthmark/routes/areas/authentication.md

Os caminhos exatos seguem a estrutura de propriedade do seu repositório. Novos arquivos aparecem em git status; mudanças em arquivos rastreados aparecem em git diff.

A forma de invocação varia conforme o host. O OpenCode usa /skill truthmark-document, o Antigravity usa @truthmark-document e os outros hosts compatíveis usam sua superfície nativa de skills ou comandos com barra. Consulte a tabela de plataformas para ver os comandos exatos.

Para scripts e integração contínua, informe explicitamente as plataformas selecionadas:

truthmark init --platform codex --platform cursor
truthmark init --json

Escolha none interativamente ou execute truthmark init --clear-platforms para ter um repositório neutro em relação ao host. Você pode adicionar plataformas de agentes mais tarde executando truthmark init novamente.

Para diagnósticos de atualidade relativos à branch, informe uma base do Git:

truthmark check --base <base-ref>

Como o Truthmark funciona

A interface de linha de comando do Truthmark instala e valida o contrato do repositório. Seu agente de programação realiza a revisão de evidências e o trabalho de documentação por meio dos fluxos de trabalho nativos do host que foram instalados.

Uma mudança normal de código segue um ciclo simples:

1. O agente altera o código funcional.
2. Os testes relevantes são executados.
3. O Truth Sync verifica a documentação mapeada.
4. O agente cria ou atualiza documentos e roteamento quando a verdade do repositório muda.
5. Você revisa o diff de código e o diff de verdade juntos.

Fluxos de trabalho

Fluxo de trabalho	Quando usar	Resultado
Truth Document	O código existente precisa de documentação	Cria ou atualiza documentação de produto e engenharia respaldada por evidências
Truth Sync	O código funcional mudou	Mantém os documentos mapeados e o roteamento alinhados antes da entrega
Truth Structure	Uma área nova precisa de propriedade ou os documentos existentes são abrangentes demais	Cria rotas delimitadas e documentos iniciais básicos
Truth Realize	Um documento de verdade aprovado deve se tornar software funcional	Atualiza o código funcional a partir da documentação
Truth Check	A verdade do repositório precisa de uma auditoria	Relata problemas de roteamento, propriedade, evidências e documentação
Truthmark Portal	A equipe quer um site de documentação navegável	Gera uma apresentação HTML estática e versionada a partir de documentos de verdade em Markdown

O Truthmark instala esses fluxos de trabalho como superfícies nativas do repositório para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor.

O que você recebe

Documentação que parte da realidade

O Truthmark pode criar documentação de recursos do produto, comportamento da implementação, interfaces de programação de aplicações, arquitetura, fluxos de trabalho, operações e testes. Código e testes fornecem as evidências; documentos Markdown delimitados preservam o resultado.

Documentação que resiste à próxima mudança

As rotas conectam áreas de código a documentos canônicos. Quando agentes alteram o comportamento, o Truth Sync sabe onde a verdade correspondente deve ficar e mantém a entrega pronta para revisão.

Verdade de produto e engenharia em faixas separadas

A verdade de produto registra promessas voltadas ao usuário, limites, decisões e critérios de aceitação. A verdade de engenharia registra o comportamento atual, contratos, arquitetura, fluxos de trabalho, operações e comportamento dos testes.

Colaboração nativa do Git

Tudo que importa vive em arquivos versionados do repositório. A verdade acompanha a branch, funciona com pull requests comuns e permanece visível para cada mantenedor e agente de programação.

Operação local-first

O Truthmark não precisa de serviço hospedado, daemon, banco de dados, banco vetorial ou servidor do Model Context Protocol. O repositório carrega seu próprio fluxo de trabalho de documentação.

Onde o Truthmark se encaixa

Necessidade	Melhor opção
Melhor resultado de uma sessão de agente	Um prompt melhor
Continuidade pessoal ou no nível da sessão	Uma ferramenta de memória
Desenvolvimento de recursos que começa por um plano	Um fluxo de trabalho de especificação
Documentação no escopo da branch que viaja com o código	Truthmark
Correção do comportamento	Testes e revisão de código
Documentação assistida por IA e revisável	Truthmark + revisão no Git

O Truthmark foi criado para mantenedores e equipes de engenharia que já usam agentes de programação com IA e querem que o repositório continue dizendo a verdade na mesma velocidade em que o código muda.

Hosts compatíveis e linha de comando

Hosts de agentes compatíveis:

• Codex
• Claude Code
• GitHub Copilot
• OpenCode
• Antigravity
• Cursor

Referência da linha de comando

Comando	Finalidade
truthmark init	Cria ou atualiza a configuração, o roteamento, os templates e os fluxos de trabalho dos hosts selecionados
truthmark check [--base <ref>]	Valida a verdade do repositório e, opcionalmente, executa diagnósticos de atualidade da branch
truthmark index --json	Inspeciona metadados derivados do repositório e do roteamento
truthmark impact --base <ref> --json	Mapeia arquivos alterados para documentos, proprietários e testes próximos
truthmark workflow status --workflow <id> [--base <ref>] --json	Inspeciona a aplicabilidade e os alvos do fluxo de trabalho
truthmark validate ...	Valida relatórios de fluxos de trabalho e concessões de escrita
truthmark uninstall --dry-run / truthmark uninstall --apply	Visualiza ou remove superfícies de host geradas, preservando a verdade criada

A saída JSON estruturada está disponível em toda a interface de linha de comando para scripts e integração contínua.

Saiba mais

• Guia do usuário do Truthmark
• Índice da documentação
• Visão geral da arquitetura
• Contratos de configuração, roteamento e comandos
• Manutenção da verdade do repositório
• Como contribuir

Instale o Truthmark, selecione seu host de programação e transforme hoje um comportamento real em documentação.

Licença

MIT. Consulte LICENSE.