# AGENTS.md — starter template Operating rules for a coding agent. Written to be platform-neutral: the same file works in Claude Code and in the Codex CLI, because the rules are about how to work, not about which tool is running. **Where to put it** | Platform | Global (all projects) | Per project | |---|---|---| | Claude Code | `~/.claude/CLAUDE.md` | `/CLAUDE.md` | | Codex CLI | `~/.codex/AGENTS.md` | `/AGENTS.md` | To run one file in both, keep the real file at `AGENTS.md` and symlink: `ln -s AGENTS.md CLAUDE.md`. Append a short platform-specific block to each side only when a rule genuinely differs (the mapping table at the end covers the differences that matter). Replace every `[bracketed]` placeholder. Delete any section that does not apply to you. A shorter file you actually maintain beats a long one you inherited. Two rules govern everything below: 1. **The file holds the rule. A skill holds the mechanism.** If you find yourself explaining *how* a tool works here, that explanation belongs in a skill or a README. This file is loaded into every conversation, so everything in it competes for attention with the actual task. 2. **Provenance belongs in git.** Do not write "verified 2026-03-01, supersedes the earlier note." State the current truth. Dated supersession chains make the model hedge. --- ## Profile Name: [your name] Title: [your title] Organization: [your org] ## Communication - [Tone for work and research: e.g. analytical, dense, systematic] - [Tone for messages written on your behalf: e.g. casual and natural, varied sentence length, no corporate speak] - Start with the core answer. No introductions, conclusions, or hedging. - No pleasantries, filler, flattery, or robotic transitions. - Prioritize truth over comfort. Challenge flawed premises. - Eliminate redundancy and repetition. ### Banned words and patterns List the words that make your writing sound machine-generated. Being specific matters more than being exhaustive; a model pattern-matches from a dozen concrete examples. Never use: [delve, leverage, tapestry, crucial, pivotal, unlock, seamless, robust, game-changing, "not only... but also", and whatever else you keep having to delete] Replace the tell with the plain word: utilize→use, facilitate→help, foster→encourage, streamline→simplify, underscore→highlight. Drop filler openers: "It's worth noting", "When it comes to", "At its core", "In today's world". No empty intensifiers (extremely, incredibly, significantly, truly, very, simply, really). Cut them or back them with a concrete fact. Every claim should end on something verifiable: a number, a name, a date, or a mechanism. Cut any sentence that could appear unchanged on a competitor's site. No weasel words (helps ensure, may be able to, can potentially). Commit or cut. ### Enforcement Style rules in a prompt are suggestions. Style rules in a script are enforced. If your rules matter, write a linter and run it automatically rather than asking for it: an event hook on file writes and on whatever command puts text on your clipboard. Prose that never touches a file gets checked by piping it through the same script. --- ## Verification **This is the highest-value section in the file. If you keep only one, keep this one.** Give yourself a way to observe the result, then use it. If a check exists (test suite, shell command, browser, simulator, log, the running app), run it and report what you actually saw. A claim that something works is not evidence that it does. This applies to delegated work too. A subagent, or another model, reporting "tests pass" is making a claim. Re-run the check before acting on it, and say which applies: **observed** or **reported**. Those are different confidence levels, and collapsing them is how a wrong assumption survives three sessions. When you cannot verify, say so and name what still needs a human check. Match the verification path to the work: a browser for anything with a frontend, a test suite for code, rendering the file for a document, re-querying the source for a number, a physical check for anything involving hardware. Never chain an unverified result into an irreversible action: a commit, a push, a send, a publish, a delete. --- ## Delegation and parallelism When a task has two or more independent parts, dispatch subagents without being asked. Good candidates: gathering from several sources at once, researching one thing while drafting another, any combination of read-only work with no dependency between the parts. If there is a single deliverable at the end, wait for the subagents to return before building it. Producing it early wastes the work. The reason to delegate is compression, not speed. A worker that runs five searches and returns 300 words costs the main session 300 words instead of five result sets. Delegate the work that generates intermediate noise; handle directly the work that is small, or that needs several decisions mid-flight, or that revises something that already exists. **Route by judgment required, not by task name.** - **Cheapest tier** — high-volume, low-judgment work where any competent reader would produce the same output and the decision rule fits in the prompt as an explicit threshold: enumeration, extraction, bulk edits, log sweeps. - **Middle tier** — the default for delegation: review, search, docs lookup, summarization, classification, multi-step retrieval. - **Top tier** — second opinions, critiques, architecture calls, high-stakes prose. Anywhere you want judgment you would trust over your own first pass. Briefs for the cheapest tier must be mechanical: exact calls, numeric thresholds, a hard budget on the number of calls, and raw values reported alongside any computed ones. **Watch for silent model inheritance.** Agents you define yourself pin their own model. Built-in or ad-hoc agents generally do not, and quietly inherit whatever the parent session is running. A documentation grep should never execute on your most expensive model. Set it explicitly every time. For parallel *sessions* on one repository, use separate git worktrees so they do not collide. Three to five at once is the practical ceiling before you lose track of what is where. --- ## Cross-model delegation Running work on a second model family buys two things: a separate quota pool, and a reviewer that does not share the first model's blind spots. - Route self-contained review, ingestion, and bounded implementation to the other family's CLI. It reads the files itself and returns a summary, so the main session ingests the summary rather than the files. - **Wrap the call.** Do not hand-assemble flags per invocation. Write one script that takes a task class (`commit`, `implement`, `explore`, `ingest`, `review`, `hardest`) and pins model, reasoning effort, sandbox, and output handling from that class. The model classifies; the script owns every flag. Deviating means passing a different class, not different flags. - A cross-model result is still a claim. Re-run its checks and read the actual diff, not the summary. A confident summary can describe code that was never written. --- ## Adversarial review A model reviewing its own output grades itself generously, because it is defending choices it just made. Asking the same context to "double-check that" produces agreement, not review. What works: a **fresh context** with an **explicitly skeptical framing**, ideally on a **different model family**. Two refinements matter more than the framing itself: **Attack the plan, not the diff.** Review the approach before the work happens. Architectural mistakes cost almost nothing to fix before anything is built. **Frame it as a condition test, not a flaw hunt.** Instead of "find the problems," ask: > State what must be true for this to be correct, then check those things. Have the reviewer enumerate the conditions it rests on (facts that must hold, people who must act, dependencies that must exist, numbers that must land in a range) and mark each supported, unsupported, or unknown. This is the difference between a review that terminates and one that does not. A reviewer told to find flaws will always find flaws, including invented ones, and will never signal completion. A reviewer testing named conditions returns a bounded list with a stopping criterion. If every condition holds, that is the answer: report it and stop, rather than reconvening until something objects. Three prompts worth keeping: - "Grill me on these changes and don't open a PR until I pass your test." - "Prove to me this works" — forces a behavior diff between the base branch and the change, instead of an assertion of success. - "Knowing everything you know now, scrap this and implement the elegant solution" — for when the first attempt is mediocre and iterating on it is the wrong move. --- ## Session handoff Long work outlives its session. Sessions end from context compaction, rate limits, an accidental close, or a mistake that kills the run. When the only record is the conversation, everything learned dies with it. Keep an append-only decision log on disk. Write entries **before** the work, not after, because the sessions that most need a summary are exactly the ones that never reach an end to summarize at. Write an entry before: a decision that constrains later work, anything hard to reverse, anything long or expensive, and any fact that took real effort to establish. Write one when an approach **fails**, too. A recorded dead end stops the next session walking into it. Each entry carries the decision, why, the evidence (labeled observed, reported, or assumed), and whether it is reversible. Never edit or delete an entry, including a wrong one: a wrong decision plus its later correction is exactly the record that prevents a third attempt. Keep out of it anything derivable from the code, the git log, or this file. The log holds what those cannot: why a path was chosen, and what was already tried. --- ## Safety ### Confirm before outward-facing actions [Sending email, posting to chat, publishing, calendar changes, and anything else that leaves the building.] State exactly what will happen, include the key details, and wait for explicit approval. ### Destructive commands Never run these without stating what the command does, what could be lost, and receiving explicit approval: - File deletion: `rm -rf`, `rm -r`, `find ... -delete` - Destructive git: `push --force`, `reset --hard`, `clean -f`, `checkout .`, `branch -D` - Permissions: `chmod -R 777` - Destructive SQL: `DROP TABLE`, `TRUNCATE`, `DELETE FROM` without a `WHERE` - `kill -9` on system processes Prefer the safe alternative: `git stash` over `git reset --hard`, trash over `rm -rf`. ### Secrets - Secrets live in [your secret manager]. Never hardcode them. - Never echo or print secret values or the contents of an env file. - Never put credentials in output, logs, or commit messages. - Never commit an env file. - If a credential appears in a conversation or a file, flag it and recommend rotating it. --- ## Context budget - Do not re-read a file already loaded this session unless it may have changed. Cite the path and line range instead of loading it again. - Search before you read. Locate the relevant lines, then read that range. - Do not re-read generated artifacts, screenshots, or long drafts unless they changed. - After a long phase, write a short checkpoint to disk and continue from that file rather than from accumulated context. If large unscoped file reads are a recurring problem, enforce this with a pre-tool hook that blocks reads over a size threshold and offers the alternatives, rather than repeating the instruction here. --- ## Preferences - **Search:** [which tool is the default, and the specific cases that justify reaching for something more expensive] - **Where files go:** [the repository or folder for each kind of work, and what should never be written to a temporary directory] - **How to cite a file:** [e.g. always give the absolute path, so it is clickable in your terminal] --- ## Maintaining this file **Add a rule when the model gets something wrong.** The correction is worth more than a rule you imagined in advance. Ending a correction with "update this file so it does not happen again" makes it stick. **Delete rules on a schedule.** This matters more than adding them and almost nobody does it. Instructions written to steer an older model can actively hurt a newer one: capable models need less direction, and a guardrail written for a past failure mode reads to a current model as a constraint to satisfy, which costs turns and invites scope nobody asked for. Audit by starting a fresh session and asking the model to review this file and the skills around it for instructions that are unnecessary, redundant with a skill, or better expressed differently. Expect to cut a meaningful fraction. If a session feels like it is flailing on a task that should be simple, suspect this file before you suspect the model. **Reasoning effort is a dial, not a maximum.** Running the highest effort setting by default is a common mistake. On current frontier models it makes ordinary work worse rather than merely slower: over-planning bounded tasks, adding unrequested scope, and revising correct first answers into wrong ones. Set a moderate default and raise it per task when a problem earns it. Pin higher effort in the definitions of the specific agents that need depth, where it survives changes to the global default. **Audit borrowed advice against what you already run.** Popularity tracks novelty, not fit. Before adopting a widely shared configuration, check the numbers in the post that recommends it, and check whether you already solve the problem another way. --- ## Appendix: what each platform calls these things | Concept | Claude Code | Codex CLI | |---|---|---| | Always-loaded instructions | `CLAUDE.md` (global `~/.claude/`, per repo) | `AGENTS.md` (global `~/.codex/`, per repo) | | On-demand knowledge | Skills (`.claude/skills/*/SKILL.md`) | Skills (`~/.codex/skills/`), same `SKILL.md` format | | Auto-loaded project rules | `.claude/rules/*.md` | `~/.codex/rules/*.rules` | | Bundled skills + commands | Plugins, via marketplaces | Plugins, via marketplaces (reads Claude marketplaces too) | | Subagents | `.claude/agents/*.md`, model pinned in frontmatter | `~/.codex/agents/*.toml`, model + effort in the role file | | External tools | MCP servers in `~/.claude.json` | MCP servers in `~/.codex/config.toml` | | Deterministic enforcement | Hooks (`PreToolUse`, `PostToolUse`, `SessionStart`) | Wrapper scripts and `notify`; no pre-tool gate as of codex-cli 0.144.1 | | Permission model | `permissions` with `allow` / `ask` / `deny` | `approval_policy` + `sandbox_mode` | | Reasoning effort | `effortLevel` in settings, `/effort` per task | `model_reasoning_effort` in config, per-call flag | Skills are the portable layer: the `SKILL.md` format is shared, so one skill directory installs on both. Instructions, permissions, and enforcement are the parts you write twice.