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.

writing-rules

Writing Rules

1. The Golden Format

One-Line Rules (when mechanism is obvious)