rhdh / rules

---
---

# Managing AI Assistant Rules

This document provides guidelines for creating, importing, and managing AI assistant rules, commands, skills, and configurations. `.rulesync/` is the project source of truth.

## 📁 Directory Structure

```text
.rulesync/
├── rules/              # Rule files (.md files with frontmatter)
├── commands/           # Command files (.md files with frontmatter)
├── skills/             # One directory per skill, containing SKILL.md
└── README.md          # Documentation
```

`rulesync.jsonc` configures Cursor, Claude Code, and OpenCode, with the `rules`,
`commands`, and `skills` features enabled. Use `yarn rulesync:generate` to regenerate
these configured targets; do not expand generation to every supported tool.

Generated outputs include:
- `.cursor/rules/*.mdc`, `.cursor/commands/`, and `.cursor/skills/`
- `.claude/rules/`, `.claude/commands/`, and `.claude/skills/`
- `.opencode/memories/`, `.opencode/commands/`, and `.opencode/skills/`
- The generated instruction list in `opencode.jsonc`

Generation uses `delete: true`: removing a source rule, command, or skill removes
its managed outputs on the next generation. Delete the source and regenerate
rather than deleting only generated files.

## 🤖 Automated Checks

A GitHub Actions workflow (`.github/workflows/rulesync-check.yaml`) automatically validates that generated files in `.cursor`, `.claude`, `.opencode`, and `opencode.jsonc` are in sync with `.rulesync` when source, generated, or configuration files change on:
- All pull requests
- Pushes to main and release branches

**What it checks:**
- Runs `yarn rulesync:check`
- Validates the configuration with `rulesync doctor --strict`
- Uses `rulesync generate --check` without modifying the checkout
- Fails if there are differences

**If the check fails, run the appropriate command based on what you edited:**

```bash
# If you forgot to generate from .rulesync
yarn rulesync:generate
yarn rulesync:check
git add .rulesync .cursor .claude .opencode opencode.jsonc

# If you edited .cursor files directly
yarn rulesync:import:cursor
git add .rulesync

# If you edited .claude files directly
yarn rulesync:import:claude
git add .rulesync

# If you edited .opencode files directly
yarn rulesync:import:opencode
git add .rulesync

# After an import, review the source changes and regenerate all configured targets
yarn rulesync:generate
yarn rulesync:check
git diff
# Stage reviewed source and generated changes together, then create a new commit
```

## ✨ Creating New Rules

### Step 1: Create the Rule File

Create a new markdown file in `.rulesync/rules/`:

```bash
# Example: Create a new rule for API development
touch .rulesync/rules/api-development.md
```

### Step 2: Add Frontmatter

Every rule file must have YAML frontmatter:

```yaml
---
targets:
  - '*'                    # Target all AI assistants
root: false                # Context-aware (not always loaded)
description: >-
  Brief description of what this rule covers
globs:                     # File patterns when this rule applies
  - src/api/**
  - tests/api/**
cursor:                    # Cursor-specific configuration
  alwaysApply: false
  description: >-
    Brief description of what this rule covers
  globs:
    - src/api/**
    - tests/api/**
claudecode:                # Claude Code-specific configuration (optional)
  description: >-
    Brief description of what this rule covers
---
```

### Step 3: Write the Rule Content

After the frontmatter, write your rule in markdown:

```markdown
# API Development Guidelines

## Overview

This rule provides guidelines for developing APIs in this project.

## Best Practices

1. **Use TypeScript** - All API code must be in TypeScript
2. **Validate inputs** - Use zod schemas for validation
3. **Document endpoints** - Include JSDoc comments

## Examples

\`\`\`typescript
// Good example
export async function getUser(id: string): Promise<User> {
  // Implementation
}
\`\`\`
```

### Step 4: Generate Configurations

After creating or editing the rule:

```bash
# This happens automatically on commit, but you can run manually:
yarn rulesync:generate
yarn rulesync:check

# Then stage and commit
git add .rulesync/rules/api-development.md .cursor .claude .opencode opencode.jsonc
git commit -s -m "docs: add API development rule"
```

## 📥 Importing Existing Rules

### Scenario 1: Rules Already Exist in `.cursor`

If you have existing rules in `.cursor/rules/*.mdc`:

```bash
# 1. Import all rules from Cursor
yarn rulesync:import:cursor

# 2. Review the imported files in .rulesync

# 3. Edit if needed to match the proper format
```

### Scenario 2: Rules Already Exist in `.claude`

If you have existing rules in `.claude/rules/*.md`:

```bash
# 1. Import all rules from Claude
yarn rulesync:import:claude

# 2. Review the imported files in .rulesync

# 3. Edit if needed to match the proper format
```

### Scenario 3: Rules Already Exist in `.opencode`

Use `yarn rulesync:import:opencode` to recover edits to `.opencode/memories/`,
commands, skills, or the generated `opencode.jsonc` instruction list. Review the
imported `.rulesync/` files before running `yarn rulesync:generate` and
`yarn rulesync:check`.

## 🎯 Creating Commands

Commands are similar to rules but define specific agent commands.

### Step 1: Create Command File

```bash
touch .rulesync/commands/analyze-code.md
```

### Step 2: Add Frontmatter and Content

```markdown
---
description: Analyze code quality and provide suggestions
targets: ["*"]
---

# Analyze Code Command

Execute the following steps:

1. Read the target files
2. Check for:
   - Code smells
   - Security issues
   - Performance problems
3. Provide actionable suggestions
```

## Creating Skills

Place each skill in `.rulesync/skills/<skill-name>/SKILL.md`, with `name`,
`description`, and `targets` frontmatter:

```yaml
---
name: example-skill
description: Explain when and how this skill should be used
targets: ['*']
---
```

Edit the source skill, regenerate, and check synchronization using the same workflow
as rules and commands. A flat `.md` file under `.rulesync/skills/` is not a skill.

## 📋 Frontmatter Field Reference

### Shared Fields

Required fields depend on the feature. Validate source metadata with
`yarn rulesync:check` rather than assuming every feature uses the same schema.

- **`targets`** - Array of AI assistants to target
  - `["*"]` - All assistants
  - `["cursor"]` - Cursor only
  - `["claudecode"]` - Claude Code only
  - `["opencode"]` - OpenCode only
  - `["cursor", "claudecode", "opencode"]` - Multiple specific assistants

- **`description`** - Brief description of the rule/command

### Optional Fields

- **`root`** - Boolean, whether to always load this rule
  - `true` - Always loaded (root-level rule)
  - `false` - Context-aware (loaded based on globs)

- **`globs`** - Array of file patterns when to apply this rule
  ```yaml
  globs:
    - "src/**/*.ts"
    - "tests/**/*.spec.ts"
  ```

- **`cursor`** - Cursor-specific configuration
  ```yaml
  cursor:
    alwaysApply: false
    description: "Rule description"
    globs:
      - "path/**"
  ```

- **`claudecode`** - Claude Code-specific configuration
  ```yaml
  claudecode:
    description: "Rule description"
  ```

## 🚫 What NOT to Do

### ❌ Don't Edit Generated Files in `.cursor`, `.claude`, `.opencode`, and `opencode.jsonc` Directly

Instead, edit the source in `.rulesync/` and then regenerate them:

```bash
yarn rulesync:generate  # Regenerate (or commit to auto-generate)
```

### ❌ Don't Forget Frontmatter

Every rule must have proper frontmatter. Without it, rulesync cannot process the file.

### ❌ Don't Use Absolute Paths in Globs

```yaml
# BAD
globs:
  - /Users/username/project/src/**

# GOOD - Use relative paths
globs:
  - src/**
```

## 🔄 Synchronization Workflow

### Normal Workflow (Recommended)

```bash
# 1. Edit source files
vim .rulesync/rules/my-rule.md

# 2. Generate and validate
yarn rulesync:generate
yarn rulesync:check

# 3. Stage the source and reviewed generated outputs, then commit
git add .rulesync/rules/my-rule.md
git add .cursor .claude .opencode opencode.jsonc
git commit -s -m "docs: update my-rule"
# ✨ The hook regenerates and checks .cursor/.claude/.opencode outputs
```

The `.lintstagedrc.cjs` hook regenerates, stages managed outputs, and runs
`yarn rulesync:check` when a `.rulesync` source or generation configuration is staged.
Changes to `rulesync.jsonc`, `.rulesyncignore`, `.lintstagedrc.cjs`, `package.json`,
and `yarn.lock` also trigger this workflow.

### If You Edited .cursor, .claude, or .opencode Directly

The hook **rejects** generated-only changes. Import the edits before committing:

```bash
# 1. Import from the tool whose generated files you changed
yarn rulesync:import:cursor
# Or: yarn rulesync:import:claude
# Or: yarn rulesync:import:opencode

# 2. Review the imported source changes
git diff -- .rulesync

# 3. Regenerate and validate all configured outputs
yarn rulesync:generate
yarn rulesync:check

# 4. Stage the reviewed source and generated outputs together
git add .rulesync .cursor .claude .opencode opencode.jsonc
```

If a commit hook fails, fix the cause and retry with a new commit. Do not amend a
previous successful commit or force-push as the default recovery step.

## 📝 Use `.local.md` for Personal Rules

For personal or machine-specific rules that shouldn't be committed:

```bash
# Create a local rule
vim .rulesync/rules/my-personal-setup.local.md

# This will be ignored by git
git status  # Won't show the .local.md file
```

Local files:
- ✅ `.rulesync/rules/*.local.md` - Ignored
- ✅ `.cursor/rules/*.local.mdc` - Ignored
- ✅ `.claude/**/*.local.md` - Ignored
- ✅ `.claude/settings.local.json` - Ignored
- ✅ `.opencode/**/*.local.md` - Ignored

## 🎓 Examples

### Example 1: Simple Rule

```yaml
---
targets: ["*"]
root: false
description: Use async/await instead of promises
globs:
  - "src/**/*.ts"
cursor:
  alwaysApply: false
---

# Async/Await Guidelines

Always use async/await instead of raw promises for better readability.
```

### Example 2: Cursor-Only Rule

```yaml
---
targets: ["cursor"]
root: false
description: Cursor-specific keyboard shortcuts
globs: ["**/*"]
cursor:
  alwaysApply: true
---

# Cursor Shortcuts

- Cmd+K - AI chat
- Cmd+L - Inline edit
```

### Example 3: Root-Level Rule (Always Loaded)

```yaml
---
targets: ["*"]
root: true
description: Project-wide coding standards
---

# Coding Standards

These standards apply to all code in this repository...
```

## 🔗 Related Documentation

- [Rulesync README](../README.md)
- [Rulesync GitHub](https://github.com/dyoshikawa/rulesync)
- [Configuration File](../../rulesync.jsonc)

## ❓ Troubleshooting

### Problem: Rules not loading in AI Assistant (Cursor, Claude Code, OpenCode, ...)

**Solution:**
1. Check frontmatter is valid YAML
2. Run `yarn rulesync:generate`
3. Restart the AI Assistant

### Problem: Import doesn't work

**Solution:**
1. Check the files exist in `.cursor`, `.claude`, or `.opencode`
2. Ensure they have proper format
3. Run the matching import script: `yarn rulesync:import:cursor`, `yarn rulesync:import:claude`, or `yarn rulesync:import:opencode`

### Problem: Git shows changes after generate

**Solution:** This is expected! The generated files should be committed along with the source files.