> For the complete documentation index, see [llms.txt](https://docs.codemate.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codemate.ai/cora/configuration/rules.md).

# Rules

Rules are the invariants of your codebase things that are always true regardless of what the prompt says. Unlike skills, which provide context Cora uses when relevant, rules constrain behavior unconditionally. Cora follows a rule even if a prompt implicitly suggests otherwise.

<figure><img src="/files/5ZlnqXpORT8OKpdsPWfV" alt=""><figcaption></figcaption></figure>

***

### Storage locations

**Global rules** apply to every project:

```
~/.config/Code/User/globalStorage/codemateai.codemate-agent/settings/rules/
```

**Project rules** apply to the current workspace only:

```
your-project/.cora/rules/
```

Project rules take precedence over global rules when a file with the same name exists in both locations.

***

### What goes in rules

Rules are best suited to constraints where a violation would cause a bug, a security issue, or a consistency problem that would need to be fixed before merging. Good candidates:

* Security invariants: "every database query on tenant-owned data must include an orgId filter"
* Forbidden patterns: things done wrong in the past that must not recur
* Required structures: things every module of a given type must have
* Import constraints: what can import from what, what must not be imported in certain contexts
* Naming conventions that apply everywhere without exception

***

### Creating rules

Create a `.md` file in the rules directory. Write rules as direct, unambiguous statements not explanations, but declarations of what Cora must or must not do.

**Example: `rules/security.md`**

```markdown
# Security rules

Every Prisma query that accesses tenant-owned data must include a
`where: { orgId }` clause. No exceptions, including admin endpoints.

API keys must never be stored in plaintext. Always hash with bcrypt
before writing to the database. Store the first 8 characters in a
separate `prefix` field for UI display.

The ingestion API must never accept JWT authentication.
API key auth via X-Api-Key header only.

Every Express route handler must validate the request body with a
Zod schema before reading any properties from req.body.

Never log full API keys, JWTs, or password hashes. Log the key
prefix or a redacted placeholder instead.
```

**Example: `rules/naming.md`**

```markdown
# Naming conventions

Database models: PascalCase singular — User, Organization, ApiKey.
Service files: camelCase — userService.ts, apiKeyService.ts.
Route files: kebab-case matching the resource — api-keys.ts.
React components: PascalCase. Filename matches the component exactly.
Zod schemas: Schema suffix — CreateUserSchema, UpdateOrgSchema.
Environment variables: SCREAMING_SNAKE_CASE with service prefix —
  DASHBOARD_DATABASE_URL, INGESTION_REDIS_URL.
```

***

### Rules vs. skills

Rules are unconditional. Skills are contextual. If you find yourself writing a skill that says "always do X" it belongs in a rules file instead. A practical test: if Cora violated this during a code generation pass, would you need to fix it before merging? If yes, it's a rule.

***

### Editing rules directly

```bash
# Edit a global rule
code ~/.config/Code/User/globalStorage/codemateai.codemate-agent/settings/rules/security.md

# Edit a project rule
code .cora/rules/security.md
```

All rule files in a given scope are loaded together on every task. There's no per-file scoping every rule applies everywhere within its scope.