Pular para o conteúdo principal

Execução com Skill Única

A execução com skill única é o caminho rápido — um agente, um domínio, uma tarefa focada. Sem overhead de orquestração, sem coordenação multi-agente. A skill ativa automaticamente a partir do seu prompt em linguagem natural.

Quando Usar Skill Única​

Use quando sua tarefa atende a TODOS estes critérios:

  • Pertence a um domínio — toda a tarefa pertence a frontend, backend, mobile, banco de dados, design, infraestrutura ou outro domínio único
  • Autocontida — sem mudanças de contrato de API entre domínios, sem mudanças de backend necessárias para uma tarefa de frontend
  • Escopo claro — você sabe qual deve ser a saída (um componente, um endpoint, um schema, uma correção)
  • Sem coordenação — outros agentes não precisam executar antes ou depois

Exemplos de tarefas de skill única:

  • Construir um componente de UI
  • Adicionar um endpoint de API
  • Corrigir um bug em uma camada
  • Projetar uma tabela de banco de dados
  • Escrever um módulo Terraform
  • Traduzir um conjunto de strings i18n
  • Criar uma seção do design system

Mude para multi-agente (/work ou /orchestrate) quando:

  • Trabalho de UI precisa de um novo contrato de API (frontend + backend)
  • Uma correção se propaga entre camadas (debug + agentes de implementação)
  • A funcionalidade abrange frontend, backend e banco de dados
  • O escopo cresce além de um domínio após a primeira iteração

Checklist de Preflight​

Antes de fazer o prompt, responda estas quatro perguntas (elas mapeiam para os quatro elementos da Estrutura de Prompt):

ElementoPerguntaPor Que Importa
GoalQue artefato específico deve ser criado ou alterado?Previne ambiguidade — "adicionar um botão" vs "adicionar um formulário com validação"
ContextQual stack, framework e convenções se aplicam?O agente detecta dos arquivos do projeto, mas explícito é melhor
ConstraintsQuais regras devem ser seguidas? (estilo, segurança, performance, compatibilidade)Sem restrições, agentes usam padrões que podem não corresponder ao seu projeto
Done WhenQuais critérios de aceitação você verificará?Dá ao agente um alvo e a você um checklist de verificação

Se qualquer elemento estiver faltando no seu prompt, o agente irá:

  • LOW uncertainty: Aplicar padrões e listar suposições
  • MEDIUM uncertainty: Apresentar 2-3 opções e prosseguir com a mais provável
  • HIGH uncertainty: Bloquear e fazer perguntas (não escreverá código)

Template de Prompt​

Build <specific artifact> using <stack/framework>.
Constraints: <style, performance, security, or compatibility constraints>.
Acceptance criteria:
1) <testable criterion>
2) <testable criterion>
3) <testable criterion>
Add tests for: <critical test cases>.

Detalhamento do Template​

PartePropósitoExemplo
Build <specific artifact>O Goal — o que criar"Build a user registration form component"
using <stack/framework>O Context — stack tecnológico"using React + TypeScript + Tailwind CSS"
Constraints:Regras que o agente deve seguir"accessible labels, no external form libraries, client-side validation only"
Acceptance criteria:Done When — resultados verificáveis"1) email format validation 2) password strength indicator 3) submit disabled while invalid"
Add tests for:Requisitos de teste"valid/invalid submit paths, edge cases for email validation"

Exemplos Reais​

Frontend: Formulário de Login​

Create a login form component in React + TypeScript + Tailwind CSS.
Constraints: accessible labels, client-side validation with Zod, no external form library beyond @tanstack/react-form, shadcn/ui Button and Input components.
Acceptance criteria:
1) Email validation with meaningful error messages
2) Password minimum 8 characters with feedback
3) Disabled submit button while form is invalid
4) Keyboard and screen-reader friendly (ARIA labels, focus management)
5) Loading state while submitting
Add unit tests for: valid submission path, invalid email, short password, loading state.

Fluxo de execução esperado:

  1. Ativação da skill: oma-frontend ativa (palavras-chave: "form", "component", "Tailwind CSS", "React")
  2. Avaliação de dificuldade: Média (2-3 arquivos, algumas decisões de design sobre UX de validação)
  3. Recursos carregados:
    • execution-protocol.md (sempre)
    • snippets.md (padrões de form + Zod)
    • component-template.tsx (estrutura React)
  4. Saída CHARTER_CHECK: 
    CHARTER_CHECK:
    - Clarification level: LOW
    - Task domain: frontend
    - Must NOT do: backend API, database, mobile screens
    - Success criteria: form validation, accessibility, loading state, tests
    - Assumptions: Next.js App Router, @tanstack/react-form + Zod, shadcn/ui, FSD-lite architecture
  5. Implementação:
    • Cria src/features/auth/components/login-form.tsx (Client Component com "use client")
    • Cria src/features/auth/utils/login-schema.ts (schema Zod)
    • Cria src/features/auth/components/skeleton/login-form-skeleton.tsx
    • Usa shadcn/ui <Button>, <Input>, <Label> (somente leitura, sem modificações)
    • Formulário gerenciado por @tanstack/react-form com validação Zod
    • Imports absolutos com @/
    • Um componente por arquivo
  6. Verificação:
    • Checklist: labels ARIA presentes, headings semânticos, navegação por teclado funciona
    • Mobile: renderiza corretamente em viewport de 320px
    • Performance: sem CLS
    • Testes: arquivo de teste Vitest em src/features/auth/utils/__tests__/login-schema.test.ts

Backend: Endpoint de API REST​

Add a paginated GET /api/tasks endpoint that returns tasks for the authenticated user.
Constraints: Repository-Service-Router pattern, parameterized queries, JWT auth required, cursor-based pagination.
Acceptance criteria:
1) Returns only tasks owned by the authenticated user
2) Cursor-based pagination with next/prev cursors
3) Filterable by status (todo, in_progress, done)
4) Response includes total count
Add tests for: auth required, pagination, status filter, empty results.

Fluxo de execução esperado:

  1. Ativação da skill: oma-backend ativa (palavras-chave: "API", "endpoint", "REST")
  2. Detecção de stack: Lê pyproject.toml ou package.json para determinar linguagem/framework. Se stack/ existe, carrega convenções de lá.
  3. Avaliação de dificuldade: Média (2-3 arquivos: route, service, repository, mais teste)
  4. Recursos carregados:
    • execution-protocol.md (sempre)
    • stack/snippets.md se disponível (route, padrões de query paginada)
    • stack/tech-stack.md se disponível (API específica do framework)
  5. CHARTER_CHECK: 
    CHARTER_CHECK:
    - Clarification level: LOW
    - Task domain: backend
    - Must NOT do: frontend UI, mobile screens, database schema changes
    - Success criteria: authenticated endpoint, cursor pagination, status filter, tests
    - Assumptions: existing JWT auth middleware, PostgreSQL, existing Task model
  6. Implementação:
    • Repository: TaskRepository.find_by_user(user_id, cursor, status, limit) com query parametrizada
    • Service: TaskService.get_user_tasks(user_id, cursor, status, limit) — wrapper de lógica de negócio
    • Router: GET /api/tasks com middleware de auth JWT, validação de entrada, formatação de resposta
    • Testes: auth obrigatória retorna 401, paginação retorna cursor correto, filtro funciona, vazio retorna 200 com array vazio

Mobile: Tela de Configurações​

Build a settings screen in Flutter with profile editing (name, email, avatar), notification preferences (toggle switches), and a logout button.
Constraints: Riverpod for state management, GoRouter for navigation, Material Design 3, handle offline gracefully.
Acceptance criteria:
1) Profile fields pre-populated from user data
2) Changes saved on submit with loading indicator
3) Notification toggles persist locally (SharedPreferences)
4) Logout clears token storage and navigates to login
5) Offline: show cached data with "offline" banner
Add tests for: profile save, logout flow, offline state.

Fluxo de execução esperado:

  1. Ativação da skill: oma-mobile ativa (palavras-chave: "Flutter", "screen", "mobile")
  2. Avaliação de dificuldade: Média (tela de configurações + gerenciamento de estado + tratamento offline)
  3. Recursos carregados:
    • execution-protocol.md
    • snippets.md (template de tela, padrão de provider Riverpod)
    • screen-template.dart
  4. CHARTER_CHECK: 
    CHARTER_CHECK:
    - Clarification level: LOW
    - Task domain: mobile
    - Must NOT do: backend API changes, web frontend, database schema
    - Success criteria: profile editing, notification toggles, logout, offline
    - Assumptions: existing auth service, Dio interceptors, Riverpod, GoRouter
  5. Implementação:
    • Tela: lib/features/settings/presentation/settings_screen.dart (Stateless Widget com Riverpod)
    • Providers: lib/features/settings/providers/settings_provider.dart
    • Repository: lib/features/settings/data/settings_repository.dart
    • Tratamento offline: interceptor Dio captura SocketException, recorre a dados em cache
    • Todos os controllers dispostos no método dispose()

Banco de Dados: Design de Schema​

Design a database schema for a multi-tenant SaaS project management tool. Entities: Organization, Project, Task, User, TeamMembership.
Constraints: PostgreSQL, 3NF, soft delete with deleted_at, audit fields (created_at, updated_at, created_by), row-level security for tenant isolation.
Acceptance criteria:
1) ERD with all relationships documented
2) External, conceptual, and internal schema layers documented
3) Index strategy for common query patterns (tasks by project, tasks by assignee)
4) Capacity estimation for 10K orgs, 100K users, 1M tasks
5) Backup strategy with full + incremental cadence
Add deliverables: data standards table, glossary, migration script.

Fluxo de execução esperado:

  1. Ativação da skill: oma-db ativa (palavras-chave: "database", "schema", "ERD", "migration")
  2. Avaliação de dificuldade: Complexa (decisões de arquitetura, múltiplas entidades, planejamento de capacidade)
  3. Recursos carregados:
    • execution-protocol.md
    • document-templates.md (estrutura de entregáveis)
    • examples.md
    • anti-patterns.md (revisão durante otimização)
  4. CHARTER_CHECK: 
    CHARTER_CHECK:
    - Clarification level: LOW
    - Task domain: database
    - Must NOT do: API implementation, frontend UI, infrastructure
    - Success criteria: schema, ERD, indexes, capacity estimate, backup strategy
    - Assumptions: PostgreSQL, 3NF, soft delete, multi-tenant with RLS
  5. Workflow: Explorar (entidades, relacionamentos, padrões de acesso, estimativas de volume) -> Projetar (schemas externo/conceitual/interno, restrições, campos de lifecycle) -> Otimizar (índices para padrões de query, estratégia de particionamento, plano de backup, revisão de anti-padrões)
  6. Entregáveis:
    • Resumo do schema externo (views por papel: admin, gerente de projeto, membro da equipe)
    • Schema conceitual com ERD (Organization 1:N Project, Project 1:N Task, Organization 1:N TeamMembership, etc.)
    • Schema interno com DDL físico, índices, particionamento
    • Tabela de padrões de dados (regras de nomenclatura de campos, convenções de tipo)
    • Glossário (tenant, workspace, assignee, etc.)
    • Planilha de estimativa de capacidade
    • Estratégia de backup (full diário + incremental horário, retenção de 30 dias)
    • Script de migração

Checklist do Portão de Qualidade​

Após o agente entregar sua saída, verifique estes itens antes de aceitar:

Verificações Universais (Todos os Agentes)​

  • Comportamento corresponde aos critérios de aceitação — cada critério do seu prompt é satisfeito
  • Testes cobrem caminho feliz e casos de borda — não apenas o caminho feliz
  • Sem alterações de arquivo não relacionadas — apenas arquivos relevantes para a tarefa foram modificados
  • Módulos compartilhados não quebrados — imports, tipos e interfaces usados por outro código ainda funcionam
  • Charter foi seguido — as restrições "Must NOT do" foram respeitadas
  • Lint, typecheck, build passam — execute as verificações padrão do seu projeto

Específico de Frontend​

  • Acessibilidade: elementos interativos têm aria-label, headings semânticos, navegação por teclado funciona
  • Mobile: renderiza corretamente em breakpoints 320px, 768px, 1024px, 1440px
  • Performance: sem CLS, meta de FCP atingida
  • Error boundaries e loading skeletons implementados
  • Componentes shadcn/ui não modificados diretamente (wrappers usados)
  • Imports absolutos com @/ (sem ../../ relativos)

Específico de Backend​

  • Arquitetura limpa mantida: sem lógica de negócio em route handlers
  • Todas as entradas validadas (sem confiar em entrada do usuário)
  • Apenas queries parametrizadas (sem interpolação de string em SQL)
  • Exceções customizadas via módulo centralizado de erros (sem exceções HTTP brutas)
  • Endpoints de auth com rate limiting

Específico de Mobile​

  • Todos os controllers dispostos no método dispose()
  • Offline tratado graciosamente
  • Meta de 60fps mantida (sem jank)
  • Testado em iOS e Android

Específico de Banco de Dados​

  • Pelo menos 3NF (ou justificativa documentada para desnormalização)
  • Todas as três camadas de schema documentadas (externa, conceitual, interna)
  • Restrições de integridade explícitas (entidade, domínio, referencial, regra de negócio)
  • Revisão de anti-padrões completada

Sinais de Escalação​

Observe estes sinais que indicam que você deve mudar de skill única para execução multi-agente:

SinalO Que SignificaAção
Agente diz "this requires a backend change"Tarefa tem dependências cross-domínioMude para /work — adicione agente backend
CHARTER_CHECK do agente mostra itens "Must NOT do" que são realmente necessáriosEscopo excede um domínioPlaneje a funcionalidade completa com /plan primeiro
Correção se propaga em 3+ arquivos em diferentes camadasUma correção afeta múltiplos domíniosUse /debug com escopo mais amplo, ou /work
Agente descobre incompatibilidade de contrato de APIDesacordo frontend/backendExecute /plan para definir contratos, depois re-spawne ambos os agentes
Portão de qualidade falha em pontos de integraçãoComponentes não conectam corretamenteAdicione etapa de revisão QA: oma agent:spawn qa "Review integration"
Tarefa cresce de "um componente" para "três componentes + nova rota + API"Desvio de escopo durante execuçãoPare, execute /plan para decompor, depois /orchestrate
Agente bloqueia com HIGH clarificationRequisitos fundamentalmente ambíguosResponda as perguntas do agente ou execute /brainstorm para clarificar abordagem

A Regra Geral​

Se você se encontrar re-spawnando o mesmo agente mais de duas vezes com refinamentos, a tarefa é provavelmente multi-domínio e precisa de /work ou no mínimo uma etapa de /plan para decompô-la adequadamente.