chore: guardrails to prevent giant files and dep-version drift #394

Merged

jwilger merged 1 commit from chore/guardrail-update-module-and-dep-consistency into main

2026-06-12 22:55:06 -07:00

jwilger commented

2026-06-12 22:14:55 -07:00

Owner

Summary

Generation guardrails arising from the review feedback on PR #390 (the
eventcore-fs backend). Two lessons came out of that review:

A single ~1600-line lib.rs — too large to work with comfortably.
Dependency versions in a new crate that did not obviously match sibling
crates, and a question about how versions stay consistent.

Per our review-feedback protocol, these go in their own guardrails PR. I chose
generation guardrails (rules an agent reads before writing code) over
auto-review review instructions because prevention is more token-efficient than
catching the same issues in a review round-trip and re-doing the work.

Changes

.claude/rules/module-organization.md (new) — keep source files focused
on one responsibility; split into responsibility-named modules before a file
grows monolithic; lib.rs is a thin facade that declares modules and
re-exports the public API. Includes a concrete Rust split.
.claude/rules/cargo-dependencies.md — adds a Version Consistency Across
Crates section: match sibling crates' dependency version requirements; how
Cargo's lockfile unifies SemVer-compatible versions; and that lockstep
path-dependency versions (ADR-025) are intentional, not drift.

These would have prevented both review comments at generation time.

🤖 Generated with Claude Code

## Summary Generation guardrails arising from the review feedback on PR #390 (the `eventcore-fs` backend). Two lessons came out of that review: 1. A single `~1600-line lib.rs` — too large to work with comfortably. 2. Dependency versions in a new crate that did not obviously match sibling crates, and a question about how versions stay consistent. Per our review-feedback protocol, these go in their own guardrails PR. I chose **generation guardrails** (rules an agent reads *before* writing code) over auto-review review instructions because prevention is more token-efficient than catching the same issues in a review round-trip and re-doing the work. ## Changes - **`.claude/rules/module-organization.md`** (new) — keep source files focused on one responsibility; split into responsibility-named modules before a file grows monolithic; `lib.rs` is a thin facade that declares modules and re-exports the public API. Includes a concrete Rust split. - **`.claude/rules/cargo-dependencies.md`** — adds a *Version Consistency Across Crates* section: match sibling crates' dependency version requirements; how Cargo's lockfile unifies SemVer-compatible versions; and that lockstep path-dependency versions (ADR-025) are intentional, not drift. These would have prevented both review comments at generation time. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jwilger added 1 commit

2026-06-12 22:14:55 -07:00

chore: guardrails to prevent giant files and dep-version drift

CI / Detect Changes (pull_request) Successful in 3s

Details

CI / Request auto_review semantic review (pull_request) Successful in 1s

Details

CI / Test (pull_request) Has been skipped

Details

auto_review auto_review: no findings

CI / Clippy (pull_request) Has been skipped

Details

CI / Security Audit (pull_request) Has been skipped

Details

CI / Mutation (pull_request) Has been skipped

Details

CI / Format (pull_request) Successful in 14s

Details

CI / CI Gate (pull_request) Successful in 1s

Details

c52b76b38d

Generation guardrails arising from PR #390 review feedback. Prevention
(an agent reads .claude/rules before writing code) is more token-efficient
than catching these in review, so these are generation guardrails rather
than auto-review instructions.

- module-organization.md (new): keep source files focused on one
  responsibility; split into responsibility-named modules before a file
  grows monolithic; lib.rs is a thin facade with re-exports.
- cargo-dependencies.md: add a Version Consistency section — match sibling
  crates' dependency version requirements; explains Cargo lockfile
  unification and that lockstep path-dep versions (ADR-025) are not drift.

auto-review approved these changes

2026-06-12 22:15:03 -07:00

auto-review left a comment

Walkthrough

Module Organization Guidelines:
- Introduces a new file .claude/rules/module-organization.md.
- Emphasizes keeping source files focused on a single responsibility.
- Provides a structured approach to splitting large files into modules based on responsibility.
- Suggests a typical module split for Rust crates, enhancing readability and maintainability.
Dependency Version Consistency:
- Updates .claude/rules/cargo-dependencies.md with a new section on version consistency.
- Advises matching dependency versions with sibling crates to maintain consistency.
- Explains how Cargo's resolver and lockfile handle version unification.
- Highlights the importance of avoiding divergent major versions unless necessary.

LLM usage and cost

Reasoning (gpt-4o) in=2107 out=226 cost=$0.013925
Cheap (gpt-4o-mini) in=591 out=46 cost=$0.000116
Estimated total USD: $0.014041 via https://api.openai.com and https://api.openai.com

This PR introduces generation guardrails to prevent large source files and ensure dependency version consistency across crates. The changes include new guidelines for module organization and dependency management, aiming to improve code maintainability and consistency. The additions appear safe to merge as they provide clear instructions for future code generation. ## Walkthrough - **Module Organization Guidelines**: - Introduces a new file `.claude/rules/module-organization.md`. - Emphasizes keeping source files focused on a single responsibility. - Provides a structured approach to splitting large files into modules based on responsibility. - Suggests a typical module split for Rust crates, enhancing readability and maintainability. - **Dependency Version Consistency**: - Updates `.claude/rules/cargo-dependencies.md` with a new section on version consistency. - Advises matching dependency versions with sibling crates to maintain consistency. - Explains how Cargo's resolver and lockfile handle version unification. - Highlights the importance of avoiding divergent major versions unless necessary. ## LLM usage and cost - Reasoning (gpt-4o) in=2107 out=226 cost=$0.013925 - Cheap (gpt-4o-mini) in=591 out=46 cost=$0.000116 Estimated total USD: $0.014041 via https://api.openai.com and https://api.openai.com

jwilger merged commit 07bd4e043c into main

2026-06-12 22:55:06 -07:00

jwilger deleted branch chore/guardrail-update-module-and-dep-consistency

2026-06-12 22:55:06 -07:00

jwilger referenced this pull request from a commit

2026-06-12 22:55:08 -07:00

chore: guardrails to prevent giant files and dep-version drift (#394)