agentleFS
Sign inStart free
1pedroosilva1pedroosilva/databricks-genie-skills/naming-conventions/SKILL.md

naming-conventions

Skill0 starsChanged 42 days agoMITView on GitHub

Use ao definir, nomear, escolher, estabelecer ou criar nomes para assets NOVOS -- notebooks, tabelas, DataFrames, variaveis, pastas. Convencoes de numeracao (001_, 103_), principio DRY, padroes de caixa (snake_case, PascalCase). NAO use para revisar ou validar nomenclatura de codigo existente.

11 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use tdd.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • GoogleSkill

    tdd

    Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 9 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Preferência por letras minúsculas em toda nomenclatura (pastas, arquivos, variáveis, tabelas)

    line 16

“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Nomenclatura e Convenções

Versão: 1.0.4 | Data: 2026-08-18 | Domínio: naming | Autor: Pedro O. Silva

Princípios Gerais

  • Nomenclatura autocontida: Todos os nomes (notebooks, células, dataframes, tabelas, variáveis) devem ser autoexplicativos - o nome deve descrever claramente o conteúdo ou propósito do objeto.
  • Convenção de caixa:
  • Preferência por letras minúsculas em toda nomenclatura (pastas, arquivos, variáveis, tabelas)
  • Títulos de células: CARREGUE a skill notebook-structure para regras de formatação de títulos de células

Notebooks

  • Formato: Sempre usar letras minúsculas, separar palavras com _ (underscore) ou - (hífen). NUNCA usar espaços.
  • Numeração e Rastreabilidade (3 dígitos obrigatórios):
  • Formato: [XXX]_[nome_base_idêntico_entre_camadas] — SEMPRE 3 dígitos
  • Primeiro dígito: identifica a camada (1=bronze, 2=silver, 3=gold)
  • Dois dígitos seguintes: sequência dentro da camada (01-99)
  • REGRA CRÍTICA DE RASTREABILIDADE:
  • O nome base (tudo após os 3 dígitos) deve ser IDÊNTICO nas três camadas
  • Apenas o primeiro dígito muda para indicar a camada
  • Isso cria rastreabilidade visual perfeita do fluxo de dados através do pipeline
  • Exemplos corretos:
  • 101_cvm_dfp_dre → 201_cvm_dfp_dre → 301_cvm_dfp_dre
  • 102_dados_clientes → 202_dados_clientes → 302_dados_clientes
  • Exemplos INCORRETOS (quebram rastreabilidade):
  • 101_ingestao_cvm → 201_transformacao_cvm → 301_agregacao_cvm (nomes diferentes)
  • 101_cvm_dfp_dre → 201_dre_dfp_silver → 301_indicadores (nomes diferentes)
  • Benefícios:
  • Rastreabilidade imediata entre camadas (101→201→301)
  • Consistência visual perfeita
  • Ordenação lógica automática
  • Facilita identificar fluxos de dados relacionados
  • CRÍTICO: NUNCA usar apenas números sem nome descritivo — seria irracional e não autodescritivo

DataFrames

  • Padrão: df_[descricao_autocontida_do_dado]
  • NÃO incluir:
  • Prefixo de camada (bronze/silver/gold) quando o notebook é dedicado a uma única camada - a camada já está explícita no nome do notebook e no schema do Unity Catalog
  • Sufixo de tecnologia (spark, pandas, etc) - o contexto tecnológico já está implícito no notebook
  • Foco: Descrever o DADO, não a infraestrutura ou camada
  • Exemplo: df_dre_consolidada (não df_bronze_dre_consolidada_spark)
  • Exceção: Quando um notebook processa múltiplas camadas (ex: transformação bronze→silver), incluir a camada para clareza

Princípio DRY (Don't Repeat Yourself)

  • Regra: Evitar redundância com a hierarquia de pastas
  • O nome do arquivo NÃO deve repetir informações já explícitas na estrutura de diretórios
  • Exemplos:
  • Se está em /bronze/, não adicionar sufixo _bronze
  • Se está em /projeto_x/, não adicionar prefixo projeto_x_
  • A camada e o projeto são definidos pela PASTA, não pelo NOME DO ARQUIVO

Pastas

  • Hierarquia de diretórios: Organizar sempre por pastas com nomes autocontidos:
  1. Nível 1: Nome do projeto
  2. Nível 2: Camada (bronze/silver/gold ou equivalente)
  3. Nível 3: Notebooks por tema
  4. Pasta dedicada: /documentacao subdividida em /técnica e /negocio
  • Numeração de pastas (BEST PRACTICE):
  • Sempre numerar pastas de camadas para forçar ordenação lógica (não alfabética)
  • Padrão: 01_bronze, 02_silver, 03_gold
  • Convenção estabelecida em engenharia de dados, usada pela Databricks em exemplos oficiais
  • Facilita navegação e deixa clara a sequência do pipeline

Versionamento

  • Git: Usar Git apenas para código refinado e decisões consolidadas
  • Evitar: Sufixos como _v1, _v2 - isso é considerado desorganização

Ao implementar mudanças, consulte docs-sync/SKILL.md para atualizar documentações afetadas.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free