AgentSkillsCN

naming

所有命名决策均需遵守——变量、函数、文件、文件夹、类、数据库表、路由、CSS 类。创建或重命名任何标识符时都必须遵循。这是确保所有语言和上下文中名称一致、易读的不可妥协基准。

SKILL.md
--- frontmatter
name: naming
description: MANDATORY for all naming decisions - variables, functions, files, folders, classes, database tables, routes, CSS classes. Must be followed when creating or renaming any identifier. Non-negotiable baseline for consistent, readable names across all languages and contexts.

Naming

This skill is mandatory. Follow these rules whenever naming anything in code.

Hierarchy of Authority

  1. •These rules - non-negotiable baseline (e.g., no ALL_CAPS)
  2. •Project conventions - existing patterns in the codebase
  3. •Language/framework conventions - ecosystem standards

Always check the project first. Consistency within the project trumps external standards.

Core Rules

  • •

    Never ALL_CAPS for names - use language features (const, final, readonly) to express immutability. Exception: PHP define() constants follow WordPress convention. Note: Claude Code metadata files use capital case (Skill.md, Claude.md).

  • •

    Avoid abbreviations - spell words out. Exception: universally understood shortenings of long words (info, max, min, config).

  • •

    Market-defined acronyms are fine - Url, Http, Api, Html, Css, Id are acceptable. Don't invent project-specific acronyms users must learn.

  • •

    Context informs naming - the container (class, folder, namespace) provides context. user.isValid() not user.isUserValid(). utils/dates.ts not date-utils.ts.

  • •

    No redundant suffixes - users not userList. The type system or structure already tells you.

  • •

    Hide implementation details - name the interface, not the mechanism. getUser not fetchAndCacheUser.

  • •

    Simple but complete - don't over-shorten, but don't add words that don't add context.

Semantic Patterns

Booleans: Use is, has, can, should prefixes. isLoggedIn, hasPermission, canEdit.

Event handlers vs callbacks:

  • •Handler (internal): handle + event → handleSubmit
  • •Callback (prop): on + event → onSubmit

Hooks: use + what it provides → useProducts, useAuth

Collections: Simple plurals → users, orders. Not userList, orderArray.

Transformers: Method on the source object → user.toJson(), order.toResponse()

The Naming Test (Boundary Detection)

Use when naming functions, services, or handlers. If you can't name it with one verb, the function is doing too many things.

For each function:

  1. •Who is the caller? Identify who uses this
  2. •What is the step-level effect? What does THIS function do — not the downstream chain, just its direct effect
  3. •Name it with ONE idiomatic verb
SignalMeaning
One verb covers all code pathsBoundary is correct
Need "or" to connect two verbsLikely two operations bundled — split them
Name doesn't feel idiomaticBoundary is wrong
Name matches a downstream effect, not this stepYou're naming the chain, not the step

Step-level vs chain-level: Name what THIS function does, not what its callees achieve. An orchestrator that calls validate → find → extract → insert is a handler, not an adder. The adding happens downstream.

Caller perspective: Names reflect what the caller achieves. A tool exposed externally: placeLocale (what the caller wants). The internal handler: handlePlaceLocale (what it does).

Naming resistance as a signal: If resolveLocale either pops from a list OR creates a new dict — "take" fits one path, "create" fits the other, need "or" → split into extractLocale and createLocale.

Checklist

  • • Checked project conventions first
  • • No ALL_CAPS (except PHP define())
  • • No abbreviations (except ultra common & universal ones like info/max/min/config)
  • • Context not repeated (user.isValid not user.isUserValid)
  • • No redundant suffixes (users not userList)
  • • Booleans use is/has/can/should prefix

References