docs: Add rules hygiene guidance for AI agents (#49143)
morgankrey
and
factory-droid[bot]
created
## 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>
@@ -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 <issue-id>`
+- Generate investigation prompt from crash: `script/crash-to-prompt <issue-id>`
+
+# 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.