Pular para o conteúdo
Voltar ao portfólio

InDocs: documentação operada por agente

  • React
  • TypeScript
  • Convex
  • Keycloak
  • Markdown
  • Claude Code

Meu papel

Construí sozinho o backend, o frontend e a skill de terminal; a única etapa externa foi o QA.

A documentação da InBot vivia em arquivos markdown num repositório: só quem mexia em git conseguia escrever, e não havia rascunho nem histórico de quem mudou o quê. O InDocs leva esse conteúdo para o Convex e abre a escrita para os times, sem perder o controle do que vai ao ar.

Duas áreas: documentação pública aberta e área interna atrás do login corporativo.
Editor web: markdown com prévia ao lado, tags, imagens e seções reordenáveis.
Rascunho e publicação seletiva: a página nasce rascunho, e o "Publicar alterações" escolhe o que vai ao ar; o site serve só o retrato publicado.
Explorador da API: cada endpoint com parâmetros, resposta esperada e código de exemplo pronto para testar.
Auditoria: cada ação grava autor, horário e o antes e depois do conteúdo.
Operado por agente: a skill /indocs responde perguntas olhando primeiro as tags, cria e edita docs sempre como rascunho, publica só com confirmação, diz quem mudou cada página e transforma a exportação de uma jornada de bot em documentação.

Sistema interno da InBot: o código é proprietário. A área pública está no ar em docs.inbot.com.br; os prints da área interna usam conteúdo fictício.

Antes

Documentação em arquivos markdown no git: corrigir uma vírgula exigia PR, quem não era dev não escrevia e ia ao ar tudo o que estivesse na branch, pronto ou não.

O problema

A documentação era um conjunto de arquivos markdown versionados em git. Para corrigir uma vírgula era preciso abrir PR, quem não era dev não escrevia, e o que ia ao ar era sempre tudo o que estivesse na branch, pronto ou não.

Também não havia como responder, sem garimpar commits, quem tinha alterado uma página e quando.

A solução

Migrei o acervo para o Convex, com seções, páginas, tags e imagens, e criei um editor web atrás do login corporativo, com a permissão de editar lida ao vivo da role no token. Cada página guarda o rascunho e, à parte, o retrato do que está no ar; o build do site serve só esse retrato, então editar não muda o site até alguém publicar.

Toda mutation grava a auditoria com o antes e o depois. Por cima disso, criei a skill /indocs, que faz o mesmo pelo terminal: consulta, escreve como rascunho e publica com confirmação.

Decisões e trade-offs

Rascunho separado do retrato publicado: editar não muda o site até alguém publicar. Auditoria com o antes e o depois em toda mutation. A mesma operação disponível pelo terminal, com a skill /indocs, para quem prefere pedir ao Claude Code.

Os resultados

Times que não mexem em git passaram a documentar direto no navegador ou conversando com o Claude Code. A publicação virou uma decisão explícita, com histórico de autor e conteúdo, e a documentação pública continua no ar em docs.inbot.com.br.

Resultados em números

  • 304consultas de agentes à documentação via skill
  • /indocsOperação por agente
  • 37Commits
  • 35Arquivos de teste
  • Pública + internaÁreas