writing-rules

Writing Rules

Scope: covers .claude/rules/ file authoring — a Claude-Code-specific concept (path-scoped, always-loaded instruction files with paths: glob frontmatter). Codex CLI and Antigravity have no exact .claude/rules/ equivalent; their always-on project instructions live in the hierarchical memory file (AGENTS.md for Codex, GEMINI.md for Antigravity — both can be pointed at the canonical AGENTS.md; see [[nlpm:conventions-codex]] / [[nlpm:conventions-antigravity]]). The bold-imperative-plus-rationale writing technique here applies to any tool's instruction files. For CLAUDE.md / AGENTS.md conventions, see [[writing-plugins]]. For system prompts generally, see [[writing-prompts]].

1. The Golden Format

Every rule should have three parts:

**Use X, not Y.** Without X, [concrete bad thing happens]. Y causes [specific problem] because [mechanism].

Part	Purpose	Example
Imperative	What to do	Use Result<T, AppError> for all API handler returns.
Consequence	What goes wrong without it	Without it, errors propagate as 500s with no context.
Mechanism	Why it fails	Raw panics bypass the error middleware and crash the worker.

One-Line Rules (when mechanism is obvious)

**Use `const`/`let`, never `var`.** `var` hoists to function scope, causing stale-reference bugs.

Multi-Line Rules (when mechanism needs explanation)

**Use database transactions for multi-table writes.** Without transactions, partial writes leave the database in an inconsistent state. The ORM's `save()` method does not auto-wrap related writes -- you must explicitly call `db.transaction()`.

2. Positive Framing (Pink Elephant Effect)

Claude fixates on prohibited things. Saying "Don't use X" makes Claude think about X.

Before (negative framing -- score 60)

- Don't use var
- Don't mutate function parameters
- Don't use console.log in production code