53 lines
1.6 KiB
Markdown
53 lines
1.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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`.
|