Projeto da Full Cycle que mostra, na prática, como construir um software com agentes de código: da ideia à especificação, da especificação aos tickets e dos tickets ao pull request.
A aplicação usada como exemplo é um gerenciador de arquivos na nuvem, no estilo Google Drive, com API em NestJS, frontend em Next.js e banco PostgreSQL. O foco do repositório, porém, não é o produto: é o processo. Os documentos, as regras para os agentes, as skills e as conversas que geraram cada parte do código estão todos aqui.
O brief define nove funcionalidades para o MVP. A Funcionalidade 01, cadastro e login com e-mail e senha, já está desenvolvida: cadastro com verificação de e-mail, entrar e sair, renovação de sessão, recuperação de senha e limite de tentativas. A Funcionalidade 02, upload e download de arquivos, já está especificada e quebrada em tickets, mas ainda não foi implementada. As outras sete ainda não têm spec. A lista completa está em docs/product-brief.md.
Luiz Carlos
| Caminho | O que é |
|---|---|
docs/ |
Os documentos que definem o produto: brief, arquitetura de alto e de baixo nível e design system. |
docs/specs/ |
Cópia das specs e dos tickets do Linear, só para conferência. |
docs/sessoes/ |
As conversas com o agente de código, na íntegra. |
docs/Gerenciador de arquivos.fig |
O arquivo do Figma com o design das telas. |
AGENTS.md |
As regras que os agentes seguem em todo o projeto. |
GLOSSARY.md |
O vocabulário do domínio, usado nas specs e nos tickets. |
apps/api |
A API em NestJS. |
apps/web |
O frontend em Next.js. |
.claude/skills |
As skills usadas para especificar, quebrar em tickets e implementar. |
A pasta docs/sessoes/ guarda as transcrições das sessões do Claude Code que construíram o projeto, em ordem cronológica. Cada arquivo traz as mensagens, as respostas do agente, as chamadas de ferramenta com seus resultados e o trabalho dos subagentes.
Comece pelo índice, que lista as sessões com data, hora e título. Elas seguem a ordem em que o projeto nasceu: documentação, criação dos projetos, design system e, depois, um ticket por sessão.
O agente trabalha ligado a duas ferramentas externas por MCP (Model Context Protocol), sem copiar e colar entre elas.
O Figma é a ferramenta de design do projeto, acessada pelo servidor MCP do plugin figma. O design system nasce nele e é espelhado no código: o agente lê os tokens e os componentes no Figma para implementar as telas e escreve de volta quando o design muda.
docs/design-system.mddefine os tokens, os componentes e o fluxo de trabalho entre o Figma e o código.docs/Gerenciador de arquivos.figé o arquivo do Figma com o design das telas. Para abrir, importe-o no Figma: na tela inicial, use Import e selecione o.fig.
As specs e os tickets vivem no Linear, e não em arquivos do repositório. O agente acessa o Linear pelo servidor MCP linear-server, configurado no .mcp.json: cria a spec de uma funcionalidade, quebra em tickets com as dependências entre eles, pega o próximo ticket liberado e atualiza o andamento.
O caminho da funcionalidade ao ticket e as regras de escrita estão na seção "Issues e tickets no Linear" do AGENTS.md.
A pasta docs/specs/ traz as specs e os tickets das duas primeiras funcionalidades, copiados do Linear, com a situação e as dependências de cada um.
Ela existe só para conferência. Tudo é gerenciado no Linear: é lá que specs e tickets são escritos, alterados e concluídos. A cópia é um retrato tirado em 12/10/2026, para quem lê o repositório sem acesso ao Linear, e não acompanha as mudanças feitas depois. Os agentes de código não a usam; eles leem as issues direto no Linear.
O único pré-requisito é o Docker. Tudo roda dentro dos contêineres do Docker Compose.
# sobe o ambiente (na primeira vez, leva alguns minutos)
docker compose -f compose.dev.yaml up -d --build --wait
# em terminais separados
docker compose -f compose.dev.yaml exec web pnpm dev --hostname 0.0.0.0
docker compose -f compose.dev.yaml exec api pnpm start:dev| Serviço | Endereço |
|---|---|
| Web | http://localhost:3000 |
| API | http://localhost:3001/v1 |
| E-mails capturados | http://localhost:8025 |
Os detalhes do ambiente e os demais comandos estão no AGENTS.md.