💻 Guia Completo: Implementação de Projetos

Ponto-chave

Todo o planejamento (especificação, plano técnico, tarefas e estimativa) já foi realizado pelo time comercial usando o Agente SpecForge no CFly. O time de dev recebe os artefatos prontos e foca na implementação. Ajustes pontuais nos artefatos podem ser necessários, mas o fluxo principal começa com /specforge.implement.

Visão Geral do Fluxo

graph LR
    subgraph "Receber"
        A["📦 Artefatos<br/><small>specs, plans, tasks</small>"]
    end
    subgraph "Preparar"
        B["🔧 specforge init<br/><small>+ setup-ai all</small>"]
    end
    subgraph "Implementar"
        C["⚡ Para cada feature:<br/><small>Revisar → Analyze → Implement → PR</small>"]
    end
    subgraph "Entregar"
        D["🚀 Deploy<br/><small>+ Entrega</small>"]
    end
    A --> B --> C --> D

Suas 3 Ferramentas Principais

🛠️ SpecForge

Comandos SDD na IDE — gera planos, tarefas, análise, estimativa.

Quando usar: Setup do projeto, planejamento técnico, geração de tarefas

🤖 Devin.ai

Agente de IA autônomo que implementa features completas.

Quando usar: Implementação de features, criação de PRs, correção de bugs

💡 Claude Code

Assistente de IA na IDE para codificação interativa.

Quando usar: Revisão de código, debugging, refatoração, tarefas pontuais

Etapa 0: Instalação do SpecForge CLI

Instale o CLI antes de qualquer passo (requer Node.js ≥ 18):

curl -sSL https://specforge.apdigitalservices.com.br/install.sh | bash

Verifique com specforge --version. Para instalar uma versão específica: curl -sSL https://specforge.apdigitalservices.com.br/install.sh | bash -s -- --version 0.10.6

Etapa 1: Recebendo os Artefatos do Time de Vendas

Quando o cliente assina o contrato, você recebe um pacote completo de artefatos gerado pelo time comercial usando o Agente SpecForge no CFly. Isso significa que as etapas de especificação (/specforge.specify), planejamento (/specforge.plan), geração de tarefas (/specforge.tasks) e estimativa (/specforge.estimate) já foram realizadas. Seu trabalho começa pela implementação.

Estrutura dos artefatos recebidos

projeto/
├── constitution.md                     # Princípios e regras do projeto
├── architectural-decisions.md          # Decisões de infraestrutura
├── specs/
│   ├── estimate.md                     # Estimativa (cronograma + roadmap)
│   ├── 001-cadastro-alunos/
│   │   ├── spec.md                     # Especificação da feature
│   │   ├── test-scenarios.md           # Cenários de teste
│   │   ├── plan.md                     # Plano de implementação
│   │   ├── tasks.md                    # Tarefas decompostas
│   │   └── checklists/
│   │       └── requirements.md         # Validação de requisitos
│   ├── 002-treinos/
│   │   └── ...
│   └── 003-aulas-coletivas/
│       └── ...
└── .specforge.yaml                     # Configuração do projeto

O que revisar primeiro

Documento	O que verificar	Prioridade
constitution.md	Princípios do projeto, restrições, padrões de qualidade	🔴 Alta
estimate.md	Roadmap de sprints, alocação de tarefas, marcos	🔴 Alta
spec.md (por feature)	Histórias de usuário, requisitos funcionais, edge cases	🔴 Alta
tasks.md (por feature)	Tarefas ordenadas, dependências, marcadores `[P]` de paralelismo	🔴 Alta
plan.md (por feature)	Stack técnica, modelo de dados, contratos de API	🟡 Média
test-scenarios.md	Cenários de teste para cada história de usuário	🟡 Média

Importante

Os artefatos já passaram por revisão do time comercial, mas podem precisar de ajustes pontuais do ponto de vista técnico. Se encontrar problemas (requisitos vagos, tarefas incompletas, inconsistências), use /specforge.analyze para identificar issues automaticamente e comunique ao time comercial se necessário.

Etapa 2: Preparação do Ambiente

2.1 — Inicialização do projeto com SpecForge

# Instalar o SpecForge (se ainda não tiver — veja Etapa 0)
# curl -sSL https://specforge.apdigitalservices.com.br/install.sh | bash

# Criar diretório do projeto
mkdir healthtrack-pro && cd healthtrack-pro

# Inicializar o projeto (interativo)
specforge init
# > Nome: HealthTrack Pro
# > Stack: web-nestjs (ou a stack definida nos artefatos)
# > Diretório de specs: specs/

2.2 — Implantação dos comandos SDD na IDE

# Implanta os 10 comandos SDD em todas as IDEs suportadas
specforge setup-ai all

Isso cria os comandos slash em:

.claude/commands/          # Claude Code
.cursor/commands/          # Cursor
.github/agents/            # GitHub Copilot

2.3 — Copiar os artefatos recebidos

Copie os artefatos do time de vendas para o diretório specs/ do projeto recém-criado. A constitution.md vai na raiz do projeto.

2.4 — Configurar as ferramentas de IA

🤖 Devin.ai

Conecte o repositório do projeto ao Devin.ai
Configure os secrets necessários (API keys, banco de dados, etc.)
Configure o MCP do SpecForge (se disponível) para acesso aos artefatos

💡 Claude Code

Abra o projeto na IDE (VS Code / Cursor)
Verifique que os comandos /specforge.* estão disponíveis
O Claude Code terá acesso a todos os artefatos via contexto do projeto

Etapa 3: Fluxo de Implementação por Feature

Fluxo direto

Como todo o planejamento já foi feito pelo time comercial, o fluxo do dev é direto: revisar brevemente os artefatos da feature e partir para a implementação com /specforge.implement.

O SpecForge usa um workflow de branch por feature. Cada funcionalidade vive em sua própria branch Git, isolando o trabalho e permitindo desenvolvimento paralelo.

main (constitution, setup do projeto)
 ├── 001-cadastro-alunos     (feature branch)
 ├── 002-treinos             (feature branch)
 └── 003-aulas-coletivas     (feature branch)

Ciclo de vida de cada feature

graph LR
    A["1. REVISAR<br/><small>spec + plan + tasks<br/>(já feitos pelo<br/>time comercial)</small>"] --> B["2. IMPLEMENTAR<br/><small>/specforge.implement<br/>Devin.ai / Claude Code</small>"]
    B --> C["3. VALIDAR<br/><small>Code review<br/>Testes passando<br/>Spec compliance</small>"]
    C --> D["4. ENTREGAR<br/><small>Merge PR<br/>Marcar tarefas<br/>como concluídas</small>"]

3.1 — Revisar artefatos (revisão rápida)

Os artefatos (spec.md, plan.md, tasks.md) já foram criados e revisados pelo time comercial. Sua revisão aqui é rápida e pontual — foque em validar que a stack técnica, modelo de dados e tarefas fazem sentido do ponto de vista de implementação.

O que já vem pronto do time comercial

Artefato	Gerado por	Seu papel
`spec.md`	`/specforge.specify` (comercial)	Leitura rápida — entender requisitos
`plan.md`	`/specforge.plan` (comercial)	Validar stack e modelo de dados
`tasks.md`	`/specforge.tasks` (comercial)	Verificar se as tarefas cobrem os requisitos
`test-scenarios.md`	`/specforge.specify` (comercial)	Referência para testes
`estimate.md`	`/specforge.estimate` (comercial)	Verificar sprint e prazos

Quando re-executar comandos de planejamento

Na maioria dos casos, você NÃO precisa re-executar

/specforge.plan ou /specforge.tasks — eles já foram feitos. Porém, se identificar problemas técnicos significativos:
# Apenas se necessário — ajustar o plano técnico
/specforge.plan

Ajuste: trocar o ORM de TypeORM para Prisma por questões de performance.
# Apenas se necessário — regenerar tarefas após mudança no plano
/specforge.tasks

Verificar consistência (recomendado)

/specforge.analyze

Rode antes de implementar como pre-flight check. Reporta issues por severidade:

Severidade	Ação
🚫 CRITICAL	Bloqueia implementação — resolver antes
🟠 HIGH	Resolver antes de implementar
🟡 MEDIUM	Resolver durante a implementação
🔵 LOW	Melhorias opcionais

3.2 — Implementar: O passo principal do dev

Opção A: Devin.ai — Implementação autônoma

Ideal para: Features completas, tarefas bem definidas, fases inteiras do tasks.md

O Devin.ai lê os artefatos e implementa as tarefas autonomamente:

Lê tasks.md, plan.md, data-model.md, contracts/
Cria a branch da feature (001-cadastro-alunos)
Implementa fase por fase, seguindo a ordem do tasks.md
Marca cada tarefa concluída como [X]
Faz commits regulares por fase
Cria o Pull Request automaticamente

Como usar — envie um prompt ao Devin:

Implemente a feature 001-cadastro-alunos do projeto HealthTrack Pro.

Artefatos disponíveis em specs/001-cadastro-alunos/:
- spec.md (especificação)
- plan.md (plano técnico)
- tasks.md (tarefas ordenadas)
- data-model.md (modelo de dados)
- contracts/ (contratos de API)

Siga o tasks.md fase por fase. Use NestJS com TypeORM e PostgreSQL.
Faça commits por fase e crie um PR ao final.

Dicas para usar o Devin.ai:

Prática	Por que
Indique os caminhos exatos dos artefatos	O Devin precisa saber onde encontrar as specs
Especifique a stack e bibliotecas	Evita que o Devin escolha tecnologias diferentes
Peça commits por fase	Facilita code review incremental
Revise o PR com atenção	O Devin implementa rápido, mas o review é seu

Opção B: Claude Code — Implementação interativa na IDE

Ideal para: Tarefas específicas, debugging, refatoração, ajustes finos

O Claude Code trabalha diretamente na sua IDE. Use os comandos SpecForge integrados:

/specforge.implement

O comando:

Verifica que você está na branch da feature
Carrega todos os artefatos (tasks, plan, data-model, contracts)
Implementa tarefa por tarefa, pedindo sua aprovação
Marca tarefas concluídas no tasks.md
Faz commits por fase

Quando preferir o Claude Code ao Devin:

Cenário	Ferramenta
Feature completa, bem especificada	Devin.ai
Tarefa pontual ou ajuste	Claude Code
Debugging de código existente	Claude Code
Refatoração	Claude Code
Implementação que exige decisões frequentes	Claude Code
Feature com muitas dependências externas	Claude Code (você controla o ambiente)

Opção C: Combinação Devin + Claude Code

A abordagem mais eficiente para features complexas:

graph TD
    A["🤖 Devin.ai<br/>Setup + Foundation<br/>(Phases 1-2)"] --> B["🤖 Devin.ai<br/>User Stories<br/>(Phases 3-N)"]
    B --> C["💡 Claude Code<br/>Code Review + Fixes<br/>Refatoração<br/>Edge cases<br/>Testes adicionais"]

Devin.ai implementa as fases principais (setup, fundação, user stories)
Claude Code faz code review, corrige edge cases, adiciona testes, refatora

3.3 — Validar: Code Review e Qualidade

Após a implementação, valide:

Checklist de validação

Todos os testes passam

tasks.md tem todas as tarefas marcadas como [X]

Code review feito (por humano ou com Claude Code)

Nenhum violation da constitution.md

API contracts aderem ao contracts/*.yaml

Modelo de dados alinhado com data-model.md

Edge cases dos test-scenarios.md cobertos

Rodar análise de consistência pós-implementação

/specforge.analyze

Verifique que:

Cobertura de requisitos > 95%
Zero issues CRITICAL
Todos os requisitos do spec.md tem tarefas correspondentes

3.4 — Entregar: Merge e Próximo Sprint

Merge o PR da feature branch para main
Atualize o status no roadmap de sprints (estimate.md)
Passe para a próxima feature do sprint

Etapa 4: Gerenciando Sprints com o Roadmap

O estimate.md contém um roadmap detalhado de sprints. Use-o como guia para o planejamento:

Exemplo de roadmap

Sprint 1  |████ Setup + Fundação              |
Sprint 2  |████ Cadastro + Pagamentos         |████ Treinos (início)  |
Sprint 3  |████ Treinos (fim)                 |████ Aulas Coletivas   |
Sprint 4  |████ Polish + QA + UAT             |
          ──────────────────────────────────────────────────────────
          MVP ▲                                Beta ▲    Lançamento ▲

Distribuição de trabalho por sprint

Sprint	🤖 Devin.ai	💡 Claude Code	👤 Dev humano
Sprint 1	Setup do projeto, migrations, configs	Revisar arquitetura, ajustar configs	Validar decisões técnicas
Sprint 2	Implementar US1-US2 completas	Fixes de code review, edge cases	Code review, testes manuais
Sprint 3	Implementar US3-US4	Integração entre features, debugging	QA, testes de integração
Sprint 4	Rate limiting, error handling, tracing	Refatoração final, otimização	UAT com cliente, deploy

Etapa 5: Criando Issues no GitHub

Para rastrear o progresso no GitHub:

/specforge.taskstoissues

Isso cria uma issue por tarefa com:

🏷️ Labels por fase (setup, foundation, feature, polish)
🏷️ Labels por user story (US-1, US-2)
🚩 Milestone por feature
🔗 Links de dependência entre issues
📝 Descrição com contexto e caminhos de arquivos

Alternativa — Azure DevOps: Use /specforge.taskstoazure para criar Sprints, PBIs, Tasks e cenários de teste no Azure DevOps. Configure azureDevOps em .specforge.yaml e o Azure DevOps MCP; specforge setup-ai cursor (ou all) adiciona o MCP em .cursor/mcp.json.

Referência Rápida dos Comandos SDD

Eu quero…	Comando	Onde rodar
Criar a constitution do projeto	`/specforge.constitution`	Na branch `main`
Especificar uma nova feature	`/specforge.specify`	Na branch `main` (cria a feature branch)
Resolver ambiguidades na spec	`/specforge.clarify`	Na feature branch
Criar o plano técnico	`/specforge.plan`	Na feature branch
Gerar tarefas	`/specforge.tasks`	Na feature branch
Criar checklists de qualidade	`/specforge.checklist`	Na feature branch
Verificar consistência	`/specforge.analyze`	Na feature branch
Implementar as tarefas	`/specforge.implement`	Na feature branch
Criar issues no GitHub	`/specforge.taskstoissues`	Na feature branch
Criar itens no Azure DevOps (Sprints, PBIs, Tasks, Test Cases)	`/specforge.taskstoazure`	Qualquer branch (requer Azure DevOps MCP e `azureDevOps` em `.specforge.yaml`)
Gerar estimativa do projeto	`/specforge.estimate`	Qualquer branch

Boas Práticas

🔀 Commits e branches

Prática	Detalhes
Uma branch por feature	Branch `001-cadastro-alunos` → dir `specs/001-cadastro-alunos/`
Commits por fase	`feat(cadastro-alunos): implement Phase 1 - Setup`
PR para merge	Sempre via Pull Request com code review
Nunca commitar direto na main	Toda implementação via feature branch

🤖 Usando Devin.ai

Prática	Detalhes
Forneça todos os artefatos relevantes no prompt	`spec.md`, `plan.md`, `tasks.md`, `data-model.md`, `contracts/`
Especifique a stack e bibliotecas	`NestJS + TypeORM + PostgreSQL + Redis + BullMQ`
Peça commits por fase	Facilita review incremental
Quebre features grandes em sub-tarefas	Cada sessão do Devin com escopo claro
Revise PRs antes de mergear	O Devin implementa rápido, mas o review humano é essencial

💡 Usando Claude Code

Prática	Detalhes
Use os comandos `/specforge.*` integrados	Já tem todo o contexto do projeto
Peça explicações quando não entender o código	Claude Code é ótimo para aprendizado
Use para debugging e investigação	Mais interativo que o Devin para problemas pontuais
Combine com `/specforge.analyze` após mudanças	Garante consistência dos artefatos

Checklist de Entrega de Sprint

Verifique ao final de cada sprint

Qualidade

Todos os testes passam (unitários + integração)

/specforge.analyze sem issues CRITICAL ou HIGH

Code review feito em todos os PRs

Constitution.md respeitada (LGPD, performance, etc.)

Artefatos

tasks.md atualizado (tarefas concluídas marcadas [X])

PRs mergeados na main

Issues no GitHub atualizadas

Comunicação

Demo preparada para o cliente (baseada nos marcos do roadmap)

Bloqueios documentados e comunicados

Próximo sprint planejado com base no roadmap

Resolução de Problemas Comuns

Problema	Solução
Spec incompleta ou ambígua	Execute `/specforge.clarify` para resolver
Tarefas faltando no `tasks.md`	Re-execute `/specforge.tasks`
Inconsistência entre spec e plano	Execute `/specforge.analyze` e corrija
Devin gerando código fora do padrão	Inclua `constitution.md` e `best-practices.md` no prompt
Devin escolhendo stack errada	Especifique a stack explicitamente no prompt
Feature mais complexa que o previsto	Re-execute `/specforge.estimate` com os artefatos atualizados
Conflito entre branches de features	Merge `main` na feature branch regularmente

Resumo do Fluxo Completo

Fluxo de ponta a ponta

Receber artefatos do time de vendas (specs, plans, tasks)

Configurar ambiente (specforge init + setup-ai)

Para cada feature no sprint:

a. Revisar artefatos (spec, plan, tasks)

b. Rodar /specforge.analyze (pre-flight check)

c. Implementar com Devin.ai e/ou Claude Code

d. Code review + testes

e. Merge PR

Ao final do sprint:

a. Validar entrega contra o roadmap

b. Preparar demo para o cliente

c. Planejar próximo sprint

💻 Guia Completo: Implementação de Projetos

Para o Time de Desenvolvimento da AP Digital Services

Visão Geral do Fluxo

Suas 3 Ferramentas Principais

🛠️ SpecForge

🤖 Devin.ai

💡 Claude Code

Etapa 0: Instalação do SpecForge CLI

Etapa 1: Recebendo os Artefatos do Time de Vendas

Estrutura dos artefatos recebidos

O que revisar primeiro

Etapa 2: Preparação do Ambiente

2.1 — Inicialização do projeto com SpecForge

2.2 — Implantação dos comandos SDD na IDE

2.3 — Copiar os artefatos recebidos

2.4 — Configurar as ferramentas de IA

🤖 Devin.ai

💡 Claude Code

Etapa 3: Fluxo de Implementação por Feature

Ciclo de vida de cada feature

3.1 — Revisar artefatos (revisão rápida)

O que já vem pronto do time comercial

Quando re-executar comandos de planejamento

Verificar consistência (recomendado)

3.2 — Implementar: O passo principal do dev

Opção A: Devin.ai — Implementação autônoma

Opção B: Claude Code — Implementação interativa na IDE

Opção C: Combinação Devin + Claude Code

3.3 — Validar: Code Review e Qualidade

Rodar análise de consistência pós-implementação

3.4 — Entregar: Merge e Próximo Sprint

Etapa 4: Gerenciando Sprints com o Roadmap

Exemplo de roadmap

Distribuição de trabalho por sprint

Etapa 5: Criando Issues no GitHub

Referência Rápida dos Comandos SDD

Boas Práticas

🔀 Commits e branches

🤖 Usando Devin.ai

💡 Usando Claude Code

Checklist de Entrega de Sprint

Resolução de Problemas Comuns

Resumo do Fluxo Completo