---
id: create-service
agent: dev
title: Criar um serviço novo a partir de template
inputs: [tipo de serviço (api-integration|utility|agent-tool), nome, story/spec]
outputs: [scaffold do serviço, teste inicial, File List atualizada]
elicit: false
modes: [interactive, yolo]
---

# Criar um serviço novo a partir de template

**Objetivo:** scaffoldar um serviço novo a partir de um template do projeto — já com estrutura,
ponto de entrada e teste inicial — pelo menor caminho, sem inventar escopo além do que a story pede.

**Pré-condições:**
- O serviço rastreia a uma story/spec que pede explicitamente sua criação. Sem essa origem,
  **pare** e elicito o escopo — não invento serviço (Constituição Art. IV).
- O `tipo de serviço` é um dos templates suportados (`api-integration`, `utility`, `agent-tool`).
  Tipo desconhecido → **pare** e confirmo com o usuário.
- Não existe já um serviço que resolve isso. Antes de criar, checo o codebase: se existe um que
  serve (REUSE) ou quase serve (ADAPT), uso/adapto em vez de criar.

## Passos

1. **Confirmo a origem** (story/spec) e o `tipo` do serviço. Identifico o template correspondente
   em `templates/` e o leio antes de scaffoldar.
2. **Verifico ausência de duplicata.** Procuro no codebase um serviço equivalente. Se existe, paro e
   reporto — reuso vence criação.
3. **Scaffoldo o serviço** a partir do template do tipo escolhido, no path do projeto (`.nexus/` para
   artefatos de framework; o pacote/módulo do projeto para código de app). Preencho os pontos do
   template: nome, ponto de entrada, contrato/interface conforme a story.
4. **Sigo os padrões do projeto** (naming, imports absolutos, tratamento de erro). Não introduzo
   dependência nova não aprovada — se o serviço exige uma, **paro** e confirmo com o usuário.
5. **Escrevo o teste inicial** que prova que o esqueleto sobe e expõe o contrato mínimo. Serviço sem
   teste não está pronto — está pela metade.
6. **Rodo lint + o teste inicial** (verde obrigatório) e **atualizo a File List** com tudo que criei.

## Critério de pronto (DoD)

- [ ] O serviço rastreia a uma story/spec (sem invenção de escopo)
- [ ] Nenhuma duplicata existente foi ignorada (reúso checado antes de criar)
- [ ] Scaffold gerado a partir do template do tipo correto, seguindo os padrões do projeto
- [ ] Teste inicial verde provando que o esqueleto sobe e expõe o contrato mínimo
- [ ] Nenhuma dependência nova não aprovada introduzida
- [ ] File List atualizada com os arquivos criados

## Falha / recuperação

- **Já existe serviço equivalente** → paro e reporto; reúso/adapto em vez de duplicar.
- **O tipo não tem template** → HALT e confirmo com o usuário; não improviso scaffold do zero sem
  base.
- **O serviço exigiria dependência nova não aprovada** → HALT e confirmo antes de adicionar
  (Constituição Art. IV).
- **O escopo do serviço não está na story** → paro e elicito; não invento contrato.