Padrão de projeto

Todo projeto igual

Web, extensão, desktop, Android ou Rust: a mesma estrutura, o mesmo git, os mesmos hooks, o mesmo i18n e o mesmo design. Este repositório segue o padrão e entrega o kit para começar qualquer projeto.

Baixar acerola-template.zip 31 arquivos · 41 KB

Claude Code

Três skills, um padrão

O agente carrega a skill certa antes de mexer, e os hooks recusam o que fugir dela.

acerola-design

Como o app parece

Tokens, tipografia, componentes, estados obrigatórios, acessibilidade, movimento, texto, ícone e mascote.

acerola-project

Como o projeto é montado

Inglês em tudo que o usuário não vê, estrutura de pastas, padrões por camada, i18n, licença e projeto novo.

acerola-git

Como o código anda

Commit, Git-Flow, travas de branch, PR, issues, Actions, Dependabot e release.

Idioma

O que o usuário não vê é em inglês

Pastas, arquivos, rotas, variáveis, tipos, chaves de JSON e de config, tabelas, colunas, modelos, logs e comentários de código. Em português (via i18n) fica só o que aparece na tela; docs, skills, commits e PRs são para pessoas e seguem em português.

ts
// code: English
const watchedEpisodes = await mediaRepository.findProgress(userId);
//    table media_progress (user_id, media_id, episode, updated_at)
//    route /library/anime · file library-screen.svelte

// screen: i18n
m['library.progress.episode']({ current, total }) // → "Ep 5 de 12"

i18n

Todo projeto tem i18n

Paraglide (inlang) com pt-br e en. Chave em inglês e aninhada por assunto: mais um nível em vez de _ ou - para emendar contexto.

Certo
messages/pt-br.json
{
  "library": {
    "search": {
      "placeholder": "Buscar título",
      "empty": "Nada encontrado"
    }
  }
}
Errado
messages/pt-br.json
{
  "library_search_placeholder": "Buscar título",
  "library": { "search_empty": "Nada encontrado" },
  "biblioteca": { "busca": "…" }
}

Estrutura

A raiz é do repositório

O código mora em pastas com o nome do local do commit. Na raiz, só o que é do repositório inteiro.

tree
<repo>/
├── <app>/                 one folder per app (name = commit scope)
│   └── messages/          pt-br.json · en.json (i18n)
├── lib/<name>/            library shared between apps
├── docs/                  ARQUITETURA.md, guides and README images
├── scripts/
│   ├── git/               branch-guard.sh · commit-msg.mjs · setup-git.mjs
│   ├── design/            check-design.mjs
│   └── i18n/              check-i18n.mjs
├── .claude/               settings.json (hooks) · skills/
├── .github/               workflows · ISSUE_TEMPLATE · PR template · CODEOWNERS · dependabot
├── acerola.config.json    name, commit scopes, design and i18n folders
├── CLAUDE.md              project rules and deviations from the standard
├── README.md · CONTRIBUTING.md · RELEASE.md · LICENSE (MPL-2.0)
└── .gitmessage · .gitattributes · .editorconfig · lefthook.yml

Padrões por camada

São o padrão, não lei: trocar é permitido com o motivo escrito em "Desvios do padrão" no CLAUDE.md do projeto.

Interface Componente burro (data / events / ui) e página que orquestra
Estado Hook use-*.svelte.ts ou ViewModel; nada de estado global solto
Domínio Serviço ou caso de uso puro, testável sem I/O
Dados Repository: SQL e chamada externa só ali
Plataforma Porta no domínio, adaptador na infra (ports & adapters)
Erro Tipado, com mensagem que diz o que fazer; nunca engolido

Git

[tipo](local): Mensagem

Português, primeira maiúscula, sem ponto, até 100 caracteres. Um local por commit. Merge também segue o formato.

commit
[feat](site): Hero em pôster com Titan One
[fix](kit): Hook de design ignora arquivo gerado
[chore](deps): Sobe o SvelteKit para a 3.1
[merge](site): Página do padrão de projeto
featfixrefactortestdocsstyleperfbuildcichoremerge
main produção · só quem administra faz merge e push
develop integração · só recebe merge, nada de commit direto
feature/<name> funcionalidade · sai da develop e volta para ela
bugfix/<name> correção · sai da develop e volta para ela
release/<version> versão · vai para main e develop, com tag vX.Y.Z
hotfix/<version> urgência · sai da main, vai para main e develop

Hooks

Trava o que dá para travar

lefthook no git (igual para Rust, Kotlin ou Node) e hooks do Claude Code no agente.

commit-msg commit-msg.mjs formato, tipo e local do commit
pre-commit branch-guard + check-design + check-i18n trava main/develop, confere design e i18n
pre-merge-commit branch-guard trava merge na main
pre-push branch-guard trava push na main
Claude · SessionStart check-design --summary regras de design no contexto
Claude · PostToolUse check-design + check-i18n --hook recusa o arquivo que fugiu do design ou do i18n

GitHub

Actions e repositório

Templates de issue e PR, CODEOWNERS por pasta, e workflows com nome e gatilho previsíveis.

  • Um workflow por local e função: <local>-tests.yml, <local>-release.yml, <local>-deploy.yml
  • Nome visível Tests/<Local>, Release/<Local>, Deploy/<Local>
  • Teste em push e PR na develop e na main, com paths do local; workflow_dispatch sempre
  • Passos: checkout → setup com cache → instalar → lint → tipos → design → i18n → testes → build → publicar
  • Segredo em secrets, endereço em vars; passo opcional com if: vars.X != ""
  • Dependabot semanal na develop, agrupado, prefixo [chore](deps)

Licença

MPL-2.0 em tudo que é nosso

Código, CSS, scripts, skills, docs, ícone e mascote. O que é de terceiros mantém a licença de origem (fontes em SIL OFL 1.1).

package.json
"license": "MPL-2.0"
Cargo.toml
license = "MPL-2.0"
topo do arquivo
// SPDX-License-Identifier: MPL-2.0

Projeto novo

Cinco passos

Do zip ao primeiro commit na develop.

  1. 1 Baixe o kit acerola-template.zip na raiz do repositório novo.
  2. 2 Configure acerola.config.json: nome, locais de commit, pastas do design e do i18n.
  3. 3 Escreva as regras CLAUDE.md do projeto e CODEOWNERS.
  4. 4 Ligue o git node scripts/git/setup-git.mjs: Git-Flow, template e lefthook.
  5. 5 Traga a marca theme.css + components.css, ou o tema do tokens.json no Android.