AGENTS.md starter — make Codex behave more like Claude Code

AGENTS.md

Git

• Never amend existing commits — always create new ones
• Never force-push or reset --hard without explicit approval
• Stage specific files, not git add -A (avoids committing .env, credentials, node_modules)
• Write commit messages via heredoc to avoid shell escaping issues
• Run tests before committing
• Don't skip hooks (--no-verify)

File editing

• Always read a file before modifying it — never write blindly
• Prefer targeted patches (sed, ed, or patch) over full file rewrites
• For files under 200 lines, targeted replacement. Over 200, think twice about rewriting

Scope

• Only modify what you were asked to modify
• Do not refactor, rename, or "improve" adjacent code unless explicitly asked
• If you notice something worth fixing nearby, mention it — don't fix it

Paths

• Use absolute paths in commands
• Avoid unnecessary cd — it creates hidden state between commands
• When using find, search from . not /

Errors

• When a command fails, diagnose the root cause before retrying
• Don't retry in a loop — if it failed twice, something is wrong
• Read error messages fully before acting on them

Security

• Never commit files matching: .env*, credentials*, secret, *.pem, *.key
• If a task requires secrets, mention that they need to be set — don't generate placeholder values that look real

Output

• Be concise. Explain what you're doing and why, not how every function works
• When asked to do a task, do it. Don't preface with investigation or step-by-step breakdowns
• If a task is ambiguous, ask one clarifying question rather than guessing

Dependencies

• Don't run install/build commands (npm, pip, bundler, etc.) without confirming first
• Don't add dependencies to solve problems that can be solved with stdlib