MÓDULO 3.5

📁 Usando arquivos de escopo

Sintaxe @arquivo: o jeito mais poderoso de melhorar o plano sem aumentar rodadas. Você dá ao Claude documentos reais antes do rascunho.

1

📐 Sintaxe @arquivo

/claudex plan @scope.md adicionar feature X

O @ diz ao Claude: "leia este arquivo antes de planejar". O conteúdo do arquivo entra no contexto, então o plano nasce com base em documentação real, não só no prompt.

2

📄 Exemplo com @scope.md

Você tem um arquivo de escopo escrito pelo time de produto:

# scope.md

## Objetivo
Implementar fluxo de checkout para cliente B2B.

## Requisitos
- Pagamento por boleto e PIX (não cartão na v1)
- Limite de R$ 100k por transação
- Aprovação manual acima de R$ 50k
- Fatura emitida pelo sistema legado

## Restrições
- Não pode tocar API de auth (em refactor paralelo)
- Stripe é proibido por compliance
- Time tem 3 sprints pra entregar

Agora você invoca:

/claudex plan @scope.md implementar checkout B2B

O Claude lê o scope.md, e o PLAN.md já nasce respeitando: pagamento boleto/PIX, limites, restrição de Stripe, prazo de 3 sprints. Sem você precisar repetir.

3

🏗️ Exemplo com @architecture.md

Você tem doc de arquitetura interna:

# architecture.md

## Stack
- Backend: Node.js 20, NestJS, PostgreSQL 16
- Filas: BullMQ + Redis
- Cache: Redis 7
- Observabilidade: Datadog (não Prometheus)

## Convenções
- Migrations via Prisma
- Logs estruturados em JSON
- Métricas com prefix `app.`
/claudex plan @architecture.md adicionar fila para
processamento de relatórios pesados

O Claude já sabe que vai usar BullMQ (não Sidekiq, não SQS), métricas em app., logs JSON. Plano nasce alinhado.

4

📚 Múltiplos arquivos

Você pode passar quantos quiser. O Claude lê todos antes de planejar:

/claudex plan @scope.md @architecture.md @api-spec.md
implementar sincronização de inventário com ERP

Limite prático: ~10 arquivos médios (varia conforme tamanho). Se você precisa de mais, é melhor consolidar em um doc único.

5

📈 Por que isso melhora o plano

Sem arquivos de escopo, o Claude tem que adivinhar seu contexto. Adivinha errado às vezes. Aí você gasta rodadas pra corrigir. Com escopo, o plano nasce com contexto real — você economiza rodadas.

❌ Sem escopo

  • • Claude assume Stripe
  • • Codex aponta "Stripe é proibido"
  • • Claude refaz
  • • Gastou 1 rodada à toa

✅ Com @scope.md

  • • Claude já sabe: sem Stripe
  • • Plano nasce com boleto/PIX
  • • Codex foca em problemas reais
  • • Rodadas usadas para o que importa
6

⏰ Quando usar e quando não

✓ Use @arquivo quando

  • • Você tem doc de escopo escrito
  • • Existe arquitetura documentada
  • • Há restrições não óbvias (compliance, contrato)
  • • Você quer respeitar convenções existentes
  • • PRD já existe

✗ Pule @arquivo quando

  • • Tarefa é trivial (1 rodada basta)
  • • Você não tem doc — escrever doc só pra Claudex é overkill
  • • Doc está desatualizado (pior que não ter)

💡 Pro-tip

Se sua equipe já mantém um docs/ com scope/arch/conventions, faça @arquivo ser parte do hábito. Plano sempre alinhado com a base de conhecimento sem esforço extra.

📌 Resumo

✓
Sintaxe @arquivo — antes da descrição.
✓
@scope.md — escopo de produto, restrições, prazos.
✓
@architecture.md — stack, convenções, observabilidade.
✓
Múltiplos arquivos — até ~10 médios.
✓
Economiza rodadas — Codex foca no que importa, não em corrigir suposições.
✓
Use sempre que tiver doc — não escreva doc só pra Claudex; mas se já tem, use.

Próximo Módulo:

3.6 — 🏗️ Exemplos reais ponta-a-ponta (com PLAN.md completos)

← AnteriorPróximo →