Principles

Rationale, tradeoffs, and limits behind related rules and patterns.

Principles are durable reasoning notes. They explain why a set of rules exists, where the rules apply, where they stop applying, and what an agent or maintainer should do with the judgment.

Use a principle when the topic is broader than a single repeatable move. Use a pattern when the idea has a recognizable "when you see this, do that" shape. Use a mechanism when the important thing is a lint, formatter, command, CI check, or tool configuration.

Agent instructions are operational controlsAgent instructions should change future behavior, not merely restate a preference. Compact rules need enough trigger, purpose, and boundary context for agents to apply them without blind literalism.Docs are contractsDocumentation near code is part of the supported behavior surface. Keep prose, examples, and implementation aligned so humans and agents can rely on the same contract.Mechanize repeated feedbackRepeated corrections should become checks, templates, generators, lints, or reusable guidance when the pattern is stable. Mechanizing the feedback moves human attention back to judgment instead of recall.Private context is not shared contextShared artifacts must carry the reasoning that downstream readers did not see in the private session. Issues, PRs, commits, guides, and review packets should restate the decision context that matters.Tests should explain failuresA failing test should point at the broken contract, not merely report that a predicate was false. Choose assertion shapes that expose the relevant value, variant, order, or case name.

Change shape controls review costChange boundaries determine how much intent, risk, validation, and revert cost a reviewer must reconstruct. Use the smallest coherent unit that preserves trust without splitting one decision into noise.JJ topology is repo role dependentJJ publication behavior depends on whether the checkout is owned, maintained, or fork-based. Align remotes, bookmarks, trunk, and GitHub handoff with that role before mutating public state.Measure before optimizingPerformance work needs a workload, baseline, goal, change, and comparison. Evidence keeps optimization from becoming readability, dependency, or API churn without a proven payoff.Reader locality reduces change costCode is cheaper to change when the reader can understand the local decision without distant facts. Keep related state, inputs, side effects, and policy close enough to inspect together.

Avoid global mutable stateMutable process-wide state hides ownership, lifecycle, reset, ordering, and concurrency policy. Prefer explicit owners or narrow handles unless the global behavior has a documented policy.Explicit boundaries preserve correctnessMove uncertainty into named boundary policy before core logic uses the data. Parsed inputs, explicit side effects, and visible lifecycle transitions reduce repeated downstream guessing.Public API changes have downstream costPublic API edits impose migration, semver, documentation, and integration costs beyond the local diff. Prefer additive paths and explicit migration proof when a break is justified.