convez.ai
AgenteDesenvolvimento WebIntermediário
robertourias

Scaffold IA — Contexto Persistente para Agentes

robertourias/scaffold-ia-projetos

Memória persistente para agentes IA em stack fullstack JavaScript/TypeScript

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework agnóstico para estruturar contexto de projetos Next.js + NestJS com papéis de agentes, fluxo spec-driven e padrões de código. Compatível com Claude Code, Cursor, Copilot Workspace e ferramentas que leem arquivos de contexto. Resolve o problema de agentes de IA que reinventam padrões por falta de conhecimento do projeto.

Instalação

$npx convez-ai robertourias/scaffold-ia-projetos

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 semana
Versão
v2.1.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Estruturar contexto de projetos fullstack para trabalhar com agentes de IA
  • Definir padrões de código, convenções e fluxo de entrega antes de delegar tarefas
  • Manter consistência de decisões arquiteturais entre múltiplas ferramentas de IA
  • Implementar review em dois estágios com spec-driven delivery

Veredito

Solução prática e bem estruturada para o problema real de desalinhamento entre agentes de IA e contexto de projeto. Excelente para equipes que usam múltiplas ferramentas de IA e precisam de guardrails consistentes; requer disciplina inicial para preencher o scaffold corretamente.

README

A tradução para o português deste README ainda está na fila.

Scaffold IA — Next.js & NestJS

Estrutura agnóstica de contexto persistente para agentes de IA. Define papéis, fluxo spec-driven, padrões de código e processo de revisão em dois estágios.

Compatível com Claude Code, Cursor, Codex, Copilot Workspace e qualquer ferramenta que leia arquivos.


O problema que resolve

Agentes de IA não sabem sobre seu projeto: stack, convenções, decisões, regras de negócio. Sem contexto, inventam padrões, repetem perguntas e divergem do planejado.

O docs/ é a memória persistente que preenche essa lacuna sem reensinar tecnologias que o agente já conhece.

Princípio central: coloque no contexto apenas o que o agente não pode inferir sozinho. Carregue apenas o que é relevante para a tarefa em curso.


Quick Start

Para um projeto novo

# 1. Copiar scaffold
cp -r scaffold-ia-projetos/docs   seu-projeto/
cp -r scaffold-ia-projetos/.claude seu-projeto/
cp    scaffold-ia-projetos/AGENTS.md seu-projeto/

# 2. Inicializar no Claude Code
/init-project sistema de gestão de pedidos para restaurantes

O comando conduz entrevista em 5 blocos (nome, arquitetura, decisões backend, frontend, convenções) e preenche automaticamente docs/context/.

Para um projeto existente

# 1. Copiar arquivos atualizados
cp -r scaffold-ia-projetos/docs/commands/ seu-projeto/docs/
cp -r scaffold-ia-projetos/docs/workflows/ seu-projeto/docs/
cp -r scaffold-ia-projetos/docs/skills/ seu-projeto/docs/

# 2. Criar pastas
mkdir -p seu-projeto/docs/archive seu-projeto/docs/context/domains

# 3. Reorganizar (veja "Migração" abaixo)

Estrutura

docs/
├── skills/                ← Papéis, responsabilidades, padrões reutilizáveis
│   ├── planner.md        ← Spec-driven: Spec → Plan → Implementação
│   ├── backend.md
│   ├── frontend.md
│   ├── quality.md        ← Revisão em dois estágios
│   └── supabase.md       ← Padrões Supabase (Auth/DB/Storage)
│
├── specs/                 ← Specs aprovados de features
│   ├── spec-template.md  ← Base para novos specs
│   └── YYYY-MM-DD-*.md   ← Spec de cada feature (Status: draft → approved)
│
├── context/               ← Informações únicas do seu produto (preencha estes!)
│   ├── product.md        ← Usuários, regras de negócio
│   ├── product-backlog.md← Tasks (gerado por /backlog)
│   ├── conventions.md    ← Nomenclatura, Git, imports
│   ├── decisions.md      ← Escolhas de frontend e backend
│   ├── ui-guidelines.md  ← Design system, tokens, componentes
│   └── current-state.md  ← Estado atual (atualizado por /checkpoint)
│
├── architecture/          ← Visão arquitetural detalhada
│   ├── overview.md
│   ├── backend.md
│   ├── frontend.md
│   └── infra.md
│
├── workflows/             ← Processos (carregados sob demanda)
│   ├── feature-delivery.md← Fases 0-7 da entrega
│   └── release-process.md
│
├── commands/              ← Prompts de ativação de papéis
│   └── README.md          ← Referência completa
│
└── changelog/             ← Histórico por data

.claude/CLAUDE.md          ← Adaptador Claude Code
AGENTS.md                  ← Adaptador Cursor/Copilot/Codex

Fluxo de entrega (Spec-driven)

Ideia/requisito
      ↓
[1] /init-project (uma vez no início)
      ↓
[2] /backlog (gera TASK01..TASKNN) ← ou pule para [3] se for feature avulsa
      ↓
[3] /spec TASK01 (gera spec + plano de tarefas técnicas)
      ↓
      ⛔ GATE: você edita spec/plano → Status: approved
      ↓
[4] /back tarefa1, tarefa2, tarefa3
      ↓
[5] /front tela1, tela2
      ↓
[6] /review [diff]
      ↓
[7] /checkpoint (salva estado) → git commit
      ↓
[8] Mova specs concluídas para docs/archive/

Por que o gate importa: Sem a aprovação, o agente assume escopo e você descobre tarde. A spec com as tarefas técnicas obriga alinhamento antes de escrever código.


Slash Commands (Claude Code)

ComandoExemploO quê
/init-project/init-project sistema de pedidosEntrevista, preenche contexto
/backlog/backlogGera TASK01..TASKNN do product.md
/spec/spec TASK01Levantamento, gera spec + plano técnico (Status: review)
/groom/groom nova funcionalidadeRefina uma nova feature isolada adicionando-a ao backlog
/back/back implementar auth com JWTAgent backend
/front/front criar modal de loginAgent frontend
/review/review [cole diff aqui]Revisão 2 estágios: Funcional → Qualidade
/checkpoint/checkpointSalva estado, gera changelog
/retomar/retomarReconstrói contexto após interrupção

Referência completa e uso em Cursor/Copilot: docs/commands/README.md


Economia de Tokens — Controle de Contexto

O design de carregamento sob demanda é proposital: cada arquivo existe para ser lido apenas quando relevante — nunca em toda sessão.

Quanto contexto cada papel usa

PapelArquivosTokens
Backendskills/backend.md + conventions.md + decisions.md~0.8k
Frontendskills/frontend.md + conventions.md + ui-guidelines.md + decisions.md~1.1k
Planner (Spec + Plan)skills/planner.md + product.md + architecture/overview.md~1.4k
Reviewerskills/quality.md + conventions.md + decisions.md~0.8k

Estratégias implementadas

1. Fragmentação por relevância

  • Só carrega o que a tarefa precisa
  • Specs vão para archive/ quando concluídos
  • Regras de negócio fragmentadas em context/domains/ (auth.md, payments.md, etc.)

2. Delta, não tutorial O agente já sabe Next.js, NestJS, TypeScript, Clean Architecture. O docs/ entrega apenas o que é único do seu produto:

  • Decisões tomadas (Tailwind em vez de styled-components)
  • Regras não-óbvias (pedidos acima de R$ 500 precisam aprovação)
  • Contexto de domínio (seu modelo de negócio)

3. Batching Agrupe tarefas pequenas em uma chamada:

/back implementar use cases: autenticação, criação de pedido, listagem
/front criar páginas: login, home, checkout

Reduz overhead de sessões múltiplas.

4. Compressão ativa Antes de fechar, /checkpoint gera current-state.md comprimido — apenas status alto nível, tarefa ativa e próximos passos. Remove histórico granular.

Crescimento controlado

O contexto cresce apenas quando:

  • Você adiciona nova regra de negócio → product.md ou context/domains/*.md
  • Você toma decisão arquitetural → architecture/*.md ou decisions.md
  • Você aprova nova feature → novo spec em specs/

Tudo mais é descartado ao final de cada feature (specs vão para archive).


Retomando após interrupção

Quando você volta após horas ou dias, use o par /checkpoint + /retomar.

Antes de fechar:

/checkpoint
  → agente lê git log + contexto da sessão
  → escreve current-state.md resumido (pronto, em progresso, próximos passos)
  → você realiza commit manual

Ao voltar:

/retomar
  → agente lê current-state.md + git log + specs ativos
  → apresenta: o quê está pronto, onde parou, próxima ação

O /retomar funciona mesmo sem checkpoint anterior — ele infere estado do git log. Mas com checkpoint recupera também decisões verbais.


Fluxo completo (exemplo)

# Iniciar uma vez
/init-project plataforma de gestão de despesas

# Gerar backlog
/backlog
  → você aprova lista de tarefas

# Especificar e planejar uma tarefa (juntos!)
/spec TASK01
  → você aprova spec + plano técnico, edita Status: review → Status: approved

# Implementar (batching)
/back implementar use case 1, 2 e 3
/front criar telas X, Y, Z

# Revisar
/review [diff do backend]
/review [diff do frontend]

# Encerrar
/checkpoint
git commit -m "feat: descrição"

# Arquivar
mv docs/specs/YYYY-MM-DD-*.md docs/archive/

# Próxima tarefa
/spec TASK02

Migração — Otimizar projeto existente

Se você já tem um projeto rodando e quer economizar tokens:

Passo 1: Atualizar arquivos base

cp -r scaffold-ia-projetos/docs/commands/ seu-projeto/docs/
cp -r scaffold-ia-projetos/docs/workflows/ seu-projeto/docs/
cp -r scaffold-ia-projetos/docs/skills/ seu-projeto/docs/
mkdir -p seu-projeto/docs/archive seu-projeto/docs/context/domains

Passo 2: Reorganizar contexto (no Claude Code)

Execute este prompt:

Você é o PLANNER. Atualize a arquitetura de contexto para economizar tokens:

1. Analise docs/context/product.md. Se extenso, fragmente regras em
   docs/context/domains/ (ex: auth.md, payments.md, reports.md),
   deixando product.md apenas com visão geral + links.

2. Mova specs/ finalizadas para docs/archive/.

3. Reescreva docs/context/current-state.md extremamente resumido:
   - Status geral (1 frase)
   - Tarefa em progresso (1 linha)
   - Próximos passos (2-3 linhas)
   - Remove histórico e listas antigas

Após isso, seu projeto usa 30-40% menos tokens sem perder contexto.


O que cada diretório faz

DiretórioResponsabilidade
skills/Papéis, checklist, boas práticas, qualidade
specs/Specs de features (Status: review → approved)
context/Informações únicas do seu produto — você preenche
architecture/Visão técnica: backend, frontend, infra
workflows/Processos (feature-delivery, release)
commands/Prompts de ativação de papéis
changelog/Histórico por data
archive/Specs concluídas

Adaptadores incluídos

FerramentaArquivoCarregamento
Claude Code.claude/CLAUDE.mdAutomático
CursorAGENTS.mdAutomático
Copilot WorkspaceAGENTS.mdAutomático
Codex / OutrosAGENTS.mdManual (copie no chat)

Manutenção

O docs/ é um documento vivo. Trate como código de produção: versionado, revisado em PR.

Atualize quando:

  • Decisão arquitetural → architecture/
  • Regra de negócio → product.md ou context/domains/
  • Nova tech/lib → decisions.md
  • Feature aprovada → novo spec em specs/

Stack padrão

CamadaTech
MonorepoTurborepo
FrontendNext.js 14+ (App Router)
BackendNestJS
LinguagemTypeScript strict
ArquiteturaClean Architecture

Licença

MIT

Ver o original no GitHub

Bom para

Relacionados