skill-rust-workspace

Skill: Rust workspace — single-crate vs multi-crate

Esta skill cobre dois cenários relacionados:

• Cenário A — você está gerando DESIGN.md/BLUEPRINT.md de um projeto Rust/Axum e precisa decidir desde já se ele nasce single-crate ou em workspace.
• Cenário B — o projeto Rust já existe em single-crate e cresceu ao ponto de doer (compilação lenta, fronteiras arquiteturais erodindo, workers acoplados ao API server). Você precisa propor um plano de migração para workspace.

A regra geral: comece simples, migre quando os critérios objetivos abaixo aparecerem. Workspace é a estrutura idiomática Rust para projetos maduros, mas é overengineering para o "hello world".

---

Cenário A — Decisão na fase Design/Blueprint

Antes de escrever o BLUEPRINT da stack rust-axum, decida: single-crate ou workspace? Os critérios são objetivos:

Comece single-crate quando TODOS forem verdadeiros

• Apenas 1 binário (HTTP server).
• Estimativa de < 30 arquivos .rs no src/.
• 1–2 sistemas externos (apenas DB; ou DB + cache).
• Equipe ≤ 2 devs trabalhando ativamente.
• Nenhum requisito de deploy independente para subcomponentes.

Comece workspace multi-crate quando QUALQUER um for verdadeiro

• ≥ 2 binários previstos (API + worker; API + admin; API + CLI).
• Múltiplos sistemas externos (3+: PG + Redis + Rabbit + Qdrant + Neo4j + …).
• Deploy independente desejado (workers em pods separados no k8s, scaling independente).
• Fronteiras arquiteturais críticas (domain puro sem HTTP/DB; SDK que vai virar crate público; biblioteca de cliente compartilhada com outras apps).
• Equipe ≥ 3 devs trabalhando em módulos diferentes em paralelo.

Layout convencional para workspace

Use o prefixo do projeto (<p>) como namespace de todos os crates — por exemplo wa- para uma wa-business-api, agent- para um agent-ai, chat- para um chat-service.

projeto/
├── Cargo.toml                          # workspace root, deps centralizadas
├── docker-compose.yml
├── Dockerfile
├── crates/
│   ├── <p>-domain/         (lib)       # entities puras: structs, errors, types
│   ├── <p>-config/         (lib)       # AppConfig::from_env()
│   ├── <p>-db/             (lib)       # sqlx pool, migrations
│   ├── <p>-cache/          (lib)       # redis/moka (se houver)
│   ├── <p>-queue/          (lib)       # lapin/kafka (se houver)
│   ├── <p>-crypto/         (lib)       # bcrypt, jwt, aes (se aplicável)
│   ├── <p>-meta-client/    (lib)       # cliente externo (Meta API, Stripe…)
│   ├── <p>-services/       (lib)       # business logic, sem HTTP
│   ├── <p>-api/            (bin + lib) # HTTP server (handlers, router, mw)
│   ├── <p>-worker-<X>/     (bin)       # 1 binário por tipo de worker
│   ├── <p>-admin/          (bin)       # CLI admin (se houver)
│   └── <p>-e2e/            (tests)     # integration tests cross-crate
└── xtask/                              # scripts de build/dev em Rust