First commit

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

@@ -0,0 +1,227 @@
+# SPEC-016 — Agent Development Lifecycle
+
+## Agent Platform OCI
+
+Version: 1.0.0
+
+
+---
+
+## Reading guide
+
+each SPEC is organizada for servir tanto como Contract arquitetural quanto como guia practical of adoção.
+
+The document structure is:
+
+1. Concept.
+2. Problem addressed.
+3. When to use.
+4. When not to use.
+5. Architecture.
+6. Implementation.
+7. Examples.
+8. Common errors.
+9. Acceptance criteria.
+
+---
+
+
+# 1. Concept
+
+O ciclo of vida of Development of Agents Defines as stages desde a discovery of the caso of uso até a Operations em Production.
+
+Ele organiza trabalho of produto, Architecture, engenharia, Security, Evaluation and Operations.
+
+# 2. Flow of the ciclo of 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. stage 1 — Discovery
+
+objective:
+
+- entender problema;
+- identificar users;
+- mapear canais;
+- mapear sistemas;
+- mapear documentos;
+- mapear Risks.
+
+Output:
+
+```yaml
+discovery:
+  business_problem: ""
+  users: []
+  channels: []
+  systems: []
+  documents: []
+  risks: []
+```
+
+# 4. stage 2 — Scope Definition
+
+Definir:
+
+- o that o Agent does;
+- o that No does;
+- intenções;
+- actions permitidas;
+- Limits;
+- criteria of success.
+
+# 5. stage 3 — Agent Design
+
+Desenhar:
+
+- agent_id;
+- rotas;
+- intents;
+- BusinessContext;
+- tools;
+- RAG namespaces;
+- Memory;
+- handoff.
+
+# 6. stage 4 — Prompt Design
+
+create:
+
+- system prompt;
+- prompt policy;
+- instruções of Domain;
+- Examples;
+- restrições;
+- formato of Response.
+
+# 7. stage 5 — MCP Design
+
+Definir:
+
+- tools;
+- parâmetros;
+- owner;
+- SLA;
+- timeout;
+- retry;
+- cache;
+- Operations mutável or idempotente.
+
+# 8. stage 6 — RAG Design
+
+Definir:
+
+- documentos;
+- namespace;
+- ingestão;
+- chunking;
+- embeddings;
+- Update;
+- criteria of relevância.
+
+# 9. stage 7 — Implementation
+
+implement:
+
+- classe of the Agent;
+- configs;
+- prompts;
+- datasets;
+- tests;
+- Observability específica.
+
+# 10. stage 8 — Testing
+
+Tests minimum:
+
+- unit;
+- integration;
+- contract;
+- MCP;
+- RAG;
+- guardrails;
+- judges;
+- runtime;
+- channel.
+
+# 11. stage 9 — Evaluation
+
+Executar:
+
+```bash
+af-evaluator run --agent-id <agent_id> --dataset <dataset>
+```
+
+Assess:
+
+- quality;
+- groundedness;
+- safety;
+- tool correctness;
+- route accuracy.
+
+# 12. stage 10 — Certification
+
+Executar:
+
+```bash
+af-certification run --agent-id <agent_id>
+```
+
+# 13. stage 11 — Homologation
+
+validate with:
+
+- negócio;
+- Architecture;
+- Security;
+- Operations;
+- integration.
+
+# 14. stage 12 — Production
+
+Requirements:
+
+- deploy aprovado;
+- Alerts ativos;
+- dashboards ativos;
+- rollback validado;
+- runbook disponível.
+
+# 15. Common errors
+
+| Error | Impact | Correction |
+| --- | --- | --- |
+| Começar by the código | Scope mal definido. | Iniciar por discovery/scope. |
+| create tool before of the intent | Tool without Context. | Definir Flow primeiro. |
+| Dataset after of the Production | without regressão. | create dataset before of the homologação. |
+| Prompt without criteria | Response inconsistente. | Definir prompt policy. |
+
+
+# 16. Acceptance criteria
+
+- [ ] Discovery concluído.
+- [ ] Scope aprovado.
+- [ ] Agent design documentado.
+- [ ] Prompts criados.
+- [ ] MCP design aprovado.
+- [ ] RAG design aprovado when aplicável.
+- [ ] Implementation concluída.
+- [ ] Tests executados.
+- [ ] Evaluator aprovado.
+- [ ] Certification aprovada.
+- [ ] Homologação concluída.
+- [ ] Production monitorada.