Rules
Compact rules for common engineering decisions, grouped by work area: documentation, Rust APIs, testing, review, source control, and agent workflow.
282 rules13 domains1 compressed agent pack
Using the rules
Tags mark work areas: DOCS for documentation, VCS for jj and source control, RUST for crate shape, and AGENT for coding-agent work.
Rule pages include rationale, limits, mechanisms, and source links. Downstream repositories can copy compact instructions without copying the full explanation.
Rule work areas
Agent WorkflowAgent workflow rules cover objectives, scoped capabilities, durable context, review packets, security proof, feedback loops, and concrete next choices.Change ShapeChange-shape rules cover one-purpose changes, small follow-ups, generated artifacts, dependency churn, ownership, and structure-versus-behavior review boundaries.Docs Are ContractsDocumentation rules cover docs-as-contracts, rendered docs, examples, reviewability, source links, concrete prose, and drift checks.Explicit Boundaries Preserve CorrectnessBoundary rules cover parsing, validation policy, explicit inputs, state transitions, provider diagnostics, effect boundaries, and external reconciliation.JJ Topology and Source ControlVCS rules cover jj-first source-control work, remote topology, operation-log recovery, workspaces, publication safety, and file-tracking decisions.Local Reasoning and RefactoringRefactoring rules cover local reasoning, concept helpers, visible linear stories, side-effect loops, whitespace paragraphs, DRY pressure, and weak abstractions.Measure Before OptimizingPerformance rules cover measuring before optimizing, benchmark provenance, single-run skepticism, correctness gates, and the cost of complexity or dependency churn.Observability and FailureObservability rules cover owned logging boundaries, durable failure visibility, diagnostic context, failure states, and safe telemetry retention.Private Context and Review ArtifactsReview artifact rules cover issue slices, PR narratives, ADRs, speculation labels, thread ownership, and artifacts that stand alone without private session context.Rust API and Crate ShapeRust rules cover public API shape, crate layout, dependency policy, docs.rs behavior, feature flags, public errors, unsafe boundaries, and release checks.Source and Context HygieneSource hygiene rules cover turning mined lessons into public guidance, preferring stable sources, keeping binary artifacts out of history, and keeping local or private context out...Testing and VerificationTesting rules cover risk-based validation, doctests, feature matrices, deterministic tests, parser samples, command construction, dependency floors, and regressions.Tests Should Explain FailuresTest-failure rules cover assertion shape and failure output that help humans and agents diagnose the failing case quickly.