Exemplo de SDD — TODO List em Arquitetura Apartada (React + C#) com Spec-Kit¶

# Pré-requisitos comuns
uv --version
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Repositório do back-end
mkdir listaja-api && cd listaja-api
git init
specify init . --integration claude

# Repositório do front-end (em outra pasta, paralelamente)
mkdir listaja-web && cd listaja-web
git init
specify init . --integration claude

listaja-api/
├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   └── ... (templates internos)
├── specs/
└── README.md

listaja-web/
├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   └── ... (templates internos)
├── specs/
└── README.md

# Constitution — listaja-api

## Princípios de Qualidade
- Toda mudança de código passa por revisão de Pull Request.
- Analyzers do .NET ativados; warnings tratados como erros em CI.
- Mensagens de commit seguem Conventional Commits.

## Política de Testes
- xUnit cobrindo Controllers e regras de validação.
- Cobertura mínima de 70% em projeto de testes dedicado.
- Testes de integração com WebApplicationFactory ficam para v2.

## Contrato e Compatibilidade
- A API segue padrão REST: substantivos no plural, verbos HTTP semânticos.
- Operações de escrita devem ser idempotentes quando o método HTTP exigir
  (ex.: PATCH `/complete` aplicado duas vezes não falha).
- Quebras de contrato exigem nova versão (`/api/v2/...`) e nota de migração.

## Performance
- Resposta da API abaixo de 300 ms para listagem de até 500 tarefas.
- Sem N+1 em queries do EF Core; uso explícito de `AsNoTracking` em leituras.

## Restrições do Contexto
- Sem autenticação na v1. Identificação apenas por nome (`OwnerName`).
- Persistência local em SQLite. Sem dependência de serviços de nuvem.
- Datas em UTC no servidor.
- Idioma de mensagens de erro: pt-BR.

# Constitution — listaja-web

## Princípios de Qualidade
- Toda mudança de código passa por revisão de Pull Request.
- ESLint + TypeScript estrito; sem `any` solto no código de produção.
- Mensagens de commit seguem Conventional Commits.

## Política de Testes
- Vitest + Testing Library para componentes-chave (formulário e lista).
- Mock da camada `api/` em testes de componente.
- Testes ponta a ponta com Playwright ficam para v2.

## Acessibilidade e UX
- Foco visível em todos os elementos interativos.
- Inputs com `<label>` associado.
- Feedback imediato em qualquer ação que altere dados.
- Mensagens de erro de rede legíveis em pt-BR; nada de stack trace na tela.

## Performance
- Bundle inicial abaixo de 200 KB gzip.
- Renderização da lista lida com até 500 itens sem travar a aba.

## Restrições do Contexto
- Idioma único: pt-BR.
- Sem dependência de lib de estado externa na v1; `useState`/`useReducer` bastam.
- A URL base da API vem de `VITE_API_BASE_URL`. Nunca usar URL hardcoded.
- O front não conhece detalhes do banco; só conhece o contrato REST documentado.

# Specification — API de Lista de Tarefas

## Contexto
A `listaja-api` expõe operações sobre tarefas pessoais.
Cada tarefa pertence a um único `OwnerName` (string simples).
Esta API é consumida por clientes externos (web, e potencialmente mobile/CLI).

## User Stories (perspectiva do cliente da API)

### US-A1 — Criar tarefa
Como cliente da API, quero enviar um POST com título, prazo opcional e dono,
para que uma nova tarefa seja persistida e devolvida com `id` e `createdAt`.

### US-A2 — Listar tarefas de um dono
Como cliente da API, quero enviar um GET filtrado por `owner`,
para receber todas as tarefas daquele dono em ordem de criação decrescente.

### US-A3 — Marcar como concluída
Como cliente da API, quero enviar um PATCH `/{id}/complete`,
para alterar o estado da tarefa para concluída de forma idempotente.

### US-A4 — Excluir tarefa
Como cliente da API, quero enviar um DELETE `/{id}`,
para remover a tarefa do banco em definitivo.

## Contratos (resumidos)

| Método | Rota                              | Status sucesso | Status erro                  |
|--------|-----------------------------------|----------------|------------------------------|
| GET    | /api/todos?owner={nome}           | 200            | 400 owner ausente            |
| POST   | /api/todos                        | 201            | 400 título inválido          |
| PATCH  | /api/todos/{id}/complete          | 200            | 404 id inexistente           |
| DELETE | /api/todos/{id}                   | 204            | 404 id inexistente           |

## Regras de Negócio do Servidor
- `Title` é obrigatório, com 1 a 200 caracteres após `Trim()`.
- `DueDate`, quando presente, é uma data válida (sem componente de hora).
- `OwnerName` é obrigatório, máximo 80 caracteres.
- Ordem padrão de listagem: `CreatedAt` decrescente.
- Datas armazenadas em UTC.
- Concluir uma tarefa já concluída retorna 200 sem alterar `CreatedAt`.

## Fora de Escopo
- Autenticação ou criação de conta.
- Edição de tarefa existente (apenas concluir/excluir).
- Compartilhamento entre `OwnerName` distintos.
- Notificação de prazo.

# Specification — Interface do ListaJá

## Contexto
A `listaja-web` é a interface web do ListaJá.
Consome a API REST do `listaja-api` (contrato em listaja-api/specs/001-todo-api/spec.md).
Cada usuário se identifica digitando um nome curto na própria tela; não há login.

## User Stories (perspectiva do usuário final)

### US-W1 — Identificar-se
Como usuário da interface, quero digitar meu nome em um campo,
para que a aplicação carregue minhas tarefas correspondentes.

### US-W2 — Criar tarefa
Como usuário da interface, quero preencher um campo de texto e, opcionalmente,
um prazo, e clicar em "Adicionar", para registrar uma nova tarefa.

### US-W3 — Ver minha lista
Como usuário da interface, quero ver minhas tarefas em uma lista única,
com indicação visual diferente para concluídas e em aberto.

### US-W4 — Concluir tarefa
Como usuário da interface, quero clicar em "Concluir" numa tarefa em aberto,
para que ela passe a aparecer riscada.

### US-W5 — Excluir tarefa
Como usuário da interface, quero clicar em "Excluir" numa tarefa,
para removê-la da lista de forma definitiva.

## Critérios de UX
- Feedback visual imediato após cada ação que altera dados.
- Estados de carregamento (`loading`) para listagem inicial.
- Mensagem amigável quando a API estiver fora do ar
  ("Não foi possível conectar ao servidor. Tente novamente.").
- A tela cabe sem rolagem horizontal em telas a partir de 360 px.
- Foco visível em inputs e botões; rótulos associados via `<label>`.

## O que é responsabilidade do back (e este spec NÃO repete)
- Tamanho máximo do título (validado também aqui por usabilidade,
  mas a regra autoritativa vive em listaja-api/specs/001-todo-api/spec.md).
- Ordem padrão da lista (vem pronta da API).
- Persistência em si.

## Fora de Escopo
- Autenticação.
- Edição de tarefa existente.
- Notificações de prazo.
- Modo offline.

## Clarifications — listaja-api

### Q1. Tarefas excluídas devem ir para uma lixeira (soft delete) ou ser apagadas em definitivo?
Resposta do time: hard delete. Lixeira ficaria para uma versão futura.

### Q2. Qual a ordem padrão da listagem retornada pelo GET?
Resposta do time: por `CreatedAt` decrescente. Concluídas e em aberto na mesma resposta.

### Q3. Há limite de caracteres para o `Title`?
Resposta do time: sim, 1 a 200 caracteres após Trim. Validação no servidor.

## Clarifications — listaja-web

### Q1. Erro de rede: feedback inline (perto do botão) ou toast no topo?
Resposta do time: inline, com `role="alert"`, perto do elemento que disparou a ação.

### Q2. Antes de excluir uma tarefa, pedimos confirmação?
Resposta do time: não na v1. Excluir é direto. Anotado como possível ajuste após uso real.

### Q3. A ordem das tarefas na tela respeita a ordem da API ou o usuário pode reordenar?
Resposta do time: apenas a ordem da API. Reordenação manual fica para v2.

# Plan — listaja-api

## Arquitetura interna
ASP.NET Core 8 Web API expondo controllers REST.
Persistência local com SQLite acessado por Entity Framework Core.

## Modelo de Dados

Entidade `TodoItem`:

| Campo      | Tipo            | Observações                   |
|------------|-----------------|-------------------------------|
| Id         | Guid            | Chave primária                |
| Title      | string (<=200)  | Texto da tarefa               |
| DueDate    | DateTime?       | Prazo opcional, apenas data   |
| Done       | bool            | Indica conclusão              |
| OwnerName  | string (<=80)   | Nome do dono da tarefa        |
| CreatedAt  | DateTime        | Definido no servidor (UTC)    |

## Contratos REST

| Método | Rota                              | Body / Query                      |
|--------|-----------------------------------|-----------------------------------|
| GET    | /api/todos?owner={nome}           | query string                      |
| POST   | /api/todos                        | { title, dueDate?, ownerName }    |
| PATCH  | /api/todos/{id}/complete          | sem body                          |
| DELETE | /api/todos/{id}                   | sem body                          |

## Camadas
Controllers -> DbContext (EF Core) -> SQLite.
A camada de Services foi descartada para a v1: as regras são tão simples
que residiriam vazias entre Controller e DbContext.

## Estrutura de Pastas

## Decisões Técnicas
- SQLite por simplicidade local; troca para Postgres ficaria como ajuste futuro.
- CORS liberado **explicitamente** para `http://localhost:5173` (porta padrão do Vite).
- Migrations por `EnsureCreated` na v1 (script único). EF Migrations entram quando
  o schema começar a evoluir.
- Datas em UTC; conversão para fuso local é responsabilidade do cliente.

# Plan — listaja-web

## Arquitetura interna
SPA em React 18 + Vite + TypeScript. Camadas:
- `api/` — funções tipadas que falam HTTP com `listaja-api`.
- `components/` — componentes de UI puros, sem chamadas HTTP diretas.
- `hooks/` — composição de estado quando necessário (não há na v1).
- `App.tsx` — orquestração e estado de alto nível.

## Configuração de ambiente

A URL base da API vem da variável `VITE_API_BASE_URL`, lida via `import.meta.env`.

Nenhum arquivo do código deve conter a URL da API hardcoded.

## Estrutura de Pastas

## Decisões Técnicas
- Sem lib de estado externa: `useState`/`useEffect` cobrem o necessário.
- Tipos do `TodoItem` declarados localmente em `src/api/todos.ts`,
  espelhando o contrato descrito em listaja-api/specs/001-todo-api/spec.md.
- Tratamento de erro: `try/catch` por chamada, com mensagem amigável em pt-BR.
- O nome do usuário é guardado em `localStorage` (chave `listaja:owner`)
  para sobreviver a recargas; sem cookies, sem auth.

namespace ListaJa.Api.Models;

public class TodoItem
{
    public Guid Id { get; set; } = Guid.NewGuid();
    public string Title { get; set; } = string.Empty;
    public DateTime? DueDate { get; set; }
    public bool Done { get; set; }
    public string OwnerName { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}

using Microsoft.EntityFrameworkCore;
using ListaJa.Api.Models;

namespace ListaJa.Api.Data;

public class TodoDbContext : DbContext
{
    public TodoDbContext(DbContextOptions<TodoDbContext> options) : base(options) { }

    public DbSet<TodoItem> Todos => Set<TodoItem>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<TodoItem>(e =>
        {
            e.HasKey(t => t.Id);
            e.Property(t => t.Title).IsRequired().HasMaxLength(200);
            e.Property(t => t.OwnerName).IsRequired().HasMaxLength(80);
        });
    }
}

using Microsoft.EntityFrameworkCore;
using ListaJa.Api.Data;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<TodoDbContext>(opt =>
    opt.UseSqlite("Data Source=todo.db"));

builder.Services.AddCors(opt =>
    opt.AddDefaultPolicy(p => p
        .WithOrigins("http://localhost:5173")
        .AllowAnyHeader()
        .AllowAnyMethod()));

builder.Services.AddControllers();

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<TodoDbContext>();
    db.Database.EnsureCreated();
}

app.UseCors();
app.MapControllers();
app.Run();

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using ListaJa.Api.Data;
using ListaJa.Api.Models;

namespace ListaJa.Api.Controllers;

public record CreateTodoDto(string Title, DateTime? DueDate, string OwnerName);

[ApiController]
[Route("api/[controller]")]
public class TodosController : ControllerBase
{
    private readonly TodoDbContext _db;

    public TodosController(TodoDbContext db) => _db = db;

    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItem>>> List([FromQuery] string owner)
    {
        if (string.IsNullOrWhiteSpace(owner)) return BadRequest("owner é obrigatório");
        var items = await _db.Todos
            .Where(t => t.OwnerName == owner)
            .OrderByDescending(t => t.CreatedAt)
            .AsNoTracking()
            .ToListAsync();
        return Ok(items);
    }

    [HttpPost]
    public async Task<ActionResult<TodoItem>> Create([FromBody] CreateTodoDto dto)
    {
        var title = (dto.Title ?? string.Empty).Trim();
        if (title.Length == 0 || title.Length > 200)
            return BadRequest("título inválido");
        var owner = (dto.OwnerName ?? string.Empty).Trim();
        if (owner.Length == 0 || owner.Length > 80)
            return BadRequest("ownerName inválido");

        var item = new TodoItem
        {
            Title = title,
            DueDate = dto.DueDate,
            OwnerName = owner
        };
        _db.Todos.Add(item);
        await _db.SaveChangesAsync();
        return CreatedAtAction(nameof(List), new { owner = item.OwnerName }, item);
    }

    [HttpPatch("{id:guid}/complete")]
    public async Task<ActionResult<TodoItem>> Complete(Guid id)
    {
        var item = await _db.Todos.FindAsync(id);
        if (item is null) return NotFound();
        item.Done = true;
        await _db.SaveChangesAsync();
        return Ok(item);
    }

    [HttpDelete("{id:guid}")]
    public async Task<IActionResult> Delete(Guid id)
    {
        var item = await _db.Todos.FindAsync(id);
        if (item is null) return NotFound();
        _db.Todos.Remove(item);
        await _db.SaveChangesAsync();
        return NoContent();
    }
}

VITE_API_BASE_URL=http://localhost:5080

VITE_API_BASE_URL=https://api.listaja.example

export interface TodoItem {
  id: string;
  title: string;
  dueDate: string | null;
  done: boolean;
  ownerName: string;
  createdAt: string;
}

export interface CreateTodoInput {
  title: string;
  dueDate: string | null;
  ownerName: string;
}

const BASE_URL: string = import.meta.env.VITE_API_BASE_URL as string;
const TODOS_URL = `${BASE_URL}/api/todos`;

async function parseOrThrow<T>(res: Response, errorMsg: string): Promise<T> {
  if (!res.ok) throw new Error(errorMsg);
  return (await res.json()) as T;
}

export async function listTodos(owner: string): Promise<TodoItem[]> {
  const res = await fetch(`${TODOS_URL}?owner=${encodeURIComponent(owner)}`);
  return parseOrThrow<TodoItem[]>(res, "Falha ao listar tarefas");
}

export async function createTodo(input: CreateTodoInput): Promise<TodoItem> {
  const res = await fetch(TODOS_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(input),
  });
  return parseOrThrow<TodoItem>(res, "Falha ao criar tarefa");
}

export async function completeTodo(id: string): Promise<TodoItem> {
  const res = await fetch(`${TODOS_URL}/${id}/complete`, { method: "PATCH" });
  return parseOrThrow<TodoItem>(res, "Falha ao concluir tarefa");
}

export async function deleteTodo(id: string): Promise<void> {
  const res = await fetch(`${TODOS_URL}/${id}`, { method: "DELETE" });
  if (!res.ok) throw new Error("Falha ao excluir tarefa");
}

import { useState, FormEvent } from "react";
import { createTodo, TodoItem } from "../api/todos";

interface Props {
  ownerName: string;
  onCreated: (item: TodoItem) => void;
}

export function TodoForm({ ownerName, onCreated }: Props) {
  const [title, setTitle] = useState<string>("");
  const [dueDate, setDueDate] = useState<string>("");
  const [error, setError] = useState<string | null>(null);
  const [submitting, setSubmitting] = useState<boolean>(false);

  async function handleSubmit(e: FormEvent<HTMLFormElement>): Promise<void> {
    e.preventDefault();
    setError(null);
    const trimmed = title.trim();
    if (trimmed.length === 0 || trimmed.length > 200) {
      setError("Texto deve ter entre 1 e 200 caracteres.");
      return;
    }
    setSubmitting(true);
    try {
      const created = await createTodo({
        title: trimmed,
        dueDate: dueDate ? dueDate : null,
        ownerName,
      });
      onCreated(created);
      setTitle("");
      setDueDate("");
    } catch (err) {
      setError((err as Error).message);
    } finally {
      setSubmitting(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Nova tarefa
        <input
          type="text"
          value={title}
          maxLength={200}
          onChange={(e) => setTitle(e.target.value)}
        />
      </label>
      <label>
        Prazo
        <input
          type="date"
          value={dueDate}
          onChange={(e) => setDueDate(e.target.value)}
        />
      </label>
      <button type="submit" disabled={submitting}>
        {submitting ? "Adicionando..." : "Adicionar"}
      </button>
      {error && <p role="alert">{error}</p>}
    </form>
  );
}

import { TodoItem, completeTodo, deleteTodo } from "../api/todos";

interface Props {
  items: TodoItem[];
  onChanged: (item: TodoItem) => void;
  onDeleted: (id: string) => void;
}

export function TodoList({ items, onChanged, onDeleted }: Props) {
  async function handleComplete(id: string): Promise<void> {
    const updated = await completeTodo(id);
    onChanged(updated);
  }

  async function handleDelete(id: string): Promise<void> {
    await deleteTodo(id);
    onDeleted(id);
  }

  if (items.length === 0) {
    return <p>Nenhuma tarefa por aqui.</p>;
  }

  return (
    <ul>
      {items.map((t) => (
        <li key={t.id}>
          <span style={{ textDecoration: t.done ? "line-through" : "none" }}>
            {t.title}
            {t.dueDate ? ` (até ${t.dueDate.slice(0, 10)})` : ""}
          </span>
          {!t.done && (
            <button onClick={() => handleComplete(t.id)}>Concluir</button>
          )}
          <button onClick={() => handleDelete(t.id)}>Excluir</button>
        </li>
      ))}
    </ul>
  );
}

import { useEffect, useState } from "react";
import { listTodos, TodoItem } from "./api/todos";
import { TodoForm } from "./components/TodoForm";
import { TodoList } from "./components/TodoList";

const OWNER_KEY = "listaja:owner";

export default function App() {
  const [ownerName, setOwnerName] = useState<string>(
    () => localStorage.getItem(OWNER_KEY) ?? ""
  );
  const [items, setItems] = useState<TodoItem[]>([]);
  const [loading, setLoading] = useState<boolean>(false);
  const [networkError, setNetworkError] = useState<string | null>(null);

  useEffect(() => {
    if (!ownerName) {
      setItems([]);
      return;
    }
    localStorage.setItem(OWNER_KEY, ownerName);
    setLoading(true);
    setNetworkError(null);
    listTodos(ownerName)
      .then(setItems)
      .catch(() =>
        setNetworkError(
          "Não foi possível conectar ao servidor. Tente novamente."
        )
      )
      .finally(() => setLoading(false));
  }, [ownerName]);

  function handleCreated(item: TodoItem): void {
    setItems((prev) => [item, ...prev]);
  }

  function handleChanged(item: TodoItem): void {
    setItems((prev) => prev.map((t) => (t.id === item.id ? item : t)));
  }

  function handleDeleted(id: string): void {
    setItems((prev) => prev.filter((t) => t.id !== id));
  }

  return (
    <main>
      <h1>ListaJá</h1>
      <label>
        Seu nome:
        <input
          type="text"
          value={ownerName}
          onChange={(e) => setOwnerName(e.target.value)}
        />
      </label>
      {ownerName && (
        <>
          <TodoForm ownerName={ownerName} onCreated={handleCreated} />
          {loading && <p>Carregando...</p>}
          {networkError && <p role="alert">{networkError}</p>}
          <TodoList
            items={items}
            onChanged={handleChanged}
            onDeleted={handleDeleted}
          />
        </>
      )}
    </main>
  );
}

# Terminal 1 — back
cd listaja-api/src/ListaJa.Api
dotnet run --urls=http://localhost:5080

# Terminal 2 — front
cd listaja-web
npm install
npm run dev   # sobe em http://localhost:5173

# 1. Pré-requisitos
#    - uv (https://docs.astral.sh/uv/)
#    - .NET 8 SDK
#    - Node.js 20+

# 2. Instalar o Spec-Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 3. Criar o repositório do back e iniciar o spec-kit
mkdir listaja-api && cd listaja-api
git init
specify init . --integration claude

# Dentro do agente do listaja-api, rodar as 6 fases na ordem:
#    /speckit.constitution
#    /speckit.specify
#    /speckit.clarify
#    /speckit.plan
#    /speckit.tasks
#    /speckit.implement

# 4. Criar o repositório do front (em outra pasta, paralelamente)
cd ..
mkdir listaja-web && cd listaja-web
git init
specify init . --integration claude

# Dentro do agente do listaja-web, rodar as mesmas 6 fases na ordem.

# 5. Antes de "implement" em qualquer um dos lados, revisem juntos
#    os pontos de sincronização da Seção 8.3 (S01–S04). Esse é o
#    momento de descobrir contratos divergentes — não em runtime.

# 6. Subir os dois serviços localmente
cd ../listaja-api/src/ListaJa.Api
dotnet run --urls=http://localhost:5080

# em outro terminal
cd ../../listaja-web
npm install
npm run dev