> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Rules

> Encode your team standards and preferences into every milestone

export const ProductName = "The Morph Platform";

export const productName = "the Morph Platform";

Rules are custom instructions that apply across your entire migration. They let you encode specific requirements, coding standards, or preferences that {productName} should follow in every milestone.

## Why Create Rules

### You Know Your Standards

Every team has conventions. Maybe you:

* Always use a specific logging library
* Follow particular naming conventions
* Have standard patterns for error handling
* Require certain testing approaches

Rules let you capture this knowledge so {productName} respects it throughout your migration.

### Consistent Output

Without rules, {productName} makes reasonable choices-but they might not be *your* choices. Rules ensure:

* All generated code follows your patterns
* The same standard applies across every milestone
* You don't have to fix the same issue repeatedly

### Prevent Repeated Mistakes

If you review a milestone PR and notice something wrong, ask: "Will this happen again?" If yes, create a rule. The next milestone-and all after-will follow it.

## When to Create Rules

Create a rule when you:

* **Know exactly what you want** - You have a specific requirement, not a vague preference
* **See a pattern emerging** - The same issue appears across milestones
* **Have company standards** - Your team has documented conventions
* **Need specific library usage** - You want {productName} to use particular dependencies

## Rule Examples

### Coding Conventions

```
When translating to Python, follow these conventions:
- Use snake_case for function and variable names
- Use PascalCase for class names
- Maximum line length of 88 characters (Black formatter style)
- Use f-strings instead of .format() or % formatting
```

### Library Preferences

```
For all database access in the destination code:
- Use SQLAlchemy 2.0 with async support
- Implement the repository pattern
- Create separate repository classes for each entity
- Never write raw SQL in service layers
```

### Testing Requirements

```
For all generated tests:
- Use pytest as the testing framework
- Follow the Arrange-Act-Assert pattern
- Each test file should mirror the source file structure
- Use factory_boy for test fixtures
- Aim for 80% code coverage on new code
```

### Error Handling

```
For error handling in the destination code:
- Create custom exception classes for domain errors
- Use try-except blocks only for operations that can fail
- Log all exceptions before re-raising
- Never swallow exceptions silently
```

### Architecture Patterns

```
When migrating the service layer:
- Implement dependency injection for all services
- Services should depend on abstractions, not implementations
- Keep services stateless
- Use constructor injection, not method injection
```

### Specific Avoidances

```
Do NOT use the following in destination code:
- Global variables or module-level state
- print() for logging (use the logging module)
- Wildcard imports (from x import *)
- Mutable default arguments in functions
```

## Creating a Rule

1. In your project, find the **Rules** section in the left sidebar
2. Click the **+** button - the Knowledge drawer opens in rule-edit mode with a default title (e.g., "Rule 1")
3. Click the title to edit it - give it a short, descriptive name (e.g., "Python naming conventions")
4. Fill in **Description** (`Apply this rule when...`) - when this rule applies. A description is required to save.
5. Write the rule body in the markdown editor below - the specific instructions
6. (Optional) Toggle the **Active** checkbox off to save as a draft
7. Click **Create Rule**

When editing an existing rule, the same button reads **Save Changes**.

### Writing Effective Rules

**Be Specific**

Instead of: "Write clean code"
Write: "Functions should do one thing. If a function exceeds 20 lines, consider splitting it."

**Be Actionable**

Instead of: "Use good error handling"
Write: "Wrap external API calls in try-except blocks. Log the error with full context. Re-raise as a custom DomainException."

**Provide Examples When Helpful**

```
When converting callbacks to async/await:

INSTEAD OF:
getData(function(result) {
  process(result);
});

USE:
const result = await getData();
process(result);
```

## How Rules Are Applied

Rules are included in the context for every task in every milestone. When {productName} generates code:

1. It reads all active rules for your project
2. It applies them alongside the milestone-specific instructions
3. Generated code reflects both the milestone goal and your rules

## Managing Rules

### Viewing Rules

Click on any rule in the Rules section to view its full content.

### Editing Rules

1. Click on a rule
2. Modify the title, description, or content
3. Save your changes

Edited rules apply to future milestones. Already-completed milestones aren't affected.

### Deleting Rules

From the **Rules** sidebar:

1. Click the **×** icon on the rule's row (always visible - no hover required)
2. Confirm deletion in the dialog that opens

Alternatively, when a rule is open in the editor, click the **Delete** button (trash icon) in the action bar and confirm.

Deleted rules no longer apply to future milestones.

## Best Practices

### Start Focused

Don't try to create 20 rules upfront. Start with:

1. Your most important coding conventions
2. Critical library or framework requirements
3. Any non-negotiable patterns

Add more rules as you review milestones and notice gaps.

### Review Rule Effectiveness

After a few milestones, check:

* Are the rules being followed?
* Are they too vague (and being ignored)?
* Are they too strict (and causing issues)?

Adjust as needed.

### Keep Rules Maintainable

Many specific rules are better than one giant rule. Separate concerns:

* One rule for naming conventions
* One rule for error handling
* One rule for testing patterns

This makes rules easier to update and understand.

## Rules vs. Project Spec

| Project Spec                           | Rules                            |
| -------------------------------------- | -------------------------------- |
| Define the overall migration goal      | Define recurring standards       |
| Approved once, apply to entire project | Can be added/modified anytime    |
| Describe *what* to migrate             | Describe *how* to write code     |
| Set at project start                   | Added as you learn what you need |

Both work together. The Project Spec sets the direction. Rules fine-tune the execution.