Base de Conhecimento para Agentes de IA

Esta base foi projetada para leitura eficiente por agentes e humanos.

Arquitetura recomendada

• index.json: catalogo central para busca semantica rapida por agente.
• records/: um registro por arquivo Markdown, com metadados em front matter YAML.
• schemas/: contrato JSON Schema para validar metadados e manter consistencia.

Por que esse formato e eficiente

• JSON para roteamento: agentes localizam o registro certo sem ler toda a base.
• Markdown para contexto: explica causa, impacto e procedimento com baixa ambiguidade.
• Metadados padronizados: permite filtro por tags, severity, domain e status.
• Versionamento simples: cada incidente vira um arquivo independente e auditavel no Git.

Convencao de registros

• ID: KB-<DOMINIO>-NNN (ex.: KB-INFRA-001)
• Nome de arquivo: <ID>-<slug>.md
• Campos obrigatorios de metadados:
  • id
  • title
  • domain
  • tags
  • status
  • severity
  • created_at
  • updated_at
  • applies_to

Fluxo de atualizacao

1. Criar novo registro em records/<dominio>/.
2. Atualizar index.json com resumo e caminho.
3. Validar aderencia ao schema em schemas/.
4. Referenciar o registro em documentacao operacional quando necessario.

Validacao automatica

Use:

make kb-check
make kb-fix

A verificacao valida:

• metadados obrigatorios conforme schema;
• padrao de ID de registro;
• sincronizacao entre index.json e arquivos em records/.

make kb-fix faz ajustes automaticos no index.json:

• inclui registros faltantes;
• remove entradas orfas;
• sincroniza campos principais;
• atualiza last_updated.