Coding Standards

Produce code a colleague can follow: a directory structure that shows the domain, small files that each hold one named responsibility, domain concepts as explicit types, direct control flow, ordinary names, and an explanation wherever code cannot show the reason. Review or diagnosis returns findings without implementing them. A change request includes its relevant local checks and nothing more: no repository-wide migration, cleanup, restructuring, or publication, and a pre-existing problem met on the way is a follow-up in the summary, not a change.

Start from the repository

Read the project instructions and written rules, the language and runtime support range, dependency constraints, nearby implementation and tests, and configured checks before choosing syntax, layout, or tools; then read the language reference for each language the change touches. Existing public imports, accepted inputs, serialized values, and persisted data stay compatible unless the request includes a migration. The current request takes precedence, then the project's written rules and explicit repository constraints, then this skill's defaults, which apply where the project is silent, to new and changed code; mixed existing style is not an exemption. In a repository the user does not own, a convention the touched module follows consistently counts as a repository constraint for style-only rules, such as annotating every local; mixed style there is still not an exemption. Preserve configured formatters, linters, type checkers, and test runners unless their change is in scope, and report a conflict with an older runtime or incompatible tooling instead of breaking support.

Name the responsibilities

Give each function a caller-visible responsibility and make data flow and side effects clear. When a new module or multi-phase task has unclear boundaries, a skeleton of typed signatures and short contract comments can expose them before implementation. Use it when it helps; an existing cohesive function or a small change does not need a separate skeleton pass. Revise boundaries as the implementation supplies evidence. Names that only describe position (step_two, process_data, helper) prompt a review of the responsibility. Resolve a consequential contract ambiguity from the request or repository; do not turn an unverified assumption into a promised documented contract.

A block is its own function when a reader would otherwise have to work out what it does and it hands back one named value, decision, or effect through a small signature. Call count decides nothing: a responsibility called once still earns a function, and a "one-time operation" that needs no helper is a statement or two, not a named step of the algorithm. Keep a block inline when extracting it would need more than about four inputs, return several unrelated locals, or leave either function unreadable without the other. Flatten before splitting, with early returns and a lookup table or pattern match in place of a chain of conditionals over constants. Keep parsing, computation, and output as phases joined by a named record type; I/O and mutation of shared state live in the orchestrating function, the computation beneath stays pure, and a function that mutates says so in its name or documentation. A comment that says what a block does is a prompt to extract or rename; a comment that says why stays.

A finished function has a name and contract that express one coherent responsibility, a caller whose flow and side effects are clear from its callees, and a boundary that improves understanding. A conjunction such as "and" can describe related parts of one responsibility; inspect the meaning rather than banning a word. A complexity or statement-count lint finding prompts a review of decomposition under the repository's rules, never a split by line ranges into numbered helpers or a suppression without a reason. Read functions and modules for the optional skeleton, the intent tests, the size prompts and gates, and the procedure for moving code.

Structure

Split directories by domain first and by responsibility inside each domain, as deep as the boundaries warrant. A boundary is real when the code on each side has its own vocabulary, its own reason to change, or its own I/O. Keep files small: each holds one responsibility a reader can state in a sentence, split by reason to change and never by kind or line range. At about 500 handwritten lines, split at a boundary you can name; a file past 1,000 needs a reason in the change summary. A one-off script, notebook-adjacent analysis, or tool that is genuinely one responsibility stays one file until it gains a second entry point, importer, or responsibility. Depth is not scaffolding: a directory or file exists because it has content, never as a placeholder or a per-feature template.