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

# Best Practices

> Get the most out of Blocklight with these recommendations

Get the most out of Blocklight with these recommendations:

## Start Simple

Begin with [basic rules](/rules/structure). Keep rules simple and focused on what you need to detect.

## Always Validate & Test

Use [validate](/cli/validate) and [dry-run](/cli/dryrun) before deploying rules.

### Use Testing Directory for Development

Create new rules in `rules/testing/` first, then test them with `dry-run` before moving to production:

1. **Create rule in testing directory:**
   ```bash theme={null}
   # Create your rule
   vim rules/testing/my_new_rule.yaml
   ```

2. **Test it safely:**
   ```bash theme={null}
   # Test without affecting production (dry-run automatically includes testing rules)
   blocklight dry-run --tx 0xabc123...
   ```

3. **Move to production when ready:**
   ```bash theme={null}
   # Once validated, move to custom
   mv rules/testing/my_new_rule.yaml rules/custom/
   ```

**Important:** Rules in `rules/testing/` are **NEVER** loaded in production (when running `blocklight start`). The `dry-run` command automatically includes them for testing purposes, ensuring you can test rules safely without generating alerts or affecting your monitoring system.

## Caching

[Caching](/features/caching) is always enabled in Blocklight for optimal performance. Configure appropriate TTL values in [analysis config](/deployment/configuration) based on your use case.

## Reuse Components

Use [lists and macros](/rules/macros) to keep rules maintainable. **Important**: `lists` and `macros` are defined at the file level (not inside rules), allowing you to create reusable building blocks that multiple rules in the same file can share.

**File Organization**: When grouping multiple rules in the same file, ensure they are related to each other (e.g., same category, threat type, or protocol). While `lists` and `macros` can be shared across rules in the same file, mixing unrelated rules can make maintenance complex. Organize rules by category, threat type, or protocol to keep your rule base maintainable. See [Rule Structure](/rules/structure#organizing-rules-in-files) for more details.

## Secure Your Secrets

Use `${ENV_VARS}` in [alert configuration](/deployment/configuration#alert-configuration). Never commit secrets.