Docs › Introdução

Desenvolvimento com IA/Agents

O OonCore distribui documentação canônica versionada em .ooncore/ para que Codex, Claude, ChatGPT, Kimi, Manus e outros Agents codifiquem dentro dos contratos.

O OonCore foi desenhado para desenvolvimento assistido. A fonte de verdade operacional para Agents fica dentro do pacote @oondemand/create-central-oon e é copiada para cada App, sempre na versão instalada.

O cache .ooncore/

npm run ooncore:docs        # sincroniza .ooncore/ com a versão instalada
npm run ooncore:docs:check  # valida versão e hashes
  • .ooncore/AGENTS.md é a entrada canônica: roteia qualquer Agent para os contratos da versão instalada.
  • .ooncore/TASK_INDEX.md organiza a documentação por intenção ("quero cadastrar e listar", "quero gerar PDF"…).
  • .ooncore/context.generated.md é uma compilação opcional para consulta — não uma leitura obrigatória.
  • O manifesto documental guarda hash de cada arquivo; docs check acusa qualquer edição manual.

Guias distribuídos

Guia Quando usar
AGENTS.md, OON_APP_AGENT_GUIDE.md, AGENT_WORKFLOW.md Entrada e roteiro curto
TASK_INDEX.md, TASK_EXAMPLES.md Encontrar a API certa por tarefa
PUBLIC_CONTRACTS.md, BACKEND_API.md, FRONTEND_API.md Assinaturas públicas
BACKEND_DOMAIN_MANIFEST.md, BACKEND_PROCESS_MANIFEST.md Domínio e processo declarativos
FRONTEND_CODE_FIRST.md, ADVANCED_UX_PATTERNS.md, DETAIL_MODAL_AND_RELATED_GRIDS.md Experiência
RBAC_SECURITY.md, AUTH_ACTIVATION_RBAC.md, USERS_AND_ACCESS.md Segurança e acesso
CAPABILITIES.md, TRANSACTIONAL_EMAIL.md, PDF_RENDERING.md, SECRETS.md Capabilities
CORE_UPGRADE.md, APP_PACKAGING.md, TROUBLESHOOTING.md, ERRORS.md Operação

Roteiro recomendado para um Agent

  1. Gerar a base oficial — nunca copiar outro App.
  2. Escolher a jornada e consultar somente a linha correspondente do TASK_INDEX.md.
  3. Implementar domínio e experiência pelos contratos públicos, preservando permissões, contexto e segredos.
  4. Validar com npm run check, build do frontend e testes relevantes; provar a jornada pela UI/API.
  5. Publicar pelo fluxo existente e registrar commit e evidência em Dev.

Regras para Agents

  • Use somente exports públicos; fontes internas e outros Apps não substituem contratos.
  • Se faltar contrato, registre a lacuna com versão, tarefa e informação ausente. Continue as partes independentes e suspenda apenas a operação que não pode ser implementada com segurança. Não invente APIs.
  • Preserve autenticação, autorização de backend, contexto autorizado, isolamento, auditoria e proteção de segredos. POC reduz escopo funcional, não proteção.
  • Plataforma homologada: consuma identidade, acesso, tenancy, licenciamento e delivery; não reimplemente.
  • Entregue uma jornada utilizável com página, navegação, endpoint e permissão. O perfil admin pode validar a POC.
  • Relate separadamente implementação, build, publicação e homologação — são estados distintos.

Exemplo de instrução para seu Agent

# Minha Central

- Leia `.ooncore/AGENTS.md` antes de alterar o código.
- Domínio: central de compras (fornecedores, pedidos, aprovações).
- Use admin para validar a POC; mantenha permissões no backend.
- Antes do PR: `npm run check` e `npm run build --prefix frontend`.