From 63ea24259a51a94a46d01a8eda69e7cf0eee01eb Mon Sep 17 00:00:00 2001 From: morgankrey Date: Fri, 13 Feb 2026 16:59:00 -0600 Subject: [PATCH] docs: Add rules hygiene guidance for AI agents (#49143) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Adds a "Rules Hygiene" section to `.rules` after the existing Build Guidelines section - Establishes clear guidelines for when/how AI agents should propose `.rules` changes - Adds a "Crash Investigation" section with reference to `script/crash-to-prompt` and other crash tooling ## What's in the Rules Hygiene section **After any agentic session:** Agents should include a "Suggested .rules additions" heading in their PR description if they discover non-obvious patterns. Reviewers decide what gets merged. **High bar for new rules:** Editing existing rules is always welcome. New rules must be (1) non-obvious, (2) repeatedly encountered, and (3) specific enough to act on. Single-crate rules go in that crate's `.rules`. **No drive-by additions:** Rules emerge from validated patterns through a 3-step workflow: agent notes pattern → team validates → dedicated commit. ## Context Part of the Background Agent Pipeline initiative (BIZOPS-801). As we scale automated crash investigation, we need guardrails to prevent `.rules` bloat from agent sessions. ## Test plan - [ ] Open a test agent session and confirm it sees the Rules Hygiene guidance - [ ] Verify the guidance is clear enough to follow without additional context 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- .rules | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/.rules b/.rules index 5965f5a185a9df47f5fce48bed4d677fa2937d0a..8ed1157775e8f4e0446edafbf960170753cf50c1 100644 --- a/.rules +++ b/.rules @@ -136,3 +136,35 @@ Other entities can then register a callback to handle these events by doing `cx. ## Build guidelines - Use `./script/clippy` instead of `cargo clippy` + +# Crash Investigation + +## Sentry Integration +- Crash investigation prompts: `.factory/prompts/crash/investigate.md` +- Crash fix prompts: `.factory/prompts/crash/fix.md` +- Fetch crash reports: `script/sentry-fetch ` +- Generate investigation prompt from crash: `script/crash-to-prompt ` + +# Rules Hygiene + +These `.rules` files are read by every agent session. Keep them high-signal. + +## After any agentic session +If you discover a non-obvious pattern that would help future sessions, include a **"Suggested .rules additions"** heading in your PR description with the proposed text. Do **not** edit `.rules` inline during normal feature/fix work. Reviewers decide what gets merged. + +## High bar for new rules +Editing or clarifying existing rules is always welcome. New rules must meet **all three** criteria: +1. **Non-obvious** — someone familiar with the codebase would still get it wrong without the rule. +2. **Repeatedly encountered** — it came up more than once (multiple hits in one session counts). +3. **Specific enough to act on** — a concrete instruction, not a vague principle. + +Rules that apply to a single crate belong in that crate's own `.rules` file, not the repo root. + +## What NOT to put in `.rules` +Avoid architectural descriptions of a crate (module layout, data flow, key types). These go stale fast and the agent can gather them by reading the code. Rules should be **traps to avoid**, not **maps to follow**. + +## No drive-by additions +Rules emerge from validated patterns, not one-off observations. The workflow is: +1. Agent notes a pattern during a session. +2. Team validates the pattern in code review. +3. A dedicated commit adds the rule with context on *why* it exists.