Files
zed/docs/AGENTS.md
T
Sha1rholder a57e2fdc38 Unifying agent instructions to AGENTS.md (#66716)
## Summary

Closes #66715

It's a follow-up of #45939

## Testing

This PR includes two commits. The first commit only removes CLAUDE.md
and GEMINI.md, and the second involves changes to
[dangerfile.ts](https://github.com/zed-industries/zed/blob/main/script/danger/dangerfile.ts).

Reset the second if not favored.

## Self-review

- [x] I've reviewed my diff for quality, security, reliability, and
performance.
- [x] UI changes follow the
[checklist](https://zed.dev/docs/development/ui-checklist).
- [x] Tests cover the new or changed behavior.

Release Notes:

- N/A

---------

Co-authored-by: Smit Barmase <heysmitbarmase@gmail.com>
2026-11-16 06:53:33 +00:00

588 lines
17 KiB
Markdown

# Zed Documentation Guidelines
## Voice and Tone
### Core Principles
- **Practical over promotional**: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
- **Honest about limitations**: When Zed lacks a feature or doesn't match another tool's depth, say so directly. Pair limitations with workarounds or alternative workflows.
- **Direct and concise**: Use short sentences. Get to the point. Developers are scanning, not reading novels.
- **Second person**: Address the reader as "you." Avoid "the user" or "one."
- **Present tense**: "Zed opens the file" not "Zed will open the file."
### What to Avoid
- Superlatives without substance ("incredibly fast," "seamlessly integrated")
- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
- Apologetic tone for missing features—state the limitation and move on
- Comparisons that disparage other tools—be factual, not competitive
- Meta-commentary about honesty ("the honest take is...", "to be frank...", "honestly...")—let honesty show through frank assessments, not announcements
- LLM-isms and filler words ("entirely," "certainly,", "deeply," "definitely," "actually")—these add nothing
## Content Structure
### Page Organization
1. **Start with the goal**: Open with what the reader will accomplish, not background
2. **Front-load the action**: Put the most common task first, edge cases later
3. **Use headers liberally**: Readers scan; headers help them find what they need
4. **End with "what's next"**: Link to related docs or logical next steps
### Section Patterns
For how-to content:
1. Brief context (1-2 sentences max)
2. Steps or instructions
3. Example (code block or screenshot reference)
4. Tips or gotchas (if any)
For reference content:
1. What it is (definition)
2. How to access/configure it
3. Options/parameters table
4. Examples
## Formatting Conventions
### Keybindings
- Use backticks for key combinations: `Cmd+Shift+P`
- Show both macOS and Linux/Windows when they differ: `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows)
- Use `+` to join simultaneous keys, space for sequences: `Cmd+K Cmd+C`
### Code and Settings
- Inline code for setting names, file paths, commands: `format_on_save`, `.zed/settings.json`, `zed .`
- Code blocks for JSON config, multi-line commands, or file contents
- Always show complete, working examples—not fragments
### Terminal Commands
Use `sh` code blocks for terminal commands, not plain backticks:
```sh
brew install --cask zed
```
Not:
```
brew install --cask zed
```
For single inline commands in prose, backticks are fine: `zed .`
### Tables
Use tables for:
- Keybinding comparisons between editors
- Settings mappings (e.g., VS Code → Zed)
- Feature comparisons with clear columns
Format:
```
| Action | Shortcut | Notes |
| --- | --- | --- |
| Open File | `Cmd+O` | Works from any context |
```
### Tips and Notes
Use blockquote format with bold label:
```
> **Tip:** Practical advice that helps bridge gaps or saves time.
```
Reserve tips for genuinely useful information, not padding.
## Writing Guidelines
### Settings Documentation
- **Settings Editor first**: Show how to find and change settings in the UI before showing JSON
- **JSON as secondary**: Present JSON examples as "Or add this to your settings.json" for users who prefer direct editing
- **Complete examples**: Include the full JSON structure, not just the value
### Migration Guides
- **Jobs to be done**: Frame around tasks ("How do I search files?") not features ("File Search Feature")
- **Acknowledge the source**: Respect that users have muscle memory and preferences from their previous editor
- **Keybindings tables**: Essential for migration docs—show what maps, what's different, what's missing
- **Trade-offs section**: Be explicit about what the user gains and loses in the switch
### Feature Documentation
- **Start with the default**: Document the out-of-box experience first
- **Configuration options**: Group related settings together
- **Cross-link generously**: Link to related features, settings reference, and relevant guides
## Terminology
| Use | Instead of |
| --------------- | --------------------------------------------------------------------- |
| folder | directory (in user-facing text) |
| project | workspace (Zed doesn't have workspaces) |
| Settings Editor | settings UI, preferences |
| command palette | command bar, action search |
| language server | LSP (spell out first use, then LSP is fine) |
| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
## Examples
### Good: Direct and actionable
```
To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
Or add this to your settings.json:
{
"format_on_save": "on"
}
```
### Bad: Wordy and promotional
```
Zed provides a powerful and seamless formatting experience. Simply navigate to the settings and you'll find the format_on_save option which enables Zed's incredible auto-formatting capabilities.
```
### Good: Honest about limitations
```
Zed doesn't index your project like IntelliJ does. You open a folder and start working immediately—no waiting. The trade-off: cross-project analysis relies on language servers, which may not go as deep.
**How to adapt:**
- Use `Cmd+Shift+F` for project-wide text search
- Use `Cmd+O` for symbol search (powered by your language server)
```
### Bad: Defensive or dismissive
```
While some users might miss indexing, Zed's approach is actually better because it's faster.
```
## Pull request hygiene
- Include a `Release Notes:` section as the final section in the PR body.
- For docs-only PRs, use exactly:
```
Release Notes:
- N/A
```
# Documentation Automation Agent Guidelines
This file governs automated documentation updates triggered by code changes. All automation phases must comply with these rules.
## Documentation System
This documentation uses **mdBook** (https://rust-lang.github.io/mdBook/).
### Key Files
- **`docs/src/SUMMARY.md`**: Table of contents following mdBook format (https://rust-lang.github.io/mdBook/format/summary.html)
- **`docs/book.toml`**: mdBook configuration
- **`docs/.prettierrc`**: Prettier config (80 char line width)
### SUMMARY.md Format
The `SUMMARY.md` file defines the book structure. Format rules:
- Chapter titles are links: `[Title](./path/to/file.md)`
- Nesting via indentation (2 spaces per level)
- Separators: `---` for horizontal rules between sections
- Draft chapters: `[Title]()` (empty parens, not yet written)
Example:
```markdown
# Section Title
- [Chapter](./chapter.md)
- [Nested Chapter](./nested.md)
---
# Another Section
```
### Custom Preprocessor
The docs use a custom preprocessor (`docs_preprocessor`) that expands special commands:
| Syntax | Purpose | Example |
| --------------------------- | ------------------------------------- | ----------------------------- |
| {#kb action::ActionName} | Keybinding for action | {#kb agent::ToggleFocus} |
| {#action agent::ActionName} | Action reference (renders as command) | {#action agent::OpenSettings} |
**Rules:**
- Always use preprocessor syntax for keybindings instead of hardcoding
- Action names use `snake_case` in the namespace, `PascalCase` for the action
- Common namespaces: `agent::`, `editor::`, `assistant::`, `vim::`
### Formatting Requirements
All documentation must pass **Prettier** formatting:
```sh
cd docs && npx prettier --check src/
```
Before any documentation change is considered complete:
1. Run Prettier to format: `cd docs && npx prettier --write src/`
2. Verify it passes: `cd docs && npx prettier --check src/`
Prettier config: 80 character line width (`docs/.prettierrc`)
### Section Anchors
Use `{#anchor-id}` syntax for linkable section headers:
```markdown
## Getting Started {#getting-started}
### Custom Models {#anthropic-custom-models}
```
Anchor IDs should be:
- Lowercase with hyphens
- Unique within the page
- Descriptive (can include parent context like `anthropic-custom-models`)
### Code Block Annotations
Use annotations after the language identifier to indicate file context:
```markdown
\`\`\`json [settings]
{
"agent": { ... }
}
\`\`\`
\`\`\`json [keymap]
[
{ "bindings": { ... } }
]
\`\`\`
```
Valid annotations: `[settings]` (for settings.json), `[keymap]` (for keymap.json)
### Blockquote Formatting
Use bold labels for callouts:
```markdown
> **Note:** Important information the user should know.
> **Tip:** Helpful advice that saves time or improves workflow.
> **Warn:** Caution about potential issues or gotchas.
```
### Image References
Images are hosted externally. Reference format:
```markdown
![Alt text description](https://zed.dev/img/path/to/image.webp)
```
### Cross-Linking
- Relative links for same-directory: `[Agent Panel](./agent-panel.md)`
- With anchors: `[Custom Models](./llm-providers.md#anthropic-custom-models)`
- Parent directory: `[Telemetry](../telemetry.md)`
## Voice and Tone
### Core Principles
- **Practical over promotional**: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
- **Honest about limitations**: When Zed lacks a feature or doesn't match another tool's depth, say so directly. Pair limitations with workarounds or alternative workflows.
- **Direct and concise**: Use short sentences. Get to the point. Developers are scanning, not reading novels.
- **Second person**: Address the reader as "you." Avoid "the user" or "one."
- **Present tense**: "Zed opens the file" not "Zed will open the file."
### What to Avoid
- Superlatives without substance ("incredibly fast," "seamlessly integrated")
- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
- Apologetic tone for missing features—state the limitation and move on
- Comparisons that disparage other tools—be factual, not competitive
- Lots of use of em or en dashes.
## Examples of Good Copy
### Good: Direct and actionable
```
To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
Or add this to your settings.json:
{
"format_on_save": "on"
}
```
### Bad: Wordy and promotional
```
Zed provides a powerful and seamless formatting experience. Simply navigate to the settings and you'll find the format_on_save option which enables Zed's incredible auto-formatting capabilities.
```
### Good: Honest about limitations
```
Zed doesn't index your project like IntelliJ does. You open a folder and start working immediately—no waiting. The trade-off: cross-project analysis relies on language servers, which may not go as deep.
**How to adapt:**
- Use `Cmd+Shift+F` for project-wide text search
- Use `Cmd+O` for symbol search (powered by your language server)
```
### Bad: Defensive or dismissive
```
While some users might miss indexing, Zed's approach is actually better because it's faster.
```
## Scope
### In-Scope Documentation
- All Markdown files in `docs/src/`
- `docs/src/SUMMARY.md` (mdBook table of contents)
- Language-specific docs in `docs/src/languages/`
- Feature docs (AI, extensions, configuration, etc.)
### Out-of-Scope (Do Not Modify)
- `CHANGELOG.md`, `CONTRIBUTING.md`, `README.md` at repo root
- Inline code comments and rustdoc
- `CLAUDE.md`, `GEMINI.md`, or other AI instruction files
- Build configuration (`book.toml`, theme files, `docs_preprocessor`)
- Any file outside `docs/src/`
## Page Structure Patterns
### Standard Page Layout
Most documentation pages follow this structure:
1. **Title** (H1) - Single sentence or phrase
2. **Overview/Introduction** - 1-3 paragraphs explaining what this is
3. **Getting Started** `{#getting-started}` - Prerequisites and first steps
4. **Main Content** - Feature details, organized by topic
5. **Advanced/Configuration** - Power user options
6. **See Also** (optional) - Related documentation links
### Settings Documentation Pattern
When documenting settings:
1. Show the Settings Editor (UI) approach first
2. Then show JSON as "Or add this to your settings.json:"
3. Always show complete, valid JSON with surrounding structure:
```json [settings]
{
"agent": {
"default_model": {
"provider": "anthropic",
"model": "claude-sonnet-4"
}
}
}
```
### Provider/Feature Documentation Pattern
For each provider or distinct feature:
1. H3 heading with anchor: `### Provider Name {#provider-name}`
2. Brief description (1-2 sentences)
3. Setup steps (numbered list)
4. Configuration example (JSON code block)
5. Custom models section if applicable: `#### Custom Models {#provider-custom-models}`
## Style Rules
Follow these key conventions:
### Voice
- Second person ("you"), present tense
- Direct and concise—no hedging ("simply", "just", "easily")
- Honest about limitations; no promotional language
### Formatting
- Keybindings: backticks with `+` for simultaneous keys (`Cmd+Shift+P`)
- Show both macOS and Linux/Windows variants when they differ
- Use `sh` code blocks for terminal commands
- Settings: show Settings Editor UI first, JSON as secondary
### Terminology
| Use | Instead of |
| --------------- | --------------------------------------------------------------------- |
| folder | directory |
| project | workspace |
| Settings Editor | settings UI |
| command palette | command bar |
| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
| language server | LSP (spell out first use, then LSP is fine) |
## Zed-Specific Conventions
### Recognized Rules Files
When documenting rules/instructions for AI, note that Zed recognizes these files (in priority order):
- `.rules`
- `.cursorrules`
- `.windsurfrules`
- `.clinerules`
- `.github/copilot-instructions.md`
- `AGENT.md`
- `AGENTS.md`
- `CLAUDE.md`
- `GEMINI.md`
### Settings File Locations
- macOS: `~/.config/zed/settings.json`
- Linux: `~/.config/zed/settings.json`
- Windows: `%AppData%\Zed\settings.json`
### Keymap File Locations
- macOS: `~/.config/zed/keymap.json`
- Linux: `~/.config/zed/keymap.json`
- Windows: `%AppData%\Zed\keymap.json`
## Safety Constraints
### Must Not
- Delete existing documentation files
- Remove sections documenting existing functionality
- Change URLs or anchor links without verifying references
- Modify `SUMMARY.md` structure without corresponding content
- Add speculative documentation for unreleased features
- Include internal implementation details not relevant to users
### Must
- Preserve existing structure when updating content
- Maintain backward compatibility of documented settings/commands
- Flag uncertainty explicitly rather than guessing
- Link to related documentation when adding new sections
## Change Classification
### Requires Documentation Update
- New user-facing features or commands
- Changed keybindings or default behaviors
- Modified settings schema or options
- Deprecated or removed functionality
- API changes affecting extensions
### Does Not Require Documentation Update
- Internal refactoring without behavioral changes
- Performance optimizations (unless user-visible)
- Bug fixes that restore documented behavior
- Test changes
- CI/CD changes
## Output Format
### Phase 4 Documentation Plan
When generating a documentation plan, use this structure:
```markdown
## Documentation Impact Assessment
### Summary
Brief description of code changes analyzed.
### Documentation Updates Required: [Yes/No]
### Planned Changes
#### 1. [File Path]
- **Section**: [Section name or "New section"]
- **Change Type**: [Update/Add/Deprecate]
- **Reason**: Why this change is needed
- **Description**: What will be added/modified
#### 2. [File Path]
...
### Uncertainty Flags
- [ ] [Description of any assumptions or areas needing confirmation]
### No Changes Needed
- [List files reviewed but not requiring updates, with brief reason]
```
### Phase 6 Summary Format
```markdown
## Documentation Update Summary
### Changes Made
| File | Change | Related Code |
| -------------- | ----------------- | ----------------- |
| path/to/doc.md | Brief description | link to PR/commit |
### Rationale
Brief explanation of why these updates were made.
### Review Notes
Any items reviewers should pay special attention to.
```
## Behavioral Guidelines
### Conservative by Default
- When uncertain whether to document something, flag it for human review
- Prefer smaller, focused updates over broad rewrites
- Do not "improve" documentation unrelated to the triggering code change
### Traceability
- Every documentation change should trace to a specific code change
- Include references to relevant commits, PRs, or issues in summaries
### Incremental Updates
- Update existing sections rather than creating parallel documentation
- Maintain consistency with surrounding content
- Follow the established patterns in each documentation area