u

.agents/skills/naming-conventions/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: naming-conventions
+description: "Use when: improving variable, function, module, or API names; refactoring code for clarity; choosing consistent naming in the dashback backend."
+---
+
+# Naming Conventions — dashback
+
+Apply these conventions when writing or refactoring code in this project.
+
+## Core rules
+
+- Prefer clear domain names over vague generic names.
+- Name functions as actions, not nouns.
+- Name variables and parameters by what they represent, not by their implementation detail.
+- Prefer explicit names over abbreviations unless the abbreviation is standard in the project.
+- Keep names consistent across the same subsystem.
+
+## Function naming
+
+- Use verb-based names for routines that do work: `registerRoutes`, `buildApiApp`, `listenOnPort`, `resolveUser`, `validateInput`.
+- Use `register`, `build`, `create`, `resolve`, `configure`, `respond`, `validate`, and `render` when the function performs an action.
+- Avoid vague names like `load`, `walk`, `handle`, `do`, `process`, `thing`, and `data` when a more specific name is available.
+- When a function builds a response object, prefer names like `respondWith...`, `build...Response`, or `create...Payload`.
+
+## Variable naming
+
+- Prefer descriptive nouns or noun phrases: `serverStartedAt`, `startupPromise`, `localPrivateHostPattern`.
+- Use boolean names that read like a question when possible: `isAllowedCorsOrigin`, `hasSelectedCompany`, `isDocsRequest`.
+- Use `statusCode` instead of `status` when a numeric HTTP status is involved.
+- Use `origin` and `request`/`req` precisely; avoid ambiguous names like `body` when `payload` or `userData` is clearer.
+
+## Module naming
+
+- Prefer names that describe the module’s responsibility, not incidental implementation details.
+- For API helper modules, names should communicate the response shape or purpose: `meJson` → `respondWithAuthenticatedUser` or `buildCurrentUserResponse`.
+- Use consistent file-level naming patterns across the same feature area.
+
+## File naming
+
+- Keep each route responsibility in its own file under `src/api/routes`.
+- Use one route module per resource or workflow, not multiple unrelated endpoints in a single file.
+- Prefer a single clear file name per route group, for example `auth/me.js`, `company/list.js`, `article/create.js`, or `journal/entries.js`.
+- Match the file name to the route’s primary resource or action so the file’s purpose is obvious from the directory tree.
+- Avoid generic names like `index.js`, `utils.js`, or `helpers.js` for route modules unless the file is truly the entry point for a module group.
+- Keep nested route directories aligned with the URL hierarchy when it improves clarity, e.g. `auth/me.js` for `/auth/me`.
+
+## API and HTTP naming
+
+- Prefer `registerRoutes` over `loadRoutes` when the function actively registers route modules on the app.
+- Prefer `buildApiApp` over `createApi` when the function constructs the Express app object.
+- Prefer `isAllowedCorsOrigin` over `isAllowedOrigin` for clarity around the specific policy being enforced.
+- When a helper adds Google client info to a response, include the domain concept in the name, e.g. `respondWithAuthenticatedUser`.
+
+## Examples from this codebase
+
+Good:
+- `registerRoutes`
+- `buildApiApp`
+- `listenOnPort`
+- `startupPromise`
+- `serverStartedAt`
+- `respondWithAuthenticatedUser`
+- `isAllowedCorsOrigin`
+- `LOCAL_PRIVATE_HOST_PATTERN`
+
+Avoid:
+- `loadRoutes` when the function actually registers route modules
+- `walk` in a route auto-loader unless it is explicitly about recursive traversal and the context is clear
+- `starting` and `startedAt` when `startupPromise` and `serverStartedAt` are more specific
+- `meJson` when the function is really a response builder for authenticated-user payloads
+- generic names like `data`, `thing`, `value`, `handle`, `doWork`
+
+## Review checklist
+
+Before finalizing a rename, ask:
+- Does the name describe the actual responsibility?
+- Does it read clearly in the local code context?
+- Is it consistent with neighboring names?
+- Is there any ambiguity about the action, domain, or response shape?
+- Is it specific enough that a teammate can infer the purpose without reading the implementation?
+
+Use these rules as the default naming standard for backend refactors and new code in the project.