mirror of
https://github.com/zed-industries/zed.git
synced 2026-06-01 03:14:56 +07:00
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:
parent
6db4a25b37
commit
63ea24259a
1 changed files with 32 additions and 0 deletions
32
.rules
32
.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 <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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue