Skip to main content

Custom Rules

Custom rules allow you to define specific guidelines and instructions that shape how AI agents behave in Forge. These rules act as persistent instructions that get injected into every AI conversation.

Looking for best practices and examples?

For comprehensive examples, team management strategies, and real-world use cases, check out our Custom Rules Guide.

Configuration​

Custom rules are defined in your forge.yaml file and can be set globally or per-agent.

Global Rules​

Apply rules to all agents:

# forge.yaml
custom_rules: |
  - Use TypeScript strict mode
  - Add error handling to all functions
  - Include unit tests for new code
  - Follow team naming conventions

Agent-Specific Rules​

Apply rules to individual agents:

# forge.yaml
agents:
  - id: frontend-specialist
    custom_rules: |
      - Use React functional components with hooks
      - Include accessibility attributes
      - Use CSS modules for styling

  - id: backend-specialist
    custom_rules: |
      - Use dependency injection for services
      - Add request/response logging
      - Validate all input with schemas

Rule Format​

Custom rules support:

  • Plain text instructions
  • Markdown formatting (lists, code blocks, emphasis)
  • Multi-line content using YAML's | syntax
  • Code examples within the rules

Example with formatting:

custom_rules: |
  Error Handling Pattern:

  Always use this pattern:
  ```typescript
  try {
    // risky operation
  } catch (error) {
    logger.error('Operation failed:', error);
    throw new AppError('User-friendly message');
  }
  ```

How It Works​

  1. Loading: Rules are loaded when Forge starts
  2. Injection: Rules become part of the AI's system prompt
  3. Application: AI applies rules to every response in the session
  4. Precedence: Global rules override agent-specific rules

Rule Precedence​

When rules conflict:

# Global rule
custom_rules: "Use tabs for indentation"

agents:
  - id: frontend
    # This gets overridden by the global rule
    custom_rules: "Use 2 spaces for indentation"

Global rules override agent-specific rules.

Troubleshooting​

Rules Not Applied​

  • Check YAML syntax (whitespace-sensitive)
  • Verify forge.yaml is in project root
  • Restart Forge session to reload rules

Viewing Active Rules​

Export session context to see what rules are active:

/dump html

This shows exactly what context (including custom rules) is sent to the AI.