Creating Rules

Rules are custom instructions that apply across your entire migration. They let you encode specific requirements, coding standards, or preferences that 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 respects it throughout your migration.

Consistent Output

Without rules, 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 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

In your project, open Project Knowledge and find the Rules section in the tree
Click the + button — the Knowledge drawer opens in rule-edit mode with a default title (e.g., “Rule 1”)
Click the title to edit it — give it a short, descriptive name (e.g., “Python naming conventions”)
Fill in Description (Apply this rule when...) — when this rule applies. A description is required to save.
Write the rule body in the markdown editor below — the specific instructions
(Optional) Toggle the Active checkbox off to save as a draft instead of publishing immediately
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 generates code:

It reads all active rules for your project
It applies them alongside the milestone-specific instructions
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

Click on a rule
Modify the title, description, or content
Save your changes

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

Archiving Rules

If you no longer need a rule but want to keep it for reference, you can archive it by changing its status to Archived from the status dropdown in the Project Knowledge toolbar. Archived rules are inactive and do not apply to future milestones.

Deleting Rules

When a rule is open in the editor, click the Delete button (trash icon) in the toolbar and confirm in the dialog that opens. Deleted rules no longer apply to future milestones.

Best Practices

Start Focused

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

Your most important coding conventions
Critical library or framework requirements
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.

Getting Started

Setting Up Your Migration

Running Your Migration

Customization

Advanced Configuration

Support

Why Create Rules

You Know Your Standards

Consistent Output

Prevent Repeated Mistakes

When to Create Rules

Rule Examples

Coding Conventions

Library Preferences

Testing Requirements

Error Handling

Architecture Patterns

Specific Avoidances

Creating a Rule

Writing Effective Rules

How Rules Are Applied

Managing Rules

Viewing Rules

Editing Rules

Archiving Rules

Deleting Rules

Best Practices

Start Focused

Review Rule Effectiveness

Keep Rules Maintainable

Rules vs. Project Spec

​Why Create Rules

​You Know Your Standards

​Consistent Output

​Prevent Repeated Mistakes

​When to Create Rules

​Rule Examples

​Coding Conventions

​Library Preferences

​Testing Requirements

​Error Handling

​Architecture Patterns

​Specific Avoidances

​Creating a Rule

​Writing Effective Rules

​How Rules Are Applied

​Managing Rules

​Viewing Rules

​Editing Rules

​Archiving Rules

​Deleting Rules

​Best Practices

​Start Focused

​Review Rule Effectiveness

​Keep Rules Maintainable

​Rules vs. Project Spec

Why Create Rules

You Know Your Standards

Consistent Output

Prevent Repeated Mistakes

When to Create Rules

Rule Examples

Coding Conventions

Library Preferences

Testing Requirements

Error Handling

Architecture Patterns

Specific Avoidances

Creating a Rule

Writing Effective Rules

How Rules Are Applied

Managing Rules

Viewing Rules

Editing Rules

Archiving Rules

Deleting Rules

Best Practices

Start Focused

Review Rule Effectiveness

Keep Rules Maintainable

Rules vs. Project Spec