4. **Custom Instructions** (advanced-usage/custom-instructions.md)

Michaelzag · Michaelzag · commit efd53a5d1369 · 2025-02-27T16:14:24.000-05:00
- Expanded and merged content from the previously separate Custom Rules document
   - Added comprehensive comparison between custom instructions and rules approaches
   - Added detailed examples of rule file formats with proper markdown formatting
   - Included project-specific rule examples for various types of projects
   - Added best practices for effective customization with clear examples
   - Added section on advanced usage with custom modes
   - Added guidance on when to use each customization approach
   - Added link to managing preferences documentation
diff --git a/docs/advanced-usage/custom-instructions.md b/docs/advanced-usage/custom-instructions.md
@@ -1,50 +1,124 @@
-# Custom Instructions
+# Customizing Roo Code Behavior
 
-Roo Code allows you to customize its behavior using custom instructions at both global and workspace levels. These instructions are added to the system prompt and influence how Roo Code responds to your requests. You can define:
+Roo Code allows you to customize its behavior using custom instructions and rules at both global and workspace levels. These customizations are added to the system prompt and influence how Roo Code responds to your requests.
+
+## Types of Customization
+
+Roo Code offers two complementary approaches to customization:
+
+1. **Custom Instructions**: General guidelines that shape how Roo interacts with you
+2. **Custom Rules**: Structured technical guidelines for code standards and practices
+
+| Feature | Custom Instructions | Custom Rules |
+|---------|---------------------|--------------|
+| **Primary Purpose** | General behavioral guidance | Specific technical guidelines |
+| **Format** | Free-form text | Structured markdown format |
+| **Configuration Method** | UI (Prompts Tab) or rules files | Rules files in project root |
+| **Scope** | Global or workspace-specific | Global or mode-specific |
+| **Best For** | General preferences, tone, approach | Coding standards, technical requirements |
+
+Both approaches complement each other - you can use custom instructions for general guidance and custom rules for specific technical requirements.
+
+## Custom Instructions Configuration
+
+You can define custom instructions at various levels:
 
 * **Global Custom Instructions:** Apply across all workspaces
 * **Workspace-Level Instructions:**
     * **Workspace-Wide:** Apply to all modes in the workspace through `.clinerules` files
     * **Mode-Specific:** Apply to specific modes in the workspace through files like `.clinerules-code`
 
-## Preferred Language
+### Preferred Language
 
 You can specify a preferred language for Roo Code to use. When set, this appears at the start of your custom instructions and directs Roo Code to communicate in your chosen language. You can set this in the **Prompts** tab. For more details on managing this and other settings, see [Managing Preferences and Settings](managing-preferences).
 
-## Global Custom Instructions
+### Setting Global Custom Instructions
 
 These instructions apply across all workspaces. They're useful for setting preferences that you want to maintain regardless of which project you're working on.
 
 **How to set them:**
 
-1.  **Open Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar
-2.  **Find Section:** Find the "Custom Instructions for All Modes" section
-3.  **Enter Instructions:** Enter your instructions in the text area
-4.  **Save Changes:** Click "Done" to save your changes
+1. **Open Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar
+2. **Find Section:** Find the "Custom Instructions for All Modes" section
+3. **Enter Instructions:** Enter your instructions in the text area
+4. **Save Changes:** Click "Done" to save your changes
 
-## Workspace-Level Instructions
+### Setting Workspace-Level Instructions
 
 These instructions only apply within your current workspace, allowing you to customize Roo Code's behavior for specific projects.
 
-### Workspace-Wide Instructions
+#### Workspace-Wide Instructions
 
 Workspace-wide instructions are defined through rule files in your workspace root, primarily using `.clinerules`. Additional support for `.cursorrules` and `.windsurfrules` is available for editor compatibility.
 
-### Mode-Specific Instructions
+#### Mode-Specific Instructions
 
 Mode-specific instructions can be set in two independent ways that can be used simultaneously:
 
-1.  **Using the Prompts Tab:**
-    * **Open Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar
-    * **Select Mode:** Under the Modes heading, click the button for the mode you want to customize
-    * **Enter Instructions:** Enter your instructions in the text area under "Mode-specific Custom Instructions (optional)"
-    * **Save Changes:** Click "Done" to save your changes
+1. **Using the Prompts Tab:**
+   * **Open Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar
+   * **Select Mode:** Under the Modes heading, click the button for the mode you want to customize
+   * **Enter Instructions:** Enter your instructions in the text area under "Mode-specific Custom Instructions (optional)"
+   * **Save Changes:** Click "Done" to save your changes
 
-2.  **Using Rule Files:** Create a `.clinerules-[mode]` file in your workspace root (e.g., `.clinerules-code`)
+2. **Using Rule Files:** Create a `.clinerules-[mode]` file in your workspace root (e.g., `.clinerules-code`)
 
 When both tab instructions and rule files are set for a mode, both sets of instructions will be included in the system prompt.
 
-### How Instructions are Combined
+## Custom Rules
+
+Custom rules provide more structured guidelines stored in special files in your project's root directory. They tell Roo how to approach various aspects of your codebase, such as:
+
+- Coding style and formatting preferences
+- Documentation requirements
+- Testing practices
+- Error handling approaches
+- Project-specific conventions
+
+### Rule File Types
+
+Roo Code supports several rule file formats:
+
+| File Name | Purpose |
+|-----------|---------|
+| `.clinerules` | Primary rule file for all modes |
+| `.clinerules-code` | Rules specific to Code mode |
+| `.clinerules-architect` | Rules specific to Architect mode |
+| `.clinerules-[mode]` | Rules for any custom mode |
+| `.cursorrules` | Alternative format (compatible with Cursor AI) |
+| `.windsurfrules` | Alternative format (compatible with Windsurf) |
+
+All rule files should be placed in your project's root directory.
+
+### Rule File Format
+
+Rule files use a simple, markdown-based format that's easy to read and write:
+
+```markdown
+# Category Title
+
+1. Rule Group Title:
+   - Specific guideline
+   - Another guideline
+   - Technical requirement
+
+2. Another Rule Group:
+   - Guideline one
+   - Guideline two
+```
+
+This format makes rules easy to read for both humans and AI.
+
+### Global vs. Mode-Specific Rules
+
+Roo Code allows you to create both global rules and mode-specific rules:
+
+- **Global Rules** (`.clinerules`) apply to all modes
+- **Mode-Specific Rules** (`.clinerules-[mode]`) only apply when using that specific mode
+
+When both exist, mode-specific rules take priority, but global rules still apply if they don't conflict.
+
+## How Instructions and Rules are Combined
 
 Instructions are placed in the system prompt in this exact format:
 
@@ -70,23 +144,9 @@ Rules:
 * **Source Headers:** Each rule file's contents are included with a header indicating its source
 * **Rule Interaction:** Mode-specific rules complement global rules rather than replacing them
 
-## Difference Between Custom Instructions and Custom Rules
-
-While related, custom instructions and custom rules serve slightly different purposes:
+## Examples and Best Practices
 
-* **Custom Instructions** (set via Prompts Tab): 
-  - General behavioral guidance for Roo
-  - Often more conversational or high-level
-  - Set through the UI or via rule files
-  
-* **Custom Rules** (primarily in rule files):
-  - More structured, specific technical guidelines
-  - Often focused on code standards and practices
-  - Typically organized by categories
-  
-For detailed information on creating effective structured rules in rule files, see the [Custom Rules](custom-rules.md) documentation.
-
-## Examples of Custom Instructions
+### Example Custom Instructions
 
 * "Always use spaces for indentation, with a width of 4 spaces"
 * "Use camelCase for variable names"
@@ -96,9 +156,103 @@ For detailed information on creating effective structured rules in rule files, s
 * "Prioritize using the most common library in the community"
 * "When adding new features to websites, ensure they are responsive and accessible"
 
-## Strategies for Effective Custom Instructions
+### Example Rule Categories
+
+#### Code Style Rules
+
+```markdown
+# Code Style
+
+1. Formatting:
+   - Use 2-space indentation for all files
+   - Keep line length under 100 characters
+   - Place opening braces on the same line
+   - Use trailing commas in multi-line arrays and objects
+
+2. Naming Conventions:
+   - Use camelCase for variables and functions
+   - Use PascalCase for classes and components
+   - Use UPPER_SNAKE_CASE for constants
+   - Prefix private methods with underscore
+```
+
+#### Testing Rules
+
+```markdown
+# Testing Requirements
+
+1. Test Coverage:
+   - Write tests for all new functions
+   - Maintain at least 80% code coverage
+   - Test both success and error paths
+   - Use descriptive test names
+
+2. Test Structure:
+   - Organize tests by feature or component
+   - Use setup and teardown for common operations
+   - Mock external dependencies
+   - Test edge cases explicitly
+```
+
+#### Documentation Rules
+
+```markdown
+# Documentation Standards
+
+1. Code Documentation:
+   - Document all public functions with JSDoc
+   - Explain complex algorithms with comments
+   - Include examples for APIs
+   - Document parameters and return values
+
+2. Project Documentation:
+   - Keep README up-to-date
+   - Document setup steps
+   - Include troubleshooting guidance
+   - Add comments for non-obvious code
+```
+
+### Project-Specific Rule Examples
+
+#### Web Development Project
 
-### Be Clear and Specific
+```markdown
+# Web Project Rules
+
+1. Accessibility:
+   - Use semantic HTML elements
+   - Include alt text for images
+   - Ensure keyboard navigation works
+   - Maintain WCAG AA compliance
+
+2. Performance:
+   - Keep bundle size under 500KB
+   - Optimize images before adding
+   - Implement code splitting
+   - Lazy load non-critical resources
+```
+
+#### Data Science Project
+
+```markdown
+# Data Science Rules
+
+1. Data Management:
+   - Document data sources
+   - Version control datasets
+   - Include data cleaning steps
+   - Note missing value handling
+
+2. Models:
+   - Document training parameters
+   - Include accuracy metrics
+   - Validate against test data
+   - Explain feature importance
+```
+
+## Best Practices for Effective Customization
+
+### Be Specific and Clear
 
 Vague instructions can lead to inconsistent results. Be as specific as possible:
 
@@ -108,6 +262,40 @@ Vague instructions can lead to inconsistent results. Be as specific as possible:
 **Less Effective:**
 "Make sure to use types properly."
 
+For rules files, write clear, actionable guidelines rather than vague principles:
+
+**Good:**
+```markdown
+- Validate all user inputs before processing
+- Log errors with stack traces and context
+- Use parameterized queries for database operations
+```
+
+**Not as helpful:**
+```markdown
+- Make sure code is secure
+- Handle errors properly
+- Be careful with databases
+```
+
+### Organize Logically
+
+Group related rules together under clear categories:
+
+```markdown
+# Security
+
+1. Input Validation:
+   - Validate all user inputs
+   - Sanitize data before use
+   - Reject unexpected values
+
+2. Authentication:
+   - Require strong passwords
+   - Implement account lockouts
+   - Log authentication attempts
+```
+
 ### Prioritize Important Guidelines
 
 Put the most important instructions first, as they'll receive more attention:
@@ -125,4 +313,54 @@ Too many rigid instructions can limit Roo's ability to help, while too few may l
 **Balanced Approach:**
 "Follow the existing code style in the project, but feel free to suggest improvements where patterns are unclear or could be more efficient."
 
-By using custom instructions effectively, you can tailor Roo Code's behavior to match your coding style, project requirements, and personal preferences.
+### Keep Rules Updated
+
+Review and update your rules as your project evolves:
+
+- Remove outdated guidelines
+- Add rules for new technologies
+- Refine based on project learnings
+
+## Advanced Usage
+
+### Combining Rules with Custom Modes
+
+For an even more tailored experience, you can:
+
+1. Create a [custom mode](custom-modes) with specific capabilities
+2. Create matching `.clinerules-[mode]` file
+3. Get specialized assistance that follows your guidelines
+
+For example, you might create a "security-auditor" mode with a `.clinerules-security-auditor` file containing security-focused rules.
+
+### Testing Your Customizations
+
+To verify your customizations are working:
+
+1. Create your rule file in the project root
+2. Switch to the appropriate mode if using mode-specific rules
+3. Ask Roo to perform a task related to your rules
+4. Check if the response follows your guidelines
+
+For example, after adding code style rules, ask Roo to write a new function and see if it follows your specified style.
+
+## When to Use Each Approach
+
+Here's guidance on when to use each customization approach:
+
+**Use Custom Instructions when:**
+- Setting general preferences that apply across projects
+- Specifying how Roo should communicate with you
+- Providing high-level guidance on approach and methodology
+- Setting simple preferences without complex formatting
+
+**Use Custom Rules when:**
+- Defining specific coding standards
+- Setting project-specific technical requirements
+- Creating structured, categorical guidelines
+- Sharing standards across a team
+- Creating mode-specific behavior
+
+For best results, combine both approaches - use custom instructions for general guidance and custom rules for specific technical requirements.
+
+By effectively customizing Roo Code's behavior, you can transform it into a team member who understands and follows your project's unique needs and standards.
diff --git a/docs/basic-usage/using-tools.md b/docs/basic-usage/using-tools.md
@@ -26,7 +26,7 @@ Here's a brief overview of the core tools available in Roo Code:
 | `ask_followup_question`     | Asks you a clarifying question.                                              |
 | `attempt_completion`        | Indicates that Roo Code believes the task is complete.                       |
 
-**Note:**  The availability of some tools may depend on the current [mode](./modes.md) and your settings.
+**Note:**  The availability of some tools may depend on the current [mode](./modes) and your settings.
 
 ## How Tools are Used
 
diff --git a/docs/providers/openai-compatible.md b/docs/providers/openai-compatible.md
@@ -10,7 +10,7 @@ Roo Code supports a wide range of AI model providers that offer APIs compatible
 *   **Cloud providers** like Perplexity, Together AI, Anyscale, and others.
 *   **Any other provider** offering an OpenAI-compatible API endpoint.
 
-This document focuses on setting up providers *other than* the official OpenAI API (which has its own [dedicated configuration page](./openai.md)).
+This document focuses on setting up providers *other than* the official OpenAI API (which has its own [dedicated configuration page](./openai)).
 
 ## General Configuration
 
diff --git a/docs/providers/openai.md b/docs/providers/openai.md
@@ -40,4 +40,4 @@ Refer to the [OpenAI Models documentation](https://platform.openai.com/docs/mode
 ## Tips and Notes
 
 *   **Pricing:** Refer to the [OpenAI Pricing](https://openai.com/pricing) page for details on model costs.
-*   **Azure OpenAI Service:** If you'd like to use the Azure OpenAI service, please see our section on [OpenAI-compatible](./openai-compatible.md) providers.
+*   **Azure OpenAI Service:** If you'd like to use the Azure OpenAI service, please see our section on [OpenAI-compatible](./openai-compatible) providers.
