Code Standards

Provides: Language-neutral maintainability rules to apply before the language-specific standards skill.

Quick Reference

Golden Rule: Code is maintainable when its behavior is easy to verify

Prefer:

• Small cohesive units with one reason to change
• Explicit inputs, outputs, errors, and dependencies
• Clear boundaries between pure logic and side effects
• Data that is not mutated in place, especially inputs owned by the caller
• Simple control flow and early exits over deep nesting
• Minimal, focused changes that preserve nearby conventions

Avoid:

• Hidden global state and surprising side effects
• Broad rewrites unrelated to the task
• Error swallowing or ambiguous failure modes
• Premature abstraction or framework cleverness

Scope note: This skill is deliberately language-neutral. Naming, formatting, file layout, and idiom rules belong to the language skill, which overrides anything here that conflicts.

Design Checks

Before editing:

• Identify the existing convention in the area you are touching.
• Find the narrowest seam for the change.
• Decide what test or command will prove the behavior.
• Load the language or framework standards skill when one exists.

While editing:

• Keep public interfaces stable unless the task requires a contract change.
• Validate data at system boundaries.
• Keep resource ownership obvious: open and close, acquire and release, start and stop.
• Make concurrency, caching, and retries explicit where used.
• Name things by domain meaning, not implementation detail.
• Do not mutate caller-provided data in place. Return new values, or make the mutation explicit in the signature and the doc comment. Silent in-place mutation of a shared slice, map, dict, or object creates aliasing bugs that surface far from the call site. Languages with legitimate in-place idioms are fine, as long as the contract says so.

Error Handling

• Preserve the original error context when wrapping or translating errors. A rethrown error that drops its cause forces the next reader to guess.
• Return or report errors at the level that can act on them.
• Do not log secrets, tokens, or unnecessary PII.
• Distinguish validation, permission, conflict, transient, and internal errors when callers need to behave differently. Collapsing them into one generic failure pushes that classification onto every caller.

Checklist

Before finishing code work:

• The smallest practical verification command has run, or is reported as skipped
• New behavior has a test where practical
• Edge cases and error paths changed by the task are covered or noted
• The diff contains no unrelated refactors
• Public interfaces are unchanged, or the contract change is intentional and documented

See also

• Load the language skill for syntax, naming, and idiom: standards-go, standards-python, standards-typescript, standards-shell, or standards-pulumi-typescript.
• Load standards-testing when writing or changing tests.
• Load standards-security for authentication, untrusted input, secrets, or sensitive data.
• Load standards-api-design for public or internal contracts.
• Load standards-database for persistence changes.
• Load standards-observability when adding logging, metrics, or tracing.