---
title: Providers e adapters
description: Diferença entre provider, client, geração de artefato, execução com escrita e integração externa.
context: Contrato de adapters e seleção de provider/model/effort.
---

# Providers e adapters

Um provider fornece capacidade de geração. Um client é a superfície onde o agent opera. Um adapter define como a capacidade conversa com o contrato SDD. Essas coisas não são equivalentes.

## Tipos

| Tipo | Responsabilidade | Exemplos |
|---|---|---|
| Provider | Modelo, effort, autenticação e limites | Codex, Claude, Antigravity, opencode, Cursor, Devin, Trae |
| Client | Experiência de editor ou shell | Codex, Claude Code, Cursor, opencode |
| Geração de artefato | Produzir Markdown via harness controlado | `codex exec --json`, `claude --print`, `opencode run` |
| Execução com escrita | Alterar workspace real | Codex, Claude Code, opencode, Cursor Agent, Devin, Trae, Antigravity |
| Integração externa | Mapear artefatos e estados para sistemas | GitHub, GitLab, Atlassian, Linear/Notion, Markdown-only |

## Precedência de seleção

1. Flags: `--provider`, `--model`, `--effort`, `--offline`.
2. Variáveis: `SDD_PROVIDER`, `SDD_MODEL`, `SDD_EFFORT`, `SDD_OFFLINE`.
3. Configuração em `sdd.config.yaml`.
4. Defaults embutidos.

## Commands

```bash
sdd providers list
sdd providers doctor --json
sdd orchestration --provider claude --model claude-sonnet-4-6 --effort high "x"
```

## Integrações externas

| Adapter | Arquivo |
|---|---|
| Atlassian | `adapters/atlassian.yaml` |
| GitHub | `adapters/github.yaml` |
| GitLab | `adapters/gitlab.yaml` |
| Linear + Notion | `adapters/linear-notion.yaml` |
| Markdown-only | `adapters/markdown-only.yaml` |

Mesmo com integração externa, mantenha ponteiros suficientes em `docs/<slug>/traceability-map.yaml` para reconstruir estado localmente.

## GitHub Issues/Projects

O adapter GitHub usa Issues para entrada e aprovações por comentário/label, Projects v2 para status de board, Pull Requests para review e Actions para evidência de CI. Configure GitHub App como autenticação principal; `GITHUB_TOKEN`/`GH_TOKEN` é fallback para desenvolvimento. O provider usa timeout explícito, retry conservador e tratamento de `429`, configuráveis por `github.request_timeout_ms`, `github.max_attempts` e `github.retry_base_delay_ms`. O bot pode iniciar um receiver HTTP opcional para webhooks GitHub quando `github.webhook.enabled`/porta ou `SDD_GITHUB_WEBHOOK_PORT` estiver configurado.

Registre ponteiros com `sdd artifact link "<orquestração>" github --url <url> --kind issue|project_item|pull_request|action_run --id <id> --stage <stage>`. O Markdown local continua canônico quando o webhook ou o Project v2 estiver parcial.
