Skip to content

tobihagemann/turbo / claude/skills/code-style

code-style

Verified

Enforce existence, reuse, mirror, and symmetry principles so new code stays minimal and consistent. Use when writing, changing, or refactoring code in an existing codebase.

Code Style: Exist, Reuse, Mirror, Symmetry

When writing new code in an existing codebase, work through these in order. When two pull in different directions, the earlier one wins.

  1. Establish that the code needs to exist: Drop work the request does not need — an abstraction with one implementation, a configuration point with one caller, a branch for a state the callers cannot reach, scaffolding for an anticipated requirement. Deleting or narrowing beats adding. Before removing code that already exists, trace its callers and confirm nothing depends on the behavior. A new test must earn its place too: before adding one, name the behavior it protects and the credible regression that makes it fail, and confirm no existing test already fails on that regression. When a mutation run checks the new test, read every test that fails under it, not only the new one: if existing tests also fail, keep the new test only for a regression they miss. When an existing test covers the same contract, extend its cases instead. Drive the test through a boundary production code already uses rather than adding an export, flag, or hook that only the test calls. A test pins the behavior it is named for: when one you add or change also covers another behavior only through how it is set up, give that behavior its own test unless another test already fails when it breaks, and set the first test up the way its siblings are. Input validation at trust boundaries, error handling that prevents data loss, security controls, accessibility affordances, and anything explicitly requested outrank this rule.
  2. Reuse existing code: Before writing a new helper, check if an existing method can be reused or generalized. If a new helper is needed, model it after its closest sibling that is not debt (as rule 3 defines it).
  3. Reuse existing patterns: Find the closest analogous feature and replicate its structure (method decomposition, control flow, annotations, guard clauses). When an existing pattern fits, use it rather than introducing a new one. When following it would force materially more code or indirection than a different approach, take the different approach and apply it across the whole change. Treat as debt a workaround for a problem inside the codebase, a deprecated API with a usable replacement, a suppression directive with no stated reason, or a TODO marking code temporary. When the closest analog contains debt, replicate its structure without the debt; when its structure is the debt, pass over it and follow the next clean one, and when none is clean, write the clean form, marking any workaround it cannot avoid as rule 7 directs. Name each skipped analog and omitted piece of debt when you report the change.
  4. Mirror the surrounding code exactly: Match brace style, comment style, naming conventions, blank line spacing, code density, and level of detail by reading nearby code first.
  5. Maintain symmetry: If adding fooB() parallel to fooA(), match naming, parameter order, and structure. Symmetry covers every name the new sibling makes asymmetric: identifiers, route paths, config keys, event names, environment variables, CLI flags, and file naming schemes. Rename the existing name by default; keep it as it stands only when it is a published contract whose consumers you cannot update, or cannot update in step with the rename. Treat deployment and registration as costs the change absorbs: updating every place the name is referenced or registered is part of the change.
  6. Logical ordering: Place new methods, switch cases, and fields in the order that mirrors the existing grouping or business lifecycle, rather than appending at the end.
  7. Default to no comment: Write code that self-explains through naming, extraction, and structure. When you reach for a comment, first try refactoring so it becomes unnecessary. Add one only for a load-bearing constraint the code cannot express (a hidden invariant, a workaround for a defect outside the codebase, with a reference to that defect where one exists, a non-obvious performance characteristic). For a problem inside the codebase, fix the root cause rather than writing a workaround with a comment justifying it. When that fix is out of reach, mark the workaround with a TODO that names the root cause and gives no reason the workaround is acceptable, and name it as debt when you report the change. When in doubt, omit the comment.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall