Code Quality Architecture

Code quality and architecture expectations

Use this skill as a design lens, not as a framework tutorial. The goal is to shape code so future agents and humans can understand it, change it safely, and test it without needing to reverse-engineer hidden coupling.

For test-specific strategy, test helper conventions, and UI test harness choices, use the testing-guide skill. This skill still treats testability as a production-code design concern.

Respect the project's existing conventions and the framework/library idioms already in use. If a dependency expects a particular pattern, such as inheritance, decorators, lifecycle hooks, or a registration API, use that pattern deliberately and keep the surrounding project code as simple and composable as possible.

Values we optimize for

Proportionate

Start with the simplest design that meets the behavioral contract and finish line. Prefer boring, local changes that solve the problem without surprising future maintainers.

When an edge case or race is identified, assess its plausible frequency and consequence before adding special handling. Address it now when the contract requires it, it is reasonably likely in normal use, or its impact justifies the added complexity. Otherwise defer special handling, rely on ordinary observable failure or recovery behavior, and revisit if real usage shows that the case matters. Do not defer cases with a credible risk of corrupting durable state, weakening a security or authorization boundary, or failing silently without a practical recovery path.

Avoid unrelated refactoring, opportunistic cleanup, and broad rewrites unless the task requires them. Avoid new abstractions that add ceremony without clarifying ownership, reducing duplication, isolating volatility, or improving testability.

Composable

Build behavior from small pieces with explicit contracts. Prefer functions, modules, factories, services, components, or adapters that can be combined without knowing each other's internals.

Prefer composition over inheritance. Reach for inheritance only when a framework/dependency requires it, when it clearly models a stable relationship, or when it is already the local convention. If you use inheritance, keep the hierarchy shallow and explain the reason in the design or final summary.

Contained

A unit of code should do its job without leaking state, assumptions, or side effects across the system. Keep effects at clear boundaries: network, filesystem, timers, process state, browser APIs, storage, logging, telemetry, and UI/event dispatch.

Make state ownership explicit: who owns it, who may mutate it, when it is created, and how it is cleaned up. Avoid hidden global coordination, surprise mutation, ad hoc event dispatch, and imports that perform work merely by being loaded. If code must produce side effects, make the trigger, scope, cleanup, and failure behavior visible.

Clear intention

Names, types, file boundaries, and function boundaries should reveal why the code exists. Prefer a small amount of clear structure over clever compactness.

Use types to express domain meaning, valid states, and boundaries between parts of the system. Do not duplicate lint/type rules here; the point is to make the design easier to understand, not merely to satisfy TypeScript.

Comments are most valuable when they explain why a decision exists, what invariant must be preserved, or why an apparent simpler approach would be unsafe. Avoid comments that merely restate the code.

Clear separation of concerns

Keep domain decisions, orchestration, framework glue, persistence, transport, rendering, and validation separate when that separation makes the code easier to reason about.

Framework-facing code should usually be thin: gather inputs, call the core logic, map results back to the framework. Core logic should usually be usable without starting the UI, server, session runtime, browser, filesystem, or network.

Deliberate error handling

Failures must be observable and traceable to their cause. Handle them at meaningful boundaries through an explicit return or throw, contextual logging, a user-visible error, or another signal appropriate to that boundary. Do not silently rescue failures, swallow errors, or turn them into vague fallback or success behavior. Avoid scattering defensive try/catch blocks everywhere; let core logic communicate failures clearly, then translate them at the edge that has the right context.

When changing PI WEB-managed durable state, structure operations so failure does not silently leave partial writes, ambiguous overwrites, or broken invariants. Apply this where an actual persistence or lifecycle boundary warrants it; do not add transactional machinery to ephemeral or reconstructible state without a concrete need.

Security and authorization boundaries fail closed. Never convert a validation, authentication, authorization, or policy failure into permissive behavior merely to keep an operation running.