Onboarding — AI Agent¶

Como configurar Claude Code, Gemini, ou outro agente LLM para trabalhar com os repos da Vanguru.

Pré-requisito: clone local do `internal-docs`¶

Decisão F0 §Q-05: o conteúdo deste site não é acessível via API. Devs e agentes leem direto do filesystem.

cd ~/project/vanguru
git clone https://github.com/rotaescolarappbr/internal-docs

A partir daí, o conteúdo de ~/project/vanguru/internal-docs/docs/** está disponível para o agente local.

Sincronizar antes de sessões importantes:

cd ~/project/vanguru/internal-docs && git pull

Como apontar o agente¶

Claude Code¶

Quando estiver trabalhando em outro repo (ex.: vanguru_mobile/), inclua o path do internal-docs na sessão:

cd ~/project/vanguru/vanguru_mobile
claude --add-dir ~/project/vanguru/internal-docs

Ou mencione explicitamente no prompt: "Considere também o conteúdo de ~/project/vanguru/internal-docs/docs/architecture/firestore.md para responder".

Gemini CLI¶

gemini --include ~/project/vanguru/internal-docs/docs/

Outros agentes¶

Geralmente exposição de filesystem via MCP ou opção CLI --add-dir. Consultar docs do agente específico.

CLAUDE.md por repo¶

Cada repo de código tem um CLAUDE.md no root com instruções específicas (padrões de código, convenções, comandos comuns). LLM lê esse arquivo automaticamente em sessões iniciadas no diretório.

Padrões observados nos CLAUDE.md:

vanguru/CLAUDE.md (raiz do workspace) — visão geral cross-projeto, convenções LGPD, GCP project IDs.
vanguru/vanguru_mobile/CLAUDE.md — padrões Flutter, Clean Architecture, Riverpod.
vanguru/website/CLAUDE.md — padrões Astro.

Adicione novos CLAUDE.md em repos onde regras locais não estão capturadas no internal-docs.

Onde encontrar o quê¶

Pergunta típica	Caminho
"Como Firestore está organizado?"	`internal-docs/docs/architecture/firestore.md`
"Como funciona auth do app?"	`internal-docs/docs/projects/vanguru-mobile/authentication.md`
"Quais decisões tomamos sobre integração Asaas?"	`internal-docs/docs/initiatives/asaas-integration/04-decisoes-arquiteturais.md`
"Como deployar payments-api?"	`internal-docs/docs/runbooks/production-deploy.md`
"Pricing atual?"	`internal-docs/docs/business/pricing.md`
"Como tratar PII?"	`internal-docs/docs/security/pii-pattern.md`

Boas práticas para o agente¶

Antes de fazer mudança não-trivial em um subsistema, ler o doc correspondente em internal-docs/docs/projects/<subsistema>/ e o 04-decisoes-arquiteturais.md da iniciativa relacionada em initiatives/<i>/.
PII em código: nunca colocar CPF/RG/nome completo em logs, comentários ou variáveis de teste. Usar dados sintéticos (000.000.000-00, "Maria Sintética").
Confirmar antes de ações irreversíveis: push em main, deploy, mudança em entity.yaml, alteração em legal.
Use os ADRs como ground truth: decisões passadas explicam o "porquê" do código atual.

Quando o internal-docs muda¶

Como devs/agentes fazem clone local, o conteúdo pode ficar stale. Sintomas: - Resposta do agente cita URL ou path que não existe mais. - Resposta menciona padrão obsoleto.

Mitigação: git pull antes de sessões importantes; se duvidar, validar contra código.

Estrutura do repo¶

internal-docs/
├── docs/
│   ├── architecture/        # Como tudo se conecta
│   ├── security/            # LGPD, threat models, PII
│   ├── api/                 # Functions, Payments, Gateway
│   ├── guides/              # Setup, Flutter, Java, Firebase
│   ├── business/            # Pricing, custos, plano
│   ├── strategy/            # Decisões estratégicas
│   ├── product/             # Features, personas
│   ├── business-rules/      # Regras operacionais
│   ├── projects/            # Por subsistema (vanguru_mobile, etc.)
│   ├── initiatives/         # Iniciativas (com ADRs embutidos)
│   ├── runbooks/            # Procedimentos operacionais
│   ├── operations/          # Retention, observability
│   ├── onboarding/          # dev.md, founder.md, ai-agent.md (este)
│   └── index.md
├── mkdocs.yml
└── requirements.txt