CLAUDE.md / AGENTS.md Starter Template

This is the generic version of the instruction file I actually run, with my paths, org, and integrations stripped out and replaced with placeholders. It’s the file the agent loads into every conversation in a project, so what goes in it is a budget decision as much as a style one.

Two files, same rules:

• AGENTS.md — platform-neutral. Works in the Codex CLI (~/.codex/AGENTS.md globally, AGENTS.md at a repo root) and in Claude Code if you symlink CLAUDE.md to it. Adds a cross-model delegation section and an appendix mapping every concept across both platforms: what Claude Code calls a hook, what Codex calls an approval policy, where each one keeps skills, agents, rules, and MCP servers.
• CLAUDE.md — the same rules in Claude Code’s vocabulary, with hook events and subagent routing named directly.

Take one. They overlap by design; maintaining both is not the point.

What’s in it

Ten sections, each of which you should feel free to delete:

• Profile and communication — who you are, and the tone rules for work versus messages written on your behalf, including a banned-words list.
• Verification — observe the result rather than asserting it, and label every finding observed or reported.
• Delegation and parallelism — route subagents by judgment required rather than by task name, plus the model-inheritance trap that quietly runs cheap work on your most expensive model.
• Cross-model delegation — why a second model family buys a separate quota pool and a reviewer with different blind spots, and why the call belongs in a wrapper script that owns every flag.
• Adversarial review — how to get a real critique instead of agreement, and the reframing that stops the review loop running forever.
• Session handoff — an append-only decision log written before the work, not summarized after it.
• Safety — confirm before outward-facing actions, the destructive-command list, and secrets handling.
• Context budget — the read-and-reread discipline, with a note on enforcing it with a hook instead of a request.
• Preferences — the placeholders for your own tooling.
• Maintaining this file — the part almost everyone skips.

The three ideas worth stealing even if you don’t use the file

The file holds the rule; a skill holds the mechanism. If you’re explaining how a tool works in the instruction file, that belongs somewhere loaded on demand. Everything in this file competes for attention with the actual task, every single turn.

Label results observed or reported. A subagent saying “tests pass” and you having watched eight tests pass are different facts. Collapsing them is how a wrong assumption survives three sessions. Making the model say which one it has costs a word.

Delete rules on a schedule. Instructions written to steer an older model can hurt a newer one, because capable models need less direction and a stale guardrail reads as a constraint to satisfy. Open a fresh session, hand it your config, and ask what’s unnecessary. Expect to cut a quarter of it. When a session flails on something simple, suspect the config before the model.

How it fits

The reasoning behind each section, with the specifics I run rather than the placeholders, is in Claude Code best practices. The packaged agents and skills are at /skills. Three public repos build on the same rules: maven-template is a full working repository, organization-ai-skills is 30 skills in the open SKILL.md format that install unchanged on Claude Code and Codex, and cross-model-agent-delegation is the wrapper pair for the delegation section.