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

Rules are compact instructions supported by the guides, principles, patterns, and mechanisms in this repo. Each rule has its own file so it can be reviewed, deepened, linked, and extracted into compressed agent instructions independently.

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.

Agent rule pack

Rule work areas

AGENT26 rulesAgent workflowAgent workflow rules cover objectives, scoped capabilities, durable context, review packets, security proof, feedback loops, and concrete next choices.CHANGE13 rulesChange shapeChange-shape rules cover one-purpose changes, small follow-ups, generated artifacts, dependency churn, ownership, and structure-versus-behavior review boundaries.DOCS35 rulesDocs are contractsDocumentation rules cover docs-as-contracts, rendered docs, examples, reviewability, source links, concrete prose, and drift checks.BOUNDARY27 rulesExplicit boundaries preserve correctnessBoundary rules cover parsing, validation policy, explicit inputs, state transitions, provider diagnostics, effect boundaries, and external reconciliation.VCS28 rulesJJ topology and source controlVCS rules cover jj-first source-control work, remote topology, operation-log recovery, workspaces, publication safety, and file-tracking decisions.REFACTOR9 rulesLocal reasoning and refactoringRefactoring rules cover local reasoning, concept helpers, visible linear stories, side-effect loops, whitespace paragraphs, DRY pressure, and weak abstractions.PERF7 rulesMeasure before optimizingPerformance rules cover measuring before optimizing, benchmark provenance, single-run skepticism, correctness gates, and the cost of complexity or dependency churn.OBSERVE7 rulesObservability and failureObservability rules cover owned logging boundaries, durable failure visibility, diagnostic context, failure states, and safe telemetry retention.REVIEW11 rulesPrivate 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.RUST90 rulesRust 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.SOURCE4 rulesSource 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...TEST22 rulesTesting and verificationTesting rules cover risk-based validation, doctests, feature matrices, deterministic tests, parser samples, command construction, dependency floors, and regressions.FAILURE3 rulesTests should explain failuresTest-failure rules cover assertion shape and failure output that help humans and agents diagnose the failing case quickly.

Rule file shape

Each rule file should keep these sections:

Metadata: stable ID, portable name, summary, status, domain, tags, and related links.
Rule: the direct human-readable instruction.
Why: rationale when the rule needs justification or tradeoff framing.
Helps: concrete development outcomes the rule improves.
Limits: exceptions, costs, or counter-signals.
Agent Instruction: compressed wording suitable for agent execution packs.
Mechanisms: lints, formatters, CI checks, commands, or workflows that support the rule.
References: durable sources that support, adapt, or contrast the rule in a useful way.

Rules can stay compact when the rationale is obvious, but compact should still mean finished. A rule should explain the failure mode, tradeoff, or design pressure well enough that a reviewer does not need the original source material to understand why it exists. Prefer concrete surfaces and examples over abstract categories when the reader would otherwise have to infer applicability.

Agent instructions are not repeated titles. They should encode the trigger, failure mode, or useful constraint that helps an agent apply the rule without blindly doing the literal shortest version of the instruction.

Naming

Use uppercase, dash-separated IDs:

DOCS-TREAT-DOCS-AS-CONTRACTS
RUST-KEEP-PUBLIC-API-SHAPE-INTENTIONAL
VCS-JJ-AS-SOURCE-OF-TRUTH
TEST-OPTIMIZE-FAILURE-OUTPUT
OBSERVABILITY-PRESERVE-OPERATION-CONTEXT-IN-ERRORS

Do not abbreviate broad family names in public rule IDs. Use OBSERVABILITY, not OBS.

Rule IDs are handles, not compressed titles. A good ID is short enough to cite in reviews, preserves the rule's real concept, and keeps connector words when dropping them would change the meaning. Prefer a verb-oriented handle when the rule is an action, and use domain nouns plus a decisive verb and object. Write titles as direct instructions when possible.