Split modular guidance from execution rules

Understand the approach

The word rule can refer to two different things. A prose rule might say how to write a changelog; an execution rule controls whether a command can run outside the sandbox. The Claude source uses modular Markdown rules, including path-specific metadata. Codex does not inherit that .claude/rules format simply because the repository contains it. Use documented Codex instruction discovery and explicit references instead.

For modular guidance, keep AGENTS.md short and point to a focused document when a task needs it. A UI guideline file can explain naming, accessibility and visual checks without loading a long design policy into every unrelated task. Nested AGENTS.md files can specialize guidance by working directory. A reference is a reading instruction, not a guarantee that arbitrary linked Markdown has already been loaded automatically.

Codex execution rules are a separate, currently experimental feature using .rules files and prefix_rule entries. They match command argument prefixes and return allow, prompt or forbidden decisions. When several rules match, the most restrictive decision wins. Project-local rule layers require project trust. Do not put stylistic preferences in that file type or treat an allow decision as user authorization to send, publish or alter an external system.

A concrete policy result without installing a rule

The supplied review.rules prompts for the prefix node --test and forbids the narrower node --test private-checks.cjs. The two evaluator examples show why the stricter matching decision wins. The file lives outside active .codex/rules locations; evaluating it does not grant permission or run checks.cjs.

For the writing exercise, keep the convention in Markdown and reference docs/writing-guidelines.md from AGENTS.md. Correct the unsupported README command, label it unrun until executed, and compare the resulting document. Prose instructions and execution-policy syntax solve different problems.

An execution rule is not a style rule

If you later need command policy, study the official prefix matching and test tools before installing a rule. A harmless-looking command wrapper can contain more than one action, so broad exceptions require care. This beginner exercise deliberately changes only project documentation. It teaches the distinction without weakening the learner’s sandbox or modifying personal command approvals.

Try it step by step

1. Classify three proposed rules as project guidance, optional reference material or command execution policy.
2. Move a detailed documentation convention into docs/writing-guidelines.md in the scratch project.
3. Reference that file from project guidance only for documentation tasks, then ask Codex to confirm what it actually read.
4. Read the execution-rule example as a draft only; leave personal policies and trusted-project settings unchanged.

A useful starting example

Illustration · adapt before use.

## Documentation work
Before editing documentation, read docs/writing-guidelines.md.
Use that file for heading and example conventions.
For code-only tasks, read it only when the task also changes public documentation.
Preserve unrelated edits and report the actual validation performed.

codex execpolicy check --rules ./exercises/review.rules -- node --test checks.cjs
codex execpolicy check --rules ./exercises/review.rules -- node --test private-checks.cjs

Check your result

• The modular guideline is explicitly referenced and its use is verified through an actual documentation task.
• No unsupported Claude YAML path-rule syntax is presented as a Codex instruction mechanism.
• You can distinguish prose guidance, command policy and user authorization with a concrete example of each.

Common mistakes

• Copying .claude/rules files unchanged and assuming Codex interprets their metadata.
• Allowlisting a broad shell prefix to make a writing convention easier to follow.