> For the complete documentation index, see [llms.txt](https://kerno.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kerno.gitbook.io/docs/guides/how-to-customize-kerno-with-custom-rules.md).

# How to Customize Kerno with Custom Rules

### Introduction

Custom rules are standing guidance you keep in your repository, so Kerno applies them on every run without you restating them. They shape how the planner writes tests, and they travel with your code.

In this guide, you will add a rule, apply it to an endpoint, and then edit and remove rules. For how rules are weighed, merged, and matched to endpoints, see Custom Rules.

### Prerequisites

Before you begin, you will need:

* [Kerno installed](/docs/getting-started/quickstart.md) and connected to your coding agent over MCP. 
* Your application running, with the [Kerno test environment configured and ready.](/docs/guides/start-the-environment.md) 

### Step 1. Add a rule

The quickest way to add a rule is to ask your agent:

```
Add a Kerno rule for POST /api/users: a duplicate email should return 409.
```

Your agent writes the rule into your Kerno config under `test-generation`. Put shared conventions in `.kerno/default.config.yaml` so your team inherits them, and keep machine-local rules in `.kerno/config.yaml`. A `context` block applies to every endpoint, and an `endpoints` map scopes guidance to specific routes:

```
test-generation:
  context: |
    ...
  endpoints:
    "POST /api/users": |
      ...
```

You can also edit this file by hand. The endpoint pattern grammar is covered in [Custom Rules.](/docs/core-concepts/custom-rules.md)

### Step 2. Apply and verify

A new rule shapes the next `generate` for an endpoint that has no tests yet. Ask your agent to generate that endpoint:

```
Use Kerno to generate tests for POST /api/users.
```

When the plan comes back for review, the guidance shows up in the scenarios it proposes, here a scenario covering the duplicate-email case. Approve the plan to implement them.

### Step 3. Apply a rule to an endpoint that already has tests

To bring an endpoint that already has tests in line with a new rule, generate it again and tell your agent to apply the rule:

```
Use Kerno to generate tests for POST /api/users again, applying the new duplicate-email rule.
```

This re-plans that endpoint with the rule in effect. Editing the config on its own leaves existing tests as they are, see Custom Rules. For a single run you can pass the same guidance as a one-off with `test_generation_context`, see Testing modes.

### Step 4. Edit or remove a rule

Ask your agent to change or remove a rule:

```
Update the Kerno rule for POST /api/users to also assert the response includes the created user id.

Remove the Kerno rule for POST /api/users.
```

You can also edit the config by hand, change a rule's text to edit it, or delete its `context` block or `endpoints` entry to remove it.

Edits and removals behave like additions. They change what Kerno plans on the next generate, and they leave existing tests untouched. Re-generate the affected endpoints when you want the change to apply.

If the same endpoint is covered by both files, your local `.kerno/config.yaml` wins. For the full merge and precedence order, see [Custom Rules](/docs/core-concepts/custom-rules.md).

### Step 4. Edit or remove a rule

To edit a rule, change its text in the config file. To remove one, delete its `context` block or its entry in the `endpoints` map.

Edits and removals behave like additions. They change what Kerno plans on the next generate, and they leave existing tests untouched. Re-generate the affected endpoints when you want the change to apply.

If the same endpoint is covered by both files, your local `.kerno/config.yaml` wins. For the full merge and precedence order, see [Custom Rules](/docs/core-concepts/custom-rules.md).

### Conclusion

That is the rule lifecycle. Add a rule, generate to apply it, and edit or remove it as your conventions change, re-generating the affected endpoints each time. From here, see Custom Rules for how rules are weighed and matched, Testing modes for per-run guidance, and How to Set Up the Kerno Agent Hook to have your agent re-validate changed endpoints automatically.