Boilerplate — Colaboração com IA (Cursor)

Repositório independente (raiz do Git) para versionar no GitHub e copiar ou mesclar em outros projetos, padronizando: docs de produto/fluxo, agentes e regras (.cursor/rules). Espelha o modelo usado no Insights Platform e referências como Teddy Open Finance.

Local sugerido: ~/Documents/Projects/cursor-ai-boilerplate (irmão de outros repos, não dentro de um app).

O que tem aqui

Item	Uso
docs/PRODUCT_SCOPE.md	Escopo de produto (edite placeholders {{PROJECT_NAME}}, stack, fora de escopo).
docs/ai-workflow.md	Princípios e fluxo de trabalho com IA.
docs/AGENTS_SETUP.md	Definição de agentes (orquestrador, front, back, DevOps, revisor).
.cursor/rules/	Regras .mdc genéricas (architecture, workflow, platform-ops, testing-quality).
snippets/ROOT_README_IA.md	Texto pronto para colar no README.md da raiz do projeto destino.
STACK_FRONT.mdc.example	Renomeie/copie para .cursor/rules/ e adapte ao seu front (React, Next, etc.).
STACK_BACK.mdc.example	Renomeie/copie para .cursor/rules/ e adapte ao seu back (Nest, Serverless, etc.).

Como adotar em um projeto novo

1. Obtenha este repositório (clone no ~/Documents/Projects/cursor-ai-boilerplate ou caminho que preferir) e copie os artefatos para a raiz do projeto destino — use os comandos da seção seguinte ou git submodule add se quiser puxar só este repo dentro do outro.

2. Substitua placeholders em todos os arquivos (busca global):

   • {{PROJECT_NAME}} — nome do produto ou repo
   • {{ORG_OR_TEAM}} — opcional

3. Ajuste docs/PRODUCT_SCOPE.md com visão real, personas, integrações e non-goals.

4. Renomeie e edite os exemplos de stack:

   • STACK_FRONT.mdc.example → .cursor/rules/next-web.mdc (ou react-ui.mdc, etc.)
   • STACK_BACK.mdc.example → .cursor/rules/nestjs-backend.mdc (ou serverless-api.mdc, etc.)
     Atualize o frontmatter globs: para bater com a pasta do seu código.

5. Cole no README.md raiz o conteúdo de snippets/ROOT_README_IA.md (seção final).

6. Opcional: se não usar Nx, apague ou ignore referências a Nx em platform-ops.mdc e no AGENTS_SETUP.

7. Abra o projeto no Cursor e faça a primeira conversa anexando contexto com @ e um dos prompts da secção «Uso do @ e prompts no projeto existente» (mais abaixo neste README).

8. Commit no repositório destino para o time inteiro herdar o mesmo comportamento da IA.

---

Copiar tudo para o lugar certo (projeto que já existe)

Defina o caminho absoluto do repositório destino. Os comandos abaixo criam pastas se faltarem e copiam por cima arquivos com o mesmo nome no destino — se já tiver docs/PRODUCT_SCOPE.md ou regras com nomes iguais, faça commit ou backup antes (cp -R docs docs.backup, etc.).

Opção A — rsync (recomendado no macOS / Linux)

# Ajuste só PROJECT_ROOT; BOILERPLATE pode ficar no padrão abaixo
export BOILERPLATE="${BOILERPLATE:-$HOME/Documents/Projects/cursor-ai-boilerplate}"
export PROJECT_ROOT="/caminho/absoluto/do/seu/repo-existente"

mkdir -p "$PROJECT_ROOT/docs" "$PROJECT_ROOT/.cursor/rules" "$PROJECT_ROOT/snippets"

rsync -av "$BOILERPLATE/docs/" "$PROJECT_ROOT/docs/"
rsync -av "$BOILERPLATE/.cursor/rules/" "$PROJECT_ROOT/.cursor/rules/"
rsync -av "$BOILERPLATE/snippets/" "$PROJECT_ROOT/snippets/"

# Exemplos de stack na pasta de regras (revise e renomeie .example → nome final)
cp -f "$BOILERPLATE/STACK_FRONT.mdc.example" "$PROJECT_ROOT/.cursor/rules/"
cp -f "$BOILERPLATE/STACK_BACK.mdc.example" "$PROJECT_ROOT/.cursor/rules/"

Opção B — cp (sem rsync)

export BOILERPLATE="${BOILERPLATE:-$HOME/Documents/Projects/cursor-ai-boilerplate}"
export PROJECT_ROOT="/caminho/absoluto/do/seu/repo-existente"

mkdir -p "$PROJECT_ROOT/docs" "$PROJECT_ROOT/.cursor/rules" "$PROJECT_ROOT/snippets"

cp -R "$BOILERPLATE/docs/." "$PROJECT_ROOT/docs/"
cp -R "$BOILERPLATE/.cursor/rules/." "$PROJECT_ROOT/.cursor/rules/"
cp -R "$BOILERPLATE/snippets/." "$PROJECT_ROOT/snippets/"
cp -f "$BOILERPLATE/STACK_FRONT.mdc.example" "$PROJECT_ROOT/.cursor/rules/"
cp -f "$BOILERPLATE/STACK_BACK.mdc.example" "$PROJECT_ROOT/.cursor/rules/"

Depois: abra a pasta PROJECT_ROOT no Cursor (File → Open Folder), não a pasta do boilerplate — assim .cursor/rules/*.mdc passam a valer para o seu app.

---

Uso do @ e prompts no projeto existente

O que entra sozinho vs. oQue você anexa com @

O quê	Comportamento
.cursor/rules/*.mdc	Regras com alwaysApply: true (ou escopo por globs) entram no contexto ao trabalhar nessa pasta — não precisa citar cada arquivo na mensagem.
docs/*.md + README	Em geral não vêm inteiros em toda mensagem; use @ na primeira mensagem de um tópico grande ou após reabrir o Cursor.
docs/AGENTS_SETUP.md	Referência para você colar instruções em agentes do Cursor; use @ quando quiser que o modelo siga papéis/orquestração naquela conversa.

Primeira mensagem recomendada (bootstrap)

Anexe os arquivos principais do seu repo (teclas @ na caixa do chat; escolha os arquivos da lista):

• @docs/PRODUCT_SCOPE.md
• @docs/ai-workflow.md
• @docs/AGENTS_SETUP.md
• @README.md
• Se existirem: @docs/architecture.md, CONTRIBUTING.md, ou README do app em subpasta.

Prompt 1 — Entender o projeto real e alinhar o boilerplate

Cole algo neste formato (edite só se quiser):

Acabei de copiar o boilerplate (docs/, .cursor/rules/, snippets/) para a raiz deste repositório.

Contexto anexado com @.

Tarefas:
1) Em 5 bullets, o que este projeto já faz hoje, com base nos READMEs e na estrutura de pastas que consulares.
2) O que em docs/PRODUCT_SCOPE.md ainda está genérico ou placeholder e deve ser editado para refletir a realidade.
3) Quais arquivos em .cursor/rules/ devem ser ajustados (globs, bullets, ou renomear STACK_* para a minha stack) — sugere alterações mínimas, sem reescrever tudo.
Não implementes código ainda; só análise e lista de próximos passos.

Prompt 2 — Preencher PRODUCT_SCOPE.md a partir do código

@docs/PRODUCT_SCOPE.md @README.md

Preenche as seções com placeholders / <!-- EDIT --> com o que conseguir inferir deste repositório. Onde faltar fato de negócio, usa [PENDENTE: pergunta ao PO] em vez de inventar. No fim, resume o que ficou pendente para o time humano.

Prompt 3 — Épico com orquestração (usa agentes do AGENTS_SETUP)

Segue docs/AGENTS_SETUP.md e docs/ai-workflow.md.

Quero implementar: [DESCREVA A FEATURE EM UMA FRASE].

Só planeamento nesta mensagem: fases, ficheiros prováveis, riscos, e qual “papel” de agente usar em cada fase. Não escrevas código até eu aprovar o plano.

Prompt 4 — Rever regras vs. stack real

Liste a stack real deste repo (linguagens, frameworks, pastas de código-fonte). Compare com .cursor/rules/*.mdc e diga o que está desalinhado (Nx, testes, ops). Proponha diffs pequenos por arquivo .mdc.

Depois de alinhar documentos e regras, use @docs/PRODUCT_SCOPE.md (e README) no início de cada feature maior para manter escopo e regras coerentes.

Evolução do boilerplate

• Melhore este repositório no GitHub e faça git pull localmente.
• Periodicamente propague mudanças para projetos que já adotaram (merge manual ou diff).

Licença

Uso interno / livre no seu organismo — ajuste conforme a política da sua empresa.