# Coding Conventions

> Internal reference skill — coding standards and patterns for developer agents. Not user-invocable.

- Skill: `alexandrbasis/coding-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alexandrbasis/coding-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexandrbasis/coding-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, AI & ML
- Author: alexandrbasis (https://skillmd.com/u/alexandrbasis)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/alexandrbasis/coding-conventions

---


# Coding Conventions

Shared knowledge preloaded into developer agents. Follow these when implementing features.

## Project context

This is a portable reference, not a generated project profile. Before making a
project-specific choice, read an applicable `CLAUDOPS.md` and inspect the
repository's manifests, source layout, CI configuration, and existing code.
Use the project's own framework, language, layers, test runner, and commands;
unknown values stay explicit until evidence is available. Do not treat
`{{...}}` markers as commands or fill them with guesses. Preserve existing
local conventions when no profile is present.

## Code Style

- Match the project's existing type/interface conventions — new code should look
  like it was written by the same person as the surrounding code.
- Preserve the project's type and naming conventions. Apply language-specific
  rules (including `any`, underscore prefixes, or equivalent) only when the
  language tooling or local style establishes them.
- Route secrets through config providers only — never hardcoded, never logged
  (logs ship to observability tools; hardcoded secrets leak via git history).
- Keep DTOs aligned with API schemas and the tech-decomposition's acceptance
  criteria — these are the contract downstream consumers rely on.
- Use parameter binding for database queries (not string interpolation) to prevent
  SQL injection.

## Testing

- **TDD**: RED → GREEN → REFACTOR — vertical slices only (one RED→GREEN per behavior). Canonical: `.claude/skills/tdd/SKILL.md`.
- Discover test, lint, and type-check commands from the project manifest, CI,
  profile, or documented scripts. If a check has no supported command, report
  it as unavailable rather than executing a placeholder.
- Find test files from the repository's actual layout and naming patterns.
- Arrange-Act-Assert pattern, descriptive test names
- Proper mocking of data-access layer in unit tests

## Implementation Rules

- Start by reading the task document — it's the source of truth for what to build,
  and implementation choices should flow from it rather than from prior assumptions.
- Resolve the task through `../setup/references/task-context.md` when this is a
  task-attached run; standalone implementation guidance does not create a synthetic task.
- Write the minimum code that makes the tests pass and the acceptance criteria
  hold. Don't add features, abstractions, or cleanup that weren't asked for.
- Bug fixes don't need surrounding refactors — fix the bug, leave the rest.
- Skip defensive error handling for scenarios that can't actually happen in this
  codebase's flow.
- Match existing codebase patterns — new code should look like it belongs.
- No git writes unless explicitly approved by orchestrator

## Engineering Principles

Named heuristics worth applying by name (mostly from *Software Engineering at Google* and Ousterhout's *A Philosophy of Software Design*):

- **Chesterton's Fence** — don't remove or rewrite code whose purpose you don't understand. Find out why it's there first; "it looks unnecessary" is not a reason.
- **Code is a liability** — every line is maintenance surface, not an asset. The best change is often less code; prefer deleting over adding.
- **Hyrum's Law** — with enough users, every observable behavior of an interface will be depended on. "It's just an implementation detail" doesn't make a change safe — treat observable behavior as the contract.
- **Deep modules** — hide substantial functionality behind a narrow, simple interface. Many shallow pass-through layers add complexity without earning it.