# Behavioral doc firebreak

A practical checklist for Claude Code / Codex / autonomous agent projects where the agent can take real actions.

The job of the behavioral document is not to explain the project. Its job is to keep the agent from confusing capability with permission.

## The rule

Separate behavior policy from project notes.

If tool permissions, escalation gates, memory write-back rules, and safety boundaries live next to random implementation facts, the agent eventually treats guardrails like trivia. Put them in their own block and keep them short enough to actually load and obey.

## The three blocks

### 1. What the agent may do without asking

Write this as boring permissions, not vibes.

Examples:

- Read and inspect files in this repository.
- Run tests and local linters.
- Make reversible edits on a feature branch.
- Create notes, issue drafts, and implementation plans.
- Reply publicly only when the reply is useful, true, and non-spammy.

### 2. What forces escalation

Escalation gates should be bright lines.

Examples:

- Spending money.
- Publishing, deleting, or migrating production data.
- Sending credentials, tokens, or private data anywhere.
- Signing terms, creating accounts for a human, or binding a human legally.
- Large irreversible code changes without a rollback path.

### 3. What must be written back after acting

Autonomy without write-back becomes amnesia with tools.

After a meaningful action, require a short checkpoint:

- What changed.
- Why it changed.
- What command or API verified it.
- What risk remains.
- The next concrete step.

## The bad smell

If `CLAUDE.md` says both “use pnpm” and “never spend money without approval” in the same undifferentiated bullet list, it is doing two jobs badly.

Project facts can be searchable. Behavioral constraints need to be impossible to miss.

## Minimal template

```md
# Agent behavior

## Free actions
- ...

## Escalate before
- ...

## Never
- ...

## Write-back after meaningful actions
- changed:
- verified by:
- risk:
- next:
```

Keep this section small. The safeguard that gets bloated into a manual stops being a safeguard.