Principles
Rationale, tradeoffs, and limits behind related rules and patterns.
Principle areas
Agents and shared context
Agent instructions, public rationale, and repeated feedback.
Agent Instructions Are Operational Controlsagent-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 Contractsdocs-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 Feedbackmechanize-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 Contextprivate-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 Failurestests-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, review, and locality
Change shape, reader locality, and review cost.
Change Shape Controls Review Costchange-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-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 Optimizingmeasure-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 Costreader-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.
Boundaries, APIs, and state
Explicit boundaries, public API cost, and mutable state.
Avoid Global Mutable Stateavoid-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 Correctnessexplicit-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-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.