Base de conhecimento
Os agentes de IA são tão bons quanto o contexto que você fornece. A base de conhecimento é onde você armazena decisões de arquitetura, especificações de API e conhecimento de domínio que os agentes consultam durante a implementação. Sem esse contexto documentado, os agentes adivinham. Com ele, tomam decisões informadas com base na sua realidade.
A base de conhecimento do Almirant é um sistema de documentação integrado no qual sua equipe pode criar, organizar e buscar documentos em formato Markdown. Os documentos são agrupados em categorias hierárquicas, vinculados a projetos e work items, e servem como contexto adicional para a IA.
O que é um documento
Um documento é uma página de conteúdo escrita em Markdown. Pode ser uma especificação técnica, um guia de processos, notas de reunião, decisões de arquitetura ou qualquer conhecimento que sua equipe precise compartilhar e consultar.
Cada documento pertence a uma categoria e pode ser vinculado a um ou mais projetos.
Criar um documento
Clique em Novo documento na seção de documentos. Preencha os campos:
| Campo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|
| Título | Sim | Nome descritivo do documento | "Guia de implantação em produção" |
| Conteúdo | Não | Corpo do documento em Markdown | Texto com formatação, listas, tabelas etc. |
| Categoria | Não | Categoria dentro da árvore hierárquica | "Guias técnicos > Infraestrutura" |
| Projeto | Não | Projeto ao qual o documento é vinculado | "App Mobile v2" |
Editor Markdown
O editor oferece suporte à sintaxe Markdown completa:
- Cabeçalhos (
#,##,###) - Listas ordenadas e não ordenadas
- Tabelas
- Blocos de código com destaque de sintaxe
- Negrito, itálico e outra formatação inline
- Links e imagens
Na parte inferior do editor, há um contador de palavras para fornecer uma referência do tamanho do documento.
Categorias hierárquicas
Os documentos são organizados em uma árvore de categorias com profundidade ilimitada. Isso permite criar estruturas tão detalhadas quanto você precisar:
Documentação
├── Guias técnicos
│ ├── Infraestrutura
│ ├── Banco de dados
│ └── APIs
├── Processos
│ ├── Onboarding
│ └── Release management
├── Decisões de arquitetura
└── Notas de reunião
├── Sprint reviews
└── Planejamento
Criar uma categoria
- Na árvore lateral de documentos, clique em Nova categoria
- Informe o nome da categoria
- Opcionalmente, selecione uma categoria pai para criar subcategorias
Navegação pela árvore
A barra lateral esquerda da seção de documentos mostra a árvore completa de categorias. Clique em uma categoria para ver os documentos que ela contém. As categorias com subcategorias podem ser expandidas e recolhidas.
Busca de texto completo
A busca de documentos permite encontrar conteúdo por texto completo. Ela busca tanto no título quanto no corpo do documento e retorna resultados ordenados por relevância.
Digite sua consulta na barra de busca da seção de documentos para filtrar a lista em tempo real.
Vinculação com work items
Os documentos podem ser vinculados bidirecionalmente a work items. Isso é útil para:
- Associar uma especificação técnica à story que a implementa
- Vincular uma decisão de arquitetura ao epic que a originou
- Conectar notas de reunião às tarefas que surgiram delas
Vincular a partir do documento
Nos detalhes do documento, procure a seção de Work items vinculados e adicione os work items que deseja associar.
Vincular a partir do work item
Nos detalhes de um work item, você pode vincular documentos existentes na seção correspondente.
A vinculação é bidirecional: se você vincular um documento a um work item, também verá a referência ao documento a partir do work item.
Fixação (pinning)
Você pode fixar documentos importantes para que apareçam em destaque no topo da lista. Isso é útil para documentos de referência frequente, como guias de estilo, processos críticos ou documentos de onboarding.
Para fixar um documento, use o ícone de pin na lista ou nos detalhes do documento.
Agrupamento entre projetos
Os documentos podem ser vinculados a vários projetos, o que permite criar documentação transversal aplicável a diversas equipes ou iniciativas. Um documento de "Padrões de código" pode ser vinculado a todos os projetos de desenvolvimento, por exemplo.
Histórico de versões
O Almirant salva automaticamente versões anteriores de cada documento. Cada vez que você salva alterações, uma nova versão é criada e armazenada no S3. Você pode:
- Ver o histórico de versões de um documento
- Consultar o conteúdo de versões anteriores
- Identificar quando e quais alterações foram feitas
Contexto para IA
Os documentos da base de conhecimento podem servir como contexto adicional para os agentes de IA conectados via MCP. Quando um agente precisa entender uma especificação, um processo ou uma decisão de arquitetura, ele pode consultar os documentos relevantes do projeto.
Isso é especialmente útil quando você combina documentos com work items: a IA pode ler a especificação técnica vinculada a um work item antes de implementá-lo.
Os documentos estão disponíveis via MCP:
| Tool | Descrição |
|---|---|
list_documents | Lista documentos com filtros por projeto e categoria |
list_document_categories | Lista as categorias hierárquicas disponíveis |
Os documentos acessíveis via MCP permitem que um agente de IA consulte a base de conhecimento da equipe para tomar decisões mais informadas durante a implementação. Por exemplo, antes de implementar um work item, o agente pode buscar especificações técnicas ou decisões de arquitetura relevantes.
Relacionado: Projetos | Work Items