Jarvis MCP: Documentação Inteligente com IA e a Migração para o docs.teorema.inf.br

## Visão Geral

A Teorema está migrando sua documentação técnica da plataforma **Assetway** para o **docs.teorema.inf.br** — uma plataforma que não serve apenas para guardar e buscar documentos, mas que é a base de conhecimento de um assistente de Inteligência Artificial (IA), o **Jarvis**. O objetivo é transformar o conhecimento espalhado da empresa em respostas rápidas e fundamentadas para o time técnico, usando o nosso próprio acervo de documentação como fonte. Este documento reúne os conceitos da iniciativa (Markdown, frontmatter, RAG, MCP), o que muda na rotina das equipes e os próximos passos do projeto (chamado 0000568337).

> **Nota:** Este é um documento de referência da iniciativa, mantido como exemplo dos padrões editoriais que adotamos no docs.teorema.inf.br. Ele não descreve a operação de um sistema, e sim o contexto e os conceitos por trás da plataforma de documentação inteligente.

## Ficha

- **Público:** Time técnico da Teorema — Suporte, Desenvolvimento e Qualidade
- **Quando usar:** para entender o que é a iniciativa Jarvis MCP, por que a documentação migrou da Assetway e como cada área contribui para a base de conhecimento

## Investir em IA como ferramenta de trabalho

A Teorema fez uma aposta concreta em Inteligência Artificial (IA), refletida no orçamento e não só no discurso. Hoje o time conta com **20 acessos ao Claude Team**, dos quais **3 são contas Premium** (com limites de uso maiores, para quem usa IA de forma mais intensa no dia a dia).

Por que esse investimento importa para o time técnico:

- **É a mesma ferramenta usada para construir o Jarvis.** Não é uma tecnologia distante: é a IA disponível na mão de cada pessoa para acelerar tarefas reais — entender um código legado, redigir uma documentação, revisar uma query, resumir um chamado.
- **Investir em IA é investir na produtividade de cada pessoa.** O acesso não é um benefício simbólico; é uma ferramenta de trabalho, como uma boa IDE ou um bom monitor.
- O **Claude** (da Anthropic) é a IA escolhida por combinar qualidade de resposta, capacidade de seguir instruções e bom encaixe com a forma como a Teorema integra IA aos seus sistemas (ver Model Context Protocol, mais adiante).

> 💡 **Dica:** quem ainda não usa o acesso ao Claude no dia a dia está deixando produtividade na mesa. Vale incorporar a IA ao fluxo de trabalho desde o início de cada tarefa.

## Adotar a postura "AI First"

"AI First" é uma postura de trabalho, não uma ferramenta específica. Significa que, diante de uma tarefa, a primeira pergunta passa a ser *"como a IA pode ajudar aqui desde o começo?"* — em vez de fazer tudo no modo antigo e recorrer à IA apenas quando o trabalho empaca. A iniciativa Jarvis MCP é a tradução prática dessa postura em três frentes:

| Frente | O que muda na rotina |
|---|---|
| **Pensar com IA** | A IA participa desde o início da tarefa (planejar, investigar, levantar hipóteses), não só no fim para "revisar". |
| **Documentar com IA** | O conhecimento é registrado de forma estruturada e pesquisável — e a própria IA ajuda a escrever e organizar essa documentação. |
| **Atender com IA** | Dúvidas técnicas do dia a dia passam a ter resposta rápida, baseada no que já foi documentado. |

A postura AI First já havia sido apresentada ao time técnico em **outubro de 2025**. Naquele momento era a ideia; a iniciativa Jarvis MCP é o passo seguinte — transformar o conceito em uma ferramenta concreta de trabalho (o Jarvis somado ao docs.teorema.inf.br). Não se trata de começar do zero nem de mudar de direção, e sim de dar sequência a um plano que já vinha sendo comunicado.

## Entender Markdown e Frontmatter

A documentação do docs.teorema.inf.br é escrita em **Markdown**, com um bloco de metadados chamado **frontmatter** no topo de cada arquivo. Alinhar esses dois termos é pré-requisito para entender como a plataforma funciona.

### Markdown — a linguagem da documentação

Markdown é uma forma simples de escrever **texto formatado** usando poucos símbolos, sem depender do Word. Em vez de clicar em botões de negrito e título, a formatação é marcada diretamente no texto:

```markdown
# Título
## Subtítulo

Um parágrafo normal com uma palavra em **negrito** e outra em *itálico*.

- item de lista
- outro item

`um trecho de código`
```

A Teorema adotou Markdown porque ele é:

- **Leve e universal** — abre em qualquer editor, é só texto puro.
- **Padronizado** — todo mundo escreve do mesmo jeito, o que facilita ler e manter.
- **Fácil de versionar e buscar** — por ser texto, funciona bem com controle de versão, com ferramentas de busca e com IA.

### Frontmatter — a ficha técnica do documento

O frontmatter é um pequeno bloco no **topo do arquivo** com **metadados** sobre ele — dados que descrevem o documento, separados do conteúdo. Fica entre duas linhas de três traços (`---`):

```markdown
---
título: Rotina de Backup
sistema: Iris
tags: [infra, backup]
autor: Equipe de Infra
---

# Rotina de Backup
(conteúdo do documento começa aqui...)
```

O frontmatter serve para dois fins:

- **Organização** — permite agrupar, filtrar e relacionar documentos (por sistema, por tag, por autor).
- **Contexto para a IA** — esses metadados ajudam a IA a entender do que o documento trata e a encontrar o documento certo na hora de responder uma dúvida.

O frontmatter prepara o terreno para o **RAG**, o mecanismo que a IA usa para localizar a informação, explicado a seguir.

## Entender RAG e MCP

Dois conceitos de IA tornam o Jarvis possível: o **RAG** (como a IA encontra o conhecimento) e o **MCP** (como a IA se conecta aos sistemas).

### RAG — Retrieval-Augmented Generation

RAG significa **Retrieval-Augmented Generation** ("geração aumentada por recuperação"). É uma técnica em que a IA, antes de responder, **primeiro busca** a informação na base de documentação e **só depois** gera a resposta com base no que encontrou:

```
Pergunta do usuário
      │
      ▼
[1] BUSCA na documentação  →  encontra os trechos relevantes
      │
      ▼
[2] GERA a resposta usando esses trechos como base
      │
      ▼
Resposta fundamentada (com fonte no nosso conteúdo)
```

O RAG é importante porque:

- As respostas ficam **fundamentadas no conhecimento real da Teorema**, não em "achismo" nem em conhecimento genérico da internet.
- Reduz drasticamente o risco de a IA "inventar" (alucinar), porque ela fica amarrada ao que está documentado.
- Quanto **melhor e mais completa** a documentação, **melhores** as respostas — o que liga diretamente ao princípio de que "documentar é munição".

### MCP — Model Context Protocol

MCP significa **Model Context Protocol** — um **padrão** que conecta a IA aos sistemas, dados e ferramentas da empresa. A analogia é a de uma **"tomada universal"** que permite à IA **agir além do chat**: em vez de só conversar, ela pode consultar um banco de dados, abrir um chamado, ler um documento ou executar uma ação.

- Sem MCP, a IA é uma boa conversadora, porém isolada.
- Com MCP, a IA se pluga nas ferramentas da Teorema e passa a trabalhar **com os nossos dados**, de forma padronizada e segura.

A combinação **RAG** (para achar conhecimento) **+ MCP** (para se conectar aos sistemas) é a base técnica que torna o Jarvis possível.

## Conhecer o Jarvis

O **Jarvis** é o assistente de IA da Teorema — a iniciativa que une RAG e MCP a serviço do time. Na prática, o Jarvis acessa a documentação, entende o contexto da pergunta e responde dúvidas técnicas, conectado via MCP aos sistemas internos. É o "rosto" de toda a estratégia: o ponto onde o investimento em IA, a documentação em Markdown, o RAG e o MCP se encontram e viram utilidade concreta.

### Por que o nome "Jarvis"

O nome é uma homenagem bem-humorada à cultura geek. **J.A.R.V.I.S.** é a famosa IA do universo Marvel: o assistente virtual do **Homem de Ferro** (Tony Stark), que controla a mansão, as armaduras e ajuda nos negócios. Na ficção, o nome é o acrônimo para **"Just A Rather Very Intelligent System"** ("apenas um sistema muito inteligente") e, por sua vez, uma homenagem a **Edwin Jarvis**, o leal mordomo da família Stark nos quadrinhos. A escolha carrega a intenção: um assistente sempre disponível, que conhece a "casa" (os sistemas e a documentação da Teorema) e ajuda o time a trabalhar melhor.

## Acessar o docs.teorema.inf.br

O **docs.teorema.inf.br** é o destino da migração: o que sai da Assetway passa a viver aqui. A mudança, porém, não é só de endereço — é de capacidade. A plataforma soma duas funções:

| Não é apenas… | …é também |
|---|---|
| **Buscar documentação** | **Tirar dúvidas com IA** |
| Localizar manuais, procedimentos e histórico técnico em um só lugar, organizado e atualizado. | Um **RAG**: o usuário pergunta em linguagem natural e recebe a resposta baseada na própria documentação da Teorema. |

Ou seja: além de ser o lugar onde a documentação mora (busca tradicional), o docs.teorema.inf.br é a base de conhecimento que alimenta o Jarvis. A mesma plataforma serve tanto para **consultar** quanto para **perguntar**.

## Consultar um exemplo real no catálogo

Um exemplo real de chamado documentado pode ser consultado no catálogo de chamadas, que mostra como o conhecimento fica registrado e disponível para reuso:

🔗 [Exemplo de chamado documentado no catálogo](https://catalogo.teorema.inf.br/chamadas/57098EA0-8B59-4C23-BE4E-355A2D46AF59)

Esse exemplo ilustra o resultado esperado da iniciativa: cada solução de chamado registrada de forma estruturada vira conteúdo pesquisável, tanto por pessoas quanto pelo Jarvis.

## Documentar é munição

Toda a tecnologia da iniciativa (RAG, Jarvis) só funciona se houver **documentação boa para alimentá-la**, e a melhor fonte dessa documentação é o próprio time, no dia a dia. Cada chamado resolvido guarda uma solução que, registrada, vira conhecimento reaproveitável.

| # | Ideia | Detalhe |
|---|---|---|
| 1 | **Todo chamado é aprendizado** | Cada problema resolvido no suporte carrega uma solução que vale ouro para o time. |
| 2 | **Resuma e registre** | Documentar e resumir o chamado transforma a solução em algo que qualquer pessoa pode consultar depois. |
| 3 | **Munição para o desenvolvimento** | O time de desenvolvimento usa esse histórico para resolver mais rápido, evitar retrabalho e prevenir falhas. |

> **Nota:** sem registro, todo problema é resolvido do zero. Documentar não é burocracia: é o que alimenta o Jarvis e dá agilidade a todo o time. O tempo investido em escrever um bom resumo de chamado não é tempo perdido — é munição que volta multiplicada, tanto para colegas quanto para a IA.

## Entender o ciclo virtuoso da documentação

A documentação cria um ciclo que se retroalimenta entre as áreas: o que cada equipe escreve vira insumo para as demais, em todas as direções — não só "para frente".

```
            ┌──────────────────┐
            │     SUPORTE       │
            │ Registra chamados │
            │   e soluções      │
            └───────┬───┬───────┘
              ▲     │   │     ▲
              │     ▼   ▼     │
   ┌──────────┴────┐   ┌──────┴────────────┐
   │  QUALIDADE /  │◄─►│  DESENVOLVIMENTO   │
   │   S2 NÍVEL    │   │ Corrige e documenta│
   │ Padroniza e   │   │     melhorias      │
   │  cria guias   │   └────────────────────┘
   └───────────────┘
```

- **Suporte** registra chamados e soluções.
- **Desenvolvimento** corrige e documenta melhorias.
- **Qualidade / S2 Nível** padroniza, valida e cria guias de boas práticas.

O conhecimento flui **nos dois sentidos** entre cada par de áreas: o que o Suporte escreve serve ao Desenvolvimento e à Qualidade; o que o Desenvolvimento documenta volta para o Suporte; o que a Qualidade padroniza orienta os dois. Quanto mais cada área documenta, mais forte fica a base que todos — e o Jarvis — consultam.

## Roadmap da iniciativa

Os próximos passos planejados para a iniciativa Jarvis MCP:

1. **Ampliar a documentação** — levar mais sistemas e processos para o docs.teorema.inf.br, enriquecendo a base de conhecimento. Quanto mais conteúdo de qualidade, melhores as respostas do RAG.
2. **Unificar o dicas.teorema.inf.br** — trazer todo o conteúdo do dicas.teorema.inf.br para dentro do docs.teorema.inf.br, centralizando tudo em uma única fonte de verdade, em vez de conhecimento espalhado por várias plataformas.
3. **Balão do Jarvis nas telas** — inserir um balão de chat com o Jarvis respondendo dúvidas diretamente onde o time trabalha, sem precisar trocar de ferramenta.
4. **Integrar os sistemas** — conectar o Jarvis (via MCP) aos sistemas internos, para respostas com dados reais e até ações — o passo que tira a IA do "só conversar" e a coloca para agir.

## Informações do documento

> Autor: Gustavo
> Setor: Suporte
> Módulo: Jarvis MCP
> Chamado: 0000568337
> Versão do Sistema:
> Aprovado em: