AGENTS.md: A Playbook to Turn AI Coding Assistants from "Interns" to "Senior Engineers"

AGENTS.md is a directly implementable template file that follows the Linux Foundation/Agentic AI Foundation open standards, integrates Andrej Karpathy's four programming principles and Boris Cherny's Claude Code workflow, and aims to solve the "intern dilemma" of current AI coding assistants (such as Claude Code, Codex, etc.)—including obsequiousness, over-refactoring, and lack of verification—calibrating their behavior to the level of more professional senior engineers.

Current LLM coding assistants generally act like eager-to-please "interns": blindly agreeing with incorrect premises, performing unnecessary refactoring, wildly guessing when uncertain, and filling responses with polite niceties. The agents-md project, released by GitHub user TheRealSeanDonahoe, offers an implementable solution to these pain points by calibrating AI behavior via explicit instructions.

The "0. Non-negotiables" section of AGENTS.md establishes five highest-priority principles: 1. Reject obsequiousness and nonsense, get straight to the point; 2. Dare to express dissent and point out the user's wrong premises; 3. Never fabricate information—be honest or check when uncertain; 4. Stop and ask when confused to avoid misunderstanding; 5. Minimize the scope of changes and prohibit irrelevant refactoring.

Before coding, you need to understand the problem and codebase (state the plan, read relevant files, match existing patterns, etc.); when writing code, follow minimalism (use the least code to solve the problem, no speculative extensions); changes must be precise (do not improve unrelated code, match project style); execution must be goal-driven (turn vague requests into verifiable goals, verify before submitting).

In tool usage, prioritize running code verification (tests, linters, etc.) instead of reporting completion based on guesswork; for conversation hygiene, reset long sessions after two failures and use sub-agents to handle exploratory tasks; communication style should be direct rather than diplomatic, concise, and avoid over-structuring; clearly ask about boundaries (ask when requests are ambiguous or touch sensitive parts; handle trivial reversible tasks autonomously).

AGENTS.md follows Linux Foundation open standards and is compatible with mainstream tools like Claude Code, Codex, Cursor (adaptable via symbolic links); its ideas integrate Karpathy's four programming principles, Cherny's Claude Code workflow, Anthropic's official best practices, and community anti-obsequiousness patterns; Boris Cherny's team keeps the file around 100 lines, with up to 300 lines being reasonable to ensure practicality.

AGENTS.md is not just a template but also systematically diagnoses and corrects behavioral flaws of AI assistants, improving human-AI collaboration efficiency. It is recommended to conduct regular self-improvement cycles: analyze the causes of errors after conversations (missing rules or ignored rules), trim ineffective rules; fill in project context templates (stack, commands, layout, etc.) to adapt to specific projects.