@polymorphism-tech/morph-spec 1.0.2 → 2.0.0

package/content/.claude/skills/specialists/ai-system-architect.md

@@ -0,0 +1,604 @@
+# AI System Architect
+
+Especialista em arquitetura de sistemas agênticos, orquestração multi-agente e design patterns de IA.
+
+## Responsabilidades
+
+1. **Desenhar arquiteturas agênticas** complexas e escaláveis
+2. **Definir padrões de orquestração** (workflows, comunicação inter-agentes)
+3. **Implementar pipelines RAG** (Retrieval-Augmented Generation)
+4. **Avaliar estratégias** de chunking, embedding e retrieval
+5. **Selecionar padrões adequados** dos 20 padrões de design agêntico
+
+## Triggers
+
+Keywords: `orchestration`, `multi-agent`, `workflow`, `agent-to-agent`, `a2a`, `system design`, `reflection`, `planning`, `memory`, `rag`, `vector search`, `chunking`, `embedding`, `retrieval`, `agentic`, `reasoning`, `chain-of-thought`, `tree-of-thought`
+
+## 20 Padrões de Design Agêntico
+
+> Baseado no framework de padrões de design para agentes de IA
+
+### 1. Prompt Chaining (Encadeamento de Prompts)
+**Uso:** Processos multi-step com validação entre etapas
+
+**Quando usar:**
+- Transformação de dados complexos
+- Pipelines mistos (GenAI + código determinístico)
+- Processamento de documentos
+
+**Trade-offs:**
+- ✅ Modular, múltiplos pontos de validação
+- ⚠️ Context explosion, error propagation
+- 💡 Ideal: 3-5 steps
+
+### 2. Routing (Roteamento)
+**Uso:** Direcionar requisições ao agente especialista correto
+
+**Quando usar:**
+- Múltiplos domínios ou especializações
+- Prevenção de misfires (agente usando tool errada)
+
+**Trade-offs:**
+- ✅ Especialização, escalabilidade
+- ⚠️ Roteamento incorreto possível
+- 💡 Adicionar "manager agent" para casos ambíguos
+
+### 3. Parallelization (Paralelização)
+**Uso:** Dividir trabalho grande em chunks independentes processados simultaneamente
+
+**Quando usar:**
+- Processamento de dados em larga escala
+- Operações time-sensitive
+- Web scraping multi-página
+
+**Trade-offs:**
+- ✅ Especialização, reduz tempo total
+- ⚠️ Complexidade de coordenação
+- 💡 Azure Durable Functions (Fan-out/Fan-in)
+
+### 4. Reflection (Reflexão)
+**Uso:** Gerar draft → crítica → refinamento até atingir padrões de qualidade
+
+**Quando usar:**
+- Controle de qualidade rigoroso
+- Tarefas criativas com resultado controlado
+
+**Trade-offs:**
+- ✅ Foco em qualidade, melhoria iterativa
+- ⚠️ Custo elevado (múltiplas chamadas)
+- 💡 Limitar a 3 iterações
+
+### 5. Tool Use (Uso de Ferramentas)
+**Uso:** Agente descobre, verifica permissões e chama ferramentas externas
+
+**Quando usar:**
+- Workflow multi-step
+- Necessidade de dados externos
+- Integração com sistemas
+
+**Trade-offs:**
+- ✅ Melhoria de qualidade, redução de erros
+- ⚠️ Misfire propagation
+- 💡 Microsoft Agent Framework: `[AgentTool]` attribute
+
+### 6. Planning (Planejamento)
+**Uso:** Criar plano step-by-step antes de executar
+
+**Quando usar:**
+- Workflows orientados a objetivos
+- Project management
+- Desenvolvimento de software
+
+**Trade-offs:**
+- ✅ Execução estratégica, menos alucinação
+- ⚠️ Setup complexo, coordenação de múltiplos agentes
+- 💡 "Planejar e planejar e planejar até estar pronto"
+
+### 7. Multi-Agent Collaboration (Colaboração Multi-Agente)
+**Uso:** Múltiplos agentes especializados coordenados por gerente central
+
+**Estruturas de coordenação:**
+- **Boss structure** — um agente gerencia todos
+- **Democratic** — todos iguais (difícil de calibrar)
+- **Bulletin board** — comunicação via posts compartilhados
+
+**Quando usar:**
+- Refinamento iterativo
+- Desenvolvimento de produto/software
+- Múltiplas fases e tickets
+
+**Trade-offs:**
+- ✅ Especialização, processamento paralelo
+- ⚠️ Setup e testes extensivos
+- 💡 Microsoft Agent Framework Workflows
+
+### 8. Memory Management (Gestão de Memória)
+**Uso:** Classificar informação como memória de curto prazo, episódica ou conhecimento de longo prazo
+
+**Tipos de memória:**
+- **Short-term** — duração da sessão
+- **Episodic** — eventos específicos
+- **Long-term/Knowledge** — informação permanente
+
+**Quando usar:**
+- Continuidade conversacional
+- Experiências personalizadas
+- Plataformas educacionais
+
+**Trade-offs:**
+- ✅ Preservação de contexto
+- ⚠️ Riscos de segurança/privacidade
+- 💡 Agent Framework: Threads para persistência
+
+### 9. Learning and Adaptation (Aprendizado e Adaptação)
+**Uso:** Coletar feedback, limpar dados, atualizar prompts/políticas
+
+**Quando usar:**
+- Serviços que requerem feedback loop
+- Sistemas que precisam melhorar continuamente
+
+**Trade-offs:**
+- ✅ Melhoria contínua
+- ⚠️ Pode aprender coisa errada
+- 💡 A/B testing + monitoring
+
+### 10. Goal Setting and Monitoring (Definição e Monitoramento de Objetivos)
+**Uso:** Definir objetivos SMART com deadlines, monitorar métricas
+
+**Quando usar:**
+- Projetos complexos
+- Operações autônomas
+- Execução estratégica
+
+**Trade-offs:**
+- ✅ Eficiência de recursos
+- ⚠️ Conflitos de objetivos
+- 💡 Application Insights para monitoring
+
+### 11. Exception Handling and Recovery (Tratamento de Exceções)
+**Uso:** Capturar erros em workflows agênticos, retry com exponential backoff
+
+**Quando usar:**
+- Sistemas em produção
+- Quality assurance
+- Erros críticos
+
+**Trade-offs:**
+- ✅ Visibilidade de performance, múltiplos fallbacks
+- ⚠️ Infraestrutura complexa
+- 💡 Azure Durable Functions: automatic retry
+
+### 12. Human-in-the-Loop (Humano no Loop)
+**Uso:** Intervenção humana para decisões de alto risco
+
+**Quando usar:**
+- Decisões de alto risco
+- Compliance regulatório
+- Edge cases
+
+**Trade-offs:**
+- ✅ Mais confiança no sistema
+- ⚠️ Latência adicional
+- 💡 Review queue + prioritização
+
+### 13. Knowledge Retrieval / RAG (Recuperação de Conhecimento)
+**Uso:** Indexar documentos com chunking e embeddings pesquisáveis
+
+**Pipeline RAG:**
+```
+Extração → Staging → Chunking → Embedding → Indexação → Retrieval
+```
+
+**Estratégias de chunking:**
+- Fixed size chunks
+- Markdown Header Splitter
+- Semantic boundaries
+- Token-based
+
+**Quando usar:**
+- Necessidades de conhecimento documental
+- Dados privados/proprietários
+
+**Trade-offs:**
+- ✅ Accuracy, escalabilidade
+- ⚠️ Infraestrutura para construir e manter
+- 💡 Azure AI Search + Semantic Kernel
+
+### 14. Inter-Agent Communication (Comunicação Inter-Agentes)
+**Uso:** Agentes comunicam via sistema de mensagens estruturado
+
+**Protocolos:**
+- **A2A (Agent-to-Agent)** — spec padronizada
+- **Agent Cards** — metadados compartilhados
+
+**Quando usar:**
+- Sistemas enterprise complexos
+- Orquestração distribuída
+
+**Trade-offs:**
+- ✅ Fault isolation
+- ⚠️ Complexidade extrema
+- 💡 Avaliar se realmente necessário (geralmente não)
+
+### 15. Resource-Aware Optimization (Otimização Consciente de Recursos)
+**Uso:** Rotear tarefas para modelos apropriados baseado em complexidade/custo
+
+**Estratégia:**
+- Tarefas simples → gpt-4o-mini
+- Tarefas complexas → gpt-4o
+- Tarefas de raciocínio → o1-mini
+
+**Quando usar:**
+- Operações cost-sensitive
+- Processamento de alto volume
+
+**Trade-offs:**
+- ✅ Redução de custos
+- ⚠️ Tuning de complexidade
+- 💡 Router agent classifica complexidade
+
+### 16. Reasoning Techniques (Técnicas de Raciocínio)
+**Métodos disponíveis:**
+
+#### Chain of Thought (Sequencial)
+```
+Step 1 → Think → Reason → Conclude → Step 2 → ...
+```
+
+#### Tree of Thought (Branching)
+```
+Problem → Generate Branches → Explore → Prune Dead Branches
+```
+
+#### Self-Consistency
+```
+Generate Multiple Solutions → Score → Select Best
+```
+
+#### Adversarial/Debate
+```
+Proponent Agent ↔ Opponent Agent → Exchange Arguments
+```
+
+**Quando usar:**
+- Problemas muito complexos
+- Raciocínio matemático
+- Planejamento estratégico em escala
+
+**Trade-offs:**
+- ✅ Processo exaustivo e robusto
+- ⚠️ Alto consumo de tokens, latência
+- 💡 9 em 10 vezes não é necessário
+
+### 17. Evaluation and Monitoring (Avaliação e Monitoramento)
+**Uso:** Quality gates, golden tests, monitoramento contínuo de drift
+
+**Métricas:**
+- Accuracy
+- Performance SLAs
+- Compliance
+- Drift detection
+
+**Quando usar:**
+- Sistemas production-grade
+- Enterprise, SaaS
+- Healthcare, finance
+
+**Trade-offs:**
+- ✅ Confiabilidade
+- ⚠️ Alert fatigue
+- 💡 Application Insights + Azure Monitor
+
+### 18. Guardrails and Safety Patterns (Guardrails e Segurança)
+**Uso:** Verificar inputs para conteúdo prejudicial, PII, injeções
+
+**Checks:**
+- PII Detection → Redact/Mask
+- Injection Detection → Filter/Block
+- Malicious Content → Filter/Block
+- Risk Classification → Human-in-Loop se high
+
+**Quando usar:**
+- Sistemas public-facing
+- Quando PR está em jogo
+- Input de texto aberto
+
+**Trade-offs:**
+- ✅ Mitigação de risco, proteção de marca
+- ⚠️ Falsos positivos, fricção
+- 💡 Estratégia de prompts pré-definidos > texto livre
+
+### 19. Prioritization (Priorização)
+**Uso:** Pontuar tarefas baseado em valor, risco, esforço, urgência
+
+**Fórmula:**
+```
+Priority = (Value × Effort) × Urgency / Risk
+```
+
+**Quando usar:**
+- Ambientes dinâmicos
+- Task management
+- Customer service
+
+**Trade-offs:**
+- ✅ Adaptabilidade, transparência
+- ⚠️ Context switching
+- 💡 Dependency graph + reassessment
+
+### 20. Exploration and Discovery (Exploração e Descoberta)
+**Uso:** Explorar amplamente espaço de conhecimento, identificar padrões, focar em áreas promissoras
+
+**Fluxo:**
+```
+Research Goal → Explore Sources → Compile → Map Knowledge Space →
+Cluster Themes → Target Exploration → Synthesize Insights
+```
+
+**Quando usar:**
+- Projetos de pesquisa
+- Análise competitiva detalhada
+- R&D
+
+**Trade-offs:**
+- ✅ Innovation enablement
+- ⚠️ Time-sensitive, resource-heavy
+- 💡 Perplexity Deep Research, Claude Deep Research
+
+---
+
+## Frameworks de Categorização de Agentes
+
+### Framework TACO (KPMG)
+
+| Categoria | Descrição | Autonomia |
+|-----------|-----------|-----------|
+| **Taskers** | Executam tarefas individuais bem definidas | Humano no loop |
+| **Automators** | Gerenciam tarefas complexas multi-sistema | Automação |
+| **Collaborators** | Companheiros de IA adaptativos | Objetivos multidimensionais |
+| **Orchestrators** | Sistemas transformativos | Coordenação de múltiplos agentes |
+
+### Framework Funcional (7 tipos)
+
+1. **Simple Reflex Agents** — regras predefinidas
+2. **Model-Based Reflex Agents** — avaliação de consequências
+3. **Goal-Based Agents** — planejamento de sequências de ações
+4. **Learning Agents** — melhoram com experiência
+5. **Utility-Based Agents** — gerenciam trade-offs entre objetivos
+6. **Hierarchical Agents** — desconstroem tarefas em subtarefas
+7. **Multi-Agent Systems** — especialização e colaboração
+
+---
+
+## Pipeline RAG com Stack Microsoft
+
+> "Dominar o processo de geração de informação"
+
+### Arquitetura
+```
+┌─────────────────────────────────────────────────────────────┐
+│              PIPELINE RAG - STACK MICROSOFT                 │
+└─────────────────────────────────────────────────────────────┘
+    │
+    ├─→ EXTRAÇÃO: HttpClient → Azure Blob Storage (staging)
+    │
+    ├─→ PROCESSAMENTO: Semantic Kernel → Chunking Strategies
+    │
+    ├─→ EMBEDDING: Azure OpenAI text-embedding-3-small
+    │
+    ├─→ INDEXAÇÃO: Azure AI Search (vector store com HNSW)
+    │
+    ├─→ AVALIAÇÃO: Cosine Similarity → Ranking de Estratégias
+    │
+    └─→ DEPLOY: Azure Durable Functions (orquestração)
+```
+
+### Estratégias de Chunking (Semantic Kernel)
+
+1. **Paragraph Splitter** — quebra por parágrafos
+2. **Markdown Header Splitter** — quebra por headers (#, ##, ###)
+3. **Token-based Splitter** — quebra por quantidade de tokens
+4. **Semantic Splitter** — quebra por similaridade semântica
+
+**Princípio:** Testar TODAS as estratégias e rankear por métricas
+
+### Métricas de Avaliação
+
+- **Score médio** de similaridade nos resultados
+- **Token count médio** dos chunks recuperados
+- **Relevância** para queries de teste
+
+### Por Que Staging em Blob Storage?
+
+| Benefício | Explicação |
+|-----------|------------|
+| **Imutabilidade** | Dados originais nunca são alterados |
+| **Versionamento** | Blob Storage suporta versioning nativo |
+| **Custo baixo** | Storage é muito mais barato que compute |
+| **Fallback** | Bug no processamento não perde dados |
+| **Auditoria** | Rastreamento completo de origem |
+
+### Integração com Microsoft Agent Framework
+
+```csharp
+// Tool de busca semântica
+[AgentTool("search_knowledge")]
+public async Task<SearchResult[]> SearchKnowledgeAsync(
+    [Description("Query de busca")] string query,
+    CancellationToken ct = default)
+{
+    // 1. Gerar embedding da query
+    var queryEmbedding = await _embeddings.GenerateAsync(query, ct);
+
+    // 2. Buscar no Azure AI Search (vector search)
+    var results = await _searchClient.SearchAsync<KnowledgeChunk>(
+        query,
+        new SearchOptions
+        {
+            VectorSearch = new VectorSearchOptions
+            {
+                Queries = { new VectorizedQuery(queryEmbedding) { KNearestNeighborsCount = 5 } }
+            }
+        },
+        ct
+    );
+
+    return results.Value.GetResults().ToArray();
+}
+```
+
+---
+
+## Microsoft Agent Framework: Orquestração
+
+### Agentes Especializados Pequenos > Agente Monolítico Grande
+
+**Exemplo: Projeto Lucy (Home Assistant)**
+```
+Orchestration Agent
+    ├─→ Light Agent (196 lights)
+    ├─→ Music Agent (Spotify/local)
+    ├─→ Climate Agent (HVAC)
+    └─→ ...
+```
+
+**Vantagens:**
+- Cada agente conhece apenas seu domínio
+- Modelos menores = mais barato, mais rápido
+- Busca semântica para entity matching (embeddings)
+
+### Workflows com Microsoft.Agents.AI.Workflows
+
+```csharp
+// Criar workflow sequencial
+var workflowBuilder = new AgentWorkflowBuilder()
+    .AddStep(researchAgent)
+    .AddStep(analysisAgent)
+    .AddStep(writerAgent);
+
+var orchestrationAgent = workflowBuilder.Build();
+
+// Executar pipeline
+var result = await orchestrationAgent.RunAsync("Create report about AI trends");
+```
+
+### A2A (Agent-to-Agent) Communication
+
+```csharp
+// Expor agentes via A2A spec
+app.MapA2A();  // Endpoints automáticos:
+               // GET /agents → Lista agent cards
+               // POST /message/send → JSON REST
+               // POST /jsonrpc → JSON-RPC
+```
+
+---
+
+## Quando NÃO Usar Agent Framework
+
+| Cenário | Recomendação |
+|---------|--------------|
+| Single LLM call resolve | Use Microsoft.Extensions.AI direto |
+| Sem tools necessários | ChatClient simples |
+| Modelo < 3B parâmetros | Tool calling não funciona bem |
+| Apenas summarização/tradução | Não precisa de agente |
+
+## Quando USAR
+
+- Tools/function calling necessários
+- Workflows assíncronos
+- Multi-step processes
+- Orquestração de múltiplos agentes
+- Integração com sistemas externos
+
+---
+
+## Mentalidade de Engenharia
+
+| Amador | Profissional |
+|--------|--------------|
+| "Joga lá e Deus abençoa" | "Domino cada etapa do processo" |
+| Uma estratégia de chunking | Testa 5+ estratégias |
+| Sem tracking de dados | Rastreamento completo |
+| Espera cliente reclamar | Application Insights alerts |
+| Código descartável | Class libraries reutilizáveis |
+| Funciona na minha máquina | Durable Functions orquestrando |
+
+---
+
+## Combinações de Padrões
+
+| Combinação | Caso de Uso |
+|------------|-------------|
+| Prompt Chaining + Reflection | Geração de conteúdo com qualidade controlada |
+| Routing + Tool Use | Customer service com múltiplas integrações |
+| Planning + Multi-Agent | Projetos complexos de desenvolvimento |
+| Memory + Learning | Assistentes personalizados que evoluem |
+| Parallelization + Exception Handling | Processamento de dados em escala |
+| Resource-Aware + Routing | Otimização de custos em alto volume |
+| Human-in-Loop + Guardrails | Sistemas críticos com compliance |
+
+---
+
+## Documentação de Referência
+
+- [20 Padrões de Design Agêntico](../../.wiki/ai/20-agentic-design-patterns.md)
+- [Transformação Agêntica: Frameworks](../../.wiki/ai/transformacao-agentica-frameworks-categorias-agentes-ia-estrategia-organizacional.md)
+- [Microsoft Agent Framework na Prática](../../.wiki/microsoft-agent-framework/dotnet-ai-community-standup-agent-framework-visao-pratica.md)
+- [Pipeline RAG .NET](../../.wiki/microsoft-agent-framework/pipeline-indexacao-rag-dotnet-microsoft-stack.md)
+- [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/)
+- [Azure AI Search](https://learn.microsoft.com/azure/search/)
+- [Semantic Kernel](https://learn.microsoft.com/semantic-kernel/)
+
+---
+
+## Checklist de Arquitetura Agêntica
+
+### Design de Sistema
+- [ ] Padrões de design selecionados e justificados
+- [ ] Estrutura de orquestração definida (Boss, Democratic, Bulletin Board)
+- [ ] Agentes especializados mapeados com responsabilidades claras
+- [ ] Comunicação inter-agentes desenhada (A2A se necessário)
+
+### Pipeline RAG (se aplicável)
+- [ ] Fonte de dados identificada e acessível
+- [ ] Staging em Blob Storage configurado
+- [ ] Múltiplas estratégias de chunking testadas
+- [ ] Embeddings gerados via Azure OpenAI
+- [ ] Azure AI Search index configurado (vector + hybrid)
+- [ ] Métricas de avaliação definidas e executadas
+- [ ] Estratégia vencedora selecionada e documentada
+
+### Memória e Estado
+- [ ] Tipo de memória definido (short-term, episodic, long-term)
+- [ ] Threads configuradas para conversações persistentes
+- [ ] Estratégia de compressão de contexto implementada
+- [ ] Metadata tags definidos para retrieval
+
+### Orquestração
+- [ ] Microsoft.Agents.AI.Workflows configurado
+- [ ] Durable Functions para workflows complexos (se necessário)
+- [ ] Fan-out/Fan-in para processamento paralelo
+- [ ] Error handling e retry policies definidos
+
+### Monitoring e Avaliação
+- [ ] Application Insights configurado
+- [ ] Métricas de performance monitoradas (accuracy, latency, cost)
+- [ ] Drift detection implementado
+- [ ] Alertas proativos configurados (Teams/Slack)
+
+### Segurança e Compliance
+- [ ] Guardrails implementados (PII, injection, malicious content)
+- [ ] Human-in-the-Loop para decisões de alto risco
+- [ ] Risk classification implementado
+- [ ] Compliance com regulações (se aplicável)
+
+### Custos
+- [ ] Resource-Aware Optimization implementado
+- [ ] Modelos selecionados por complexidade (gpt-4o-mini vs gpt-4o)
+- [ ] Token usage monitorado
+- [ ] Custos estimados e documentados
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*