How Pinned Rules Keep Coding Agents on Track

A coding agent can read a rule, agree with it, and still drift away from it during a long session. Pinned rule injection keeps a few critical instructions in the foreground by adding them to the agent's context whenever the user submits a prompt. Both Codex and Claude Code support UserPromptSubmit hooks that can add this context.

This is runtime steering, not fine-tuning. It does not guarantee obedience, but it makes the rules that matter most much harder to overlook.

Two rules worth pinning

Claude is particularly notorious for narrating its work inside source files: long headers, obvious explanations, debugging history, and paragraphs of rationale. Enough of this makes code unreadable for humans, including the rare comment that carries a real constraint.

A useful pinned rule is load-bearing comments only. Keep a comment only when a competent reader could not infer it from the code. Prefer one line. Put reasoning and history in commit messages or private notes. During final review, delete each comment and restore it only if something essential was lost.

The second rule is never use the agent as a polling loop. During a recent release, an agent repeatedly spent turns reporting that the remote workflow was still running. Nothing changed, but every continuation consumed quota.

Use a detached systemd service, cron job, or equivalent monitor instead. It should wait outside the model, record terminal evidence, and send one wake event only when it owns the matching thread, goal, and external run. It must never resume a goal that was already paused by the user or stalled for another reason.

Pin by scope, not severity

A pinned rule should be short, stable, repeatedly useful, and relevant to nearly every session. Project commands belong in repository instructions. Detailed procedures belong in skills or runbooks. Changing operational state and one-time requirements belong in the current task. Deterministic restrictions should be enforced by code when possible.

This distinction matters. A strict command-format rule for one reconstruction workflow was once promoted from its existing skill into every agent prompt. It was important, but irrelevant almost everywhere else. Pinning it added noise rather than safety.

A dedicated host is the exception. If every session on a machine shares one narrow purpose, a host profile can inject the specific rules that genuinely apply there.

Turn recurring corrections into rules

Start with a failure you have corrected more than once. Reduce it to one imperative that names the trigger, required action, and final check: “When X happens, do Y; never use Z; verify Q before finishing.” Leave the incident story out of the injected text.

Review the pinned set regularly. Remove rules that no longer earn their context, move situational instructions into the relevant project or skill, and replace deterministic rules with code or a linter. Two or three sharp rules steer an agent better than a catalog in which every preference claims to be critical.