First commit

specs/SPEC-016-Agent-Development-Lifecycle.md

@@ -0,0 +1,227 @@
+# SPEC-016 — Agent Development Lifecycle
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Padrão de leitura
+
+Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
+
+A estrutura usada é:
+
+1. Conceito.
+2. Problema que resolve.
+3. Quando usar.
+4. Quando não usar.
+5. Arquitetura.
+6. Implementação.
+7. Exemplos.
+8. Erros comuns.
+9. Critérios de aceite.
+
+---
+
+
+# 1. Conceito
+
+O ciclo de vida de desenvolvimento de agentes define as etapas desde a descoberta do caso de uso até a operação em produção.
+
+Ele organiza trabalho de produto, arquitetura, engenharia, segurança, avaliação e operação.
+
+# 2. Fluxo do ciclo de vida
+
+```mermaid
+flowchart LR
+    D[Discovery] --> S[Scope]
+    S --> AD[Agent Design]
+    AD --> PD[Prompt Design]
+    PD --> MD[MCP Design]
+    MD --> RD[RAG Design]
+    RD --> I[Implementation]
+    I --> T[Testing]
+    T --> E[Evaluation]
+    E --> C[Certification]
+    C --> H[Homologation]
+    H --> P[Production]
+```
+
+# 3. Etapa 1 — Discovery
+
+Objetivo:
+
+- entender problema;
+- identificar usuários;
+- mapear canais;
+- mapear sistemas;
+- mapear documentos;
+- mapear riscos.
+
+Saída:
+
+```yaml
+discovery:
+  business_problem: ""
+  users: []
+  channels: []
+  systems: []
+  documents: []
+  risks: []
+```
+
+# 4. Etapa 2 — Scope Definition
+
+Definir:
+
+- o que o agente faz;
+- o que não faz;
+- intenções;
+- ações permitidas;
+- limites;
+- critérios de sucesso.
+
+# 5. Etapa 3 — Agent Design
+
+Desenhar:
+
+- agent_id;
+- rotas;
+- intents;
+- BusinessContext;
+- tools;
+- RAG namespaces;
+- memória;
+- handoff.
+
+# 6. Etapa 4 — Prompt Design
+
+Criar:
+
+- system prompt;
+- prompt policy;
+- instruções de domínio;
+- exemplos;
+- restrições;
+- formato de resposta.
+
+# 7. Etapa 5 — MCP Design
+
+Definir:
+
+- tools;
+- parâmetros;
+- owner;
+- SLA;
+- timeout;
+- retry;
+- cache;
+- operação mutável ou idempotente.
+
+# 8. Etapa 6 — RAG Design
+
+Definir:
+
+- documentos;
+- namespace;
+- ingestão;
+- chunking;
+- embeddings;
+- atualização;
+- critérios de relevância.
+
+# 9. Etapa 7 — Implementation
+
+Implementar:
+
+- classe do agente;
+- configs;
+- prompts;
+- datasets;
+- tests;
+- observabilidade específica.
+
+# 10. Etapa 8 — Testing
+
+Testes mínimos:
+
+- unit;
+- integration;
+- contract;
+- MCP;
+- RAG;
+- guardrails;
+- judges;
+- runtime;
+- channel.
+
+# 11. Etapa 9 — Evaluation
+
+Executar:
+
+```bash
+af-evaluator run --agent-id <agent_id> --dataset <dataset>
+```
+
+Avaliar:
+
+- quality;
+- groundedness;
+- safety;
+- tool correctness;
+- route accuracy.
+
+# 12. Etapa 10 — Certification
+
+Executar:
+
+```bash
+af-certification run --agent-id <agent_id>
+```
+
+# 13. Etapa 11 — Homologation
+
+Validar com:
+
+- negócio;
+- arquitetura;
+- segurança;
+- operação;
+- integração.
+
+# 14. Etapa 12 — Production
+
+Requisitos:
+
+- deploy aprovado;
+- alertas ativos;
+- dashboards ativos;
+- rollback validado;
+- runbook disponível.
+
+# 15. Erros comuns
+
+| Erro | Impacto | Correção |
+| --- | --- | --- |
+| Começar pelo código | Escopo mal definido. | Iniciar por discovery/scope. |
+| Criar tool antes da intent | Tool sem contexto. | Definir fluxo primeiro. |
+| Dataset depois da produção | Sem regressão. | Criar dataset antes da homologação. |
+| Prompt sem critérios | Resposta inconsistente. | Definir prompt policy. |
+
+
+# 16. Critérios de aceite
+
+- [ ] Discovery concluído.
+- [ ] Escopo aprovado.
+- [ ] Agent design documentado.
+- [ ] Prompts criados.
+- [ ] MCP design aprovado.
+- [ ] RAG design aprovado quando aplicável.
+- [ ] Implementação concluída.
+- [ ] Testes executados.
+- [ ] Evaluator aprovado.
+- [ ] Certification aprovada.
+- [ ] Homologação concluída.
+- [ ] Produção monitorada.