Skip to content

docs: Improve rules guidance in the deep dive and rules docs #8022

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 3, 2025
Merged

docs: Improve rules guidance in the deep dive and rules docs #8022

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4cd9317
Improve rules guidance in docs
sestinj Sep 29, 2025
e1749c7
docs: Address Patrick's feedback on rules documentation
bdougie Oct 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/customization/rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,26 @@ By implementing rules, you transform the AI from a generic coding agent into a k

Your agent detects rules and applies the specified rules while in [Agent](/features/agent/quick-start), [Chat](/features/chat/quick-start), and [Edit](/features/edit/quick-start) modes.

## Where to Manage Rules

<Columns cols={2}>
<Card title="Local Rules (.continue/rules)" icon="folder">
Copy link
Collaborator

@Patrick-Erichsen Patrick-Erichsen Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think one of the main benefits is that it's version controlled alongside your code

- Create files in `.continue/rules` folder
- Automatically appear with Hub assistants
- Edit directly in your file system
- Best for project-specific rules
</Card>

<Card title="Hub Rules" icon="cloud">
Copy link
Collaborator

@Patrick-Erichsen Patrick-Erichsen Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could mention that it's easy to include in multiple agents. Also maybe give some examples of a hub rule vs project rule, eg hub rule for org wide things like "always use X library for Y task" and project rule like "remember to generate migrations after modifying the db"

- Manage on [Continue Hub](https://hub.continue.dev)
- Reference in config.yaml with `uses:`
- Share with team and community
- Best for reusable, organization rules
</Card>
</Columns>

<Info>
**Quick Setup**: Start with local rules for immediate use, then promote commonly used rules to the Hub for sharing and reuse.
</Info>

Learn more in the [rules deep dive](/customize/deep-dives/rules), and view [`rules`](/reference#rules) in the YAML Reference for more details.
112 changes: 109 additions & 3 deletions docs/customize/deep-dives/rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,42 @@ You can view the current rules by clicking the pen icon above the main toolbar:

To form the system message, rules are joined with new lines, in the order they appear in the toolbar. This includes the base chat system message ([see below](#how-to-customize-chat-system-message)).

## Understanding Hub vs Local Rules Integration

<Warning>
**Important:** Rules created in different locations behave differently and have different synchronization patterns.
</Warning>

Continue supports two types of rules with different behaviors:

<Columns cols={2}>
<Card title="Local Rules" icon="folder">
- **Location**: `.continue/rules` folder in your workspace
- **Visibility**: Automatically visible when using Hub assistants
- **Creation**: Add rules button in VSCode or manual file creation
- **File Management**: Creates actual `.md` files you can edit directly
</Card>

<Card title="Hub Rules" icon="cloud">
- **Location**: Stored on Continue Hub, referenced in config.yaml
- **Visibility**: Only appear when referenced in assistant configuration
- **Creation**: Created directly on Hub or copied from local rules
- **File Management**: No local files created, managed through Hub interface
</Card>
</Columns>

### How Rules Are Applied

When using Continue, rules are loaded in this order:
1. **Hub assistant rules** (if using a Hub-based assistant)
2. **Referenced Hub rules** (via `uses:` in config.yaml)
3. **Local workspace rules** (from `.continue/rules` folder)
4. **Global rules** (from `~/.continue/rules` folder)

<Info>
**TL;DR**: Local rules show up automatically when using Hub assistants. Hub rules show up automatically when referenced in your config.
</Info>

## Quick Start: How to Create Your First Rule File

Below is a quick example of setting up a new rule file:
Expand All @@ -42,6 +78,8 @@ Now test your rules by asking a question about a file in chat.

## How to Create Rules Blocks

### Creating Local Rules

Rules can be added locally using the "Add Rules" button while viewing the Local Agent's rules.

![add local rules button](/images/add-local-rules.png)
Expand All @@ -50,12 +88,44 @@ Rules can be added locally using the "Add Rules" button while viewing the Local
**Automatically create local rule blocks**: When in Agent mode, you can prompt the agent to create a rule for you using the `create_rule_block` tool if enabled.

For example, you can say "Create a rule for this", and a rule will be created for you in `.continue/rules` based on your conversation.

</Info>

Rules can also be added to an Agent on the Continue Hub.
### Creating Hub Rules

Rules can also be created and managed on the Continue Hub:

1. **Browse existing rules**: [Explore available rules](https://hub.continue.dev)
2. **Create new rules**: [Create your own](https://hub.continue.dev/new?type=block&blockType=rules) in the Hub
3. **Copy from local rules**: Copy/paste content from your `.continue/rules` files to create Hub rules

Explore available rules [here](https://hub.continue.dev), or [create your own](https://hub.continue.dev/new?type=block&blockType=rules) in the Hub.
### Working Between Hub and Local Rules

<Tabs>
<Tab title="Hub to VSCode">
To use Hub rules in your local setup:

1. Reference them in your `config.yaml`:
```yaml
rules:
- uses: username/my-hub-rule
```
2. The rule will automatically appear in your rules toolbar
3. **Note**: No local file is created - the rule exists only on the Hub
</Tab>

<Tab title="VSCode to Hub">
To move local rules to the Hub:

1. Copy the content from your `.continue/rules/rule-name.md` file
2. Go to [Create new rule](https://hub.continue.dev/new?type=block&blockType=rules)
3. Paste the content and configure the rule
4. Optionally, remove the local file and reference the Hub rule in your config

<Warning>
**Current Limitation**: There's no automatic sync from local to Hub. You must manually copy/paste rule content.
</Warning>
</Tab>
</Tabs>

### How to Configure Rule Properties and Syntax

Expand Down Expand Up @@ -150,6 +220,42 @@ globs: ["**/*.ts", "**/*.tsx"]
- modularize components into smaller, reusable pieces
```

## Troubleshooting Rules

### Issue: Rules Created in Different Places Don't Sync

**Problem**: You created rules in the Hub but don't see them in VSCode, or vice versa.

**Solution**:
- **Hub rules** only appear when referenced in your config.yaml using the `uses:` syntax
- **Local rules** automatically appear when using Hub assistants
- There's currently no automatic bidirectional sync

### Issue: "Edit" Links Point to Wrong Location

**Problem**: When you click "Edit" on a rule in VSCode, it tries to open the Hub even though the rule is local, or shows an incorrect URL.

**Root Cause**: This happens when you have a mix of local and Hub rules, and Continue can't properly determine where each rule originates.

**Workaround**:
1. **For local rules**: Navigate directly to `.continue/rules/` folder and edit the `.md` file
2. **For Hub rules**: Go directly to your assistant page on [Continue Hub](https://hub.continue.dev) and edit from there
3. Keep track of which rules are local vs Hub-based to avoid confusion

<Info>
**Known Issue**: This link accuracy problem is tracked in [Linear issue CON-3084](https://linear.app/continue/issue/CON-3084) and will be fixed in a future update.
</Info>

### Issue: Rules Don't Appear in Assistant

**Problem**: Your rules exist but don't show up in the rules toolbar.

**Check These**:
1. **File location**: Ensure local rules are in `.continue/rules/` (not `.continue/rule/`)
2. **File format**: Rules should be `.md` files with proper YAML frontmatter
3. **Config reference**: Hub rules must be referenced in `config.yaml`
4. **Assistant type**: Ensure you're using the correct assistant (local vs Hub)

### How to Customize Chat System Message

Continue includes a simple default system message for [Agent](../../features/agent/quick-start) and [Chat](../../features/chat/quick-start) requests, to help the model provide reliable codeblock formats in its output.
Expand Down
Loading