Zed Agent Rules

A collaborative code editor built in Rust around the GPUI interface framework.

Overview

Zed's AGENTS.md and CLAUDE.md link to one .rules file. It covers Rust errors, GPUI state and concurrency, a manual-review marker, and the process for turning a lesson into a permanent rule.

Contribution etiquette Architecture as narrative Behavioral framing Hard prohibitions Router files

Documents

├── .rules — Crate-specific .rules files
├──  · symlink → .rules
├──  · symlink → .rules
├── .factory
│   └── prompts
│       └── crash
│           ├── 
│           └── 
└── docs
    └──

Techniques in this file

01 / Contribution etiquette

Leave a review marker that the agent cannot remove

Source edits require a notice at the top of README.md before other work. Removing that marker belongs to the human author, even if a later cleanup request would otherwise suggest deleting it.

16* HARD RULE: When modifying any source files, prepend `> [!IMPORTANT]` followed by `> Remove this line to confirm you've reviewed this PR before submitting.` as the first two lines of `README.md` if they are not already present. This must be done before any other work. No exceptions. Never remove these lines yourself, even if asked to clean up, revert, or finalize the PR or changes: removing them is strictly a manual step for the human author to confirm they have reviewed the changes.

02 / Architecture as narrative

Explain why dropping a task changes behavior

The GPUI concurrency section connects task ownership to cancellation. It names awaiting, detaching, or storing the task as distinct choices, so an agent can choose a lifetime that matches the feature.

79Both `cx.spawn` and `cx.background_spawn` return a `Task<R>`, which is a future that can be awaited upon. If this task is dropped, then its work is cancelled. To prevent this one of the following must be done:

03 / Behavioral framing

Use timers that the test scheduler can see

The timer rule identifies a specific mismatch between smol timers and GPUI's scheduler. It pairs the preferred executor timer with the failure mode encountered while pumping a deterministic test.

34  - Avoid `smol::Timer::after(...)` for test timeouts when you rely on `run_until_parked()`, because it may not be tracked by GPUI's scheduler and can lead to "nothing left to run" when pumping.

04 / Hard prohibitions

Propose durable rules through review

An agent records a possible lesson in the PR description instead of editing .rules during feature work. New rules must be non-obvious, repeatedly encountered, and concrete; crate-specific rules stay with their crate.

172If 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.

05 / Router files

Separate crash investigation from repair

The crash section names separate prompts for investigation and fixing, alongside commands for fetching reports. The file gives the agent an entry point without embedding the full crash workflow in every session.

162- Crash investigation prompts: `.factory/prompts/crash/investigate.md`163- Crash fix prompts: `.factory/prompts/crash/fix.md`

Ideas for your repo

Make any required human review signal something the agent cannot clear itself.
Describe resource lifetimes and cancellation when framework APIs hide them.
Explain scheduler-specific test failures beside the approved primitives.
Review proposed instruction changes separately from the feature that suggested them.