docs: Add rules hygiene guidance for AI agents (#49143)

## 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>
This commit is contained in:
morgankrey 2026-02-13 16:59:00 -06:00 committed by GitHub
parent 6db4a25b37
commit 63ea24259a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

32
.rules
View file

@ -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.