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.
1---2name: coding-conventions3description: "Internal reference skill — coding standards and patterns for developer agents. Not user-invocable."4metadata:5 source: https://skillmd.com/skills/alexandrbasis/coding-conventions6---78# Coding Conventions910Shared knowledge preloaded into developer agents. Follow these when implementing features.1112## Project context1314This is a portable reference, not a generated project profile. Before making a15project-specific choice, read an applicable `CLAUDOPS.md` and inspect the16repository's manifests, source layout, CI configuration, and existing code.17Use the project's own framework, language, layers, test runner, and commands;18unknown values stay explicit until evidence is available. Do not treat19`{{...}}` markers as commands or fill them with guesses. Preserve existing20local conventions when no profile is present.2122## Code Style2324- Match the project's existing type/interface conventions — new code should look25 like it was written by the same person as the surrounding code.26- Preserve the project's type and naming conventions. Apply language-specific27 rules (including `any`, underscore prefixes, or equivalent) only when the28 language tooling or local style establishes them.29- Route secrets through config providers only — never hardcoded, never logged30 (logs ship to observability tools; hardcoded secrets leak via git history).31- Keep DTOs aligned with API schemas and the tech-decomposition's acceptance32 criteria — these are the contract downstream consumers rely on.33- Use parameter binding for database queries (not string interpolation) to prevent34 SQL injection.3536## Testing3738- **TDD**: RED → GREEN → REFACTOR — vertical slices only (one RED→GREEN per behavior). Canonical: `.claude/skills/tdd/SKILL.md`.39- Discover test, lint, and type-check commands from the project manifest, CI,40 profile, or documented scripts. If a check has no supported command, report41 it as unavailable rather than executing a placeholder.42- Find test files from the repository's actual layout and naming patterns.43- Arrange-Act-Assert pattern, descriptive test names44- Proper mocking of data-access layer in unit tests4546## Implementation Rules4748- Start by reading the task document — it's the source of truth for what to build,49 and implementation choices should flow from it rather than from prior assumptions.50- Resolve the task through `../setup/references/task-context.md` when this is a51 task-attached run; standalone implementation guidance does not create a synthetic task.52- Write the minimum code that makes the tests pass and the acceptance criteria53 hold. Don't add features, abstractions, or cleanup that weren't asked for.54- Bug fixes don't need surrounding refactors — fix the bug, leave the rest.55- Skip defensive error handling for scenarios that can't actually happen in this56 codebase's flow.57- Match existing codebase patterns — new code should look like it belongs.58- No git writes unless explicitly approved by orchestrator5960## Engineering Principles6162Named heuristics worth applying by name (mostly from *Software Engineering at Google* and Ousterhout's *A Philosophy of Software Design*):6364- **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.65- **Code is a liability** — every line is maintenance surface, not an asset. The best change is often less code; prefer deleting over adding.66- **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.67- **Deep modules** — hide substantial functionality behind a narrow, simple interface. Many shallow pass-through layers add complexity without earning it.