Engineering notes / Muhammad Kashif
AGENTS.md Is the New README — Here's How I Write Mine
AGENTS.md is the new README for repositories that expect coding agents as first-class contributors. Week forty-five notes threw Rosalind biodefense models, Project Glasswing finding thousands of critical flaws, humanoid …
AGENTS.md Is the New README — Here's How I Write Mine
By Muhammad Kashif · Draft · AI automation & cybersecurity builder, Pakistan
AGENTS.md is the new README for repositories that expect coding agents as first-class contributors. Week forty-five notes threw Rosalind biodefense models, Project Glasswing finding thousands of critical flaws, humanoid warehouse near-ties, Erdős problems, India AI summit pledges, and AI round-tripping money loops into the same scroll. I still opened with a file that tells an agent what it may touch. Geopolitics and safety headlines do not replace that file — they make it mandatory.
What I put in AGENTS.md
Stack, test command, formatting, forbidden paths, secret policy, review expectations, and where human approval is required. Short enough to read, strict enough to matter. README is for humans onboarding. AGENTS.md is for non-humans that will otherwise invent their own onboarding out of confidence.
I link to CODEOWNERS and to the threat model. If the agent cannot fetch those, it should not write.
Safety headlines as urgency, not as content
OpenAI GPT Rosalind limited to governments and allies, Anthropic Project Glasswing with Claude Mythos finding over ten thousand critical flaws, Figure nearly matching a human on packages, DeepMind agents on open Erdős problems — these tell me agent capability and dual-use risk are both rising. My AGENTS.md answers with tighter tool allowlists and mandatory security skills, not with a blog rant pasted into the repo.
India AI summit language about data sovereignty, multilingual access, and human control becomes residency and language notes in the same file when the client is local.
Round-tripping awareness
OpenAI–Microsoft–Nvidia and Amazon–Anthropic money loops that inflate apparent markets are a procurement caution. I do not let hype cycles rewrite AGENTS.md every week. I do schedule quarterly reviews when contracts or model availability shift.
OpenAI–Tata and Anthropic Bangalore presence are distribution facts for my clients, not excuses to skip evals.
Creative tool noise stays out
ElevenLabs Music, Runway Aleph, Genie worlds, Storybook, Deep Think, Qwen text rendering, Grok Imagine — wonderful, and not what AGENTS.md is for unless the repo is a creative pipeline. Scope creep in the agent brief is how a coding agent starts "helpfully" regenerating brand assets mid-refactor.
Separate DESIGN.md — Google open-sourcing the idea helped — for visual systems. Agents read the file that matches the job.
Humanoid and research humility
A humanoid losing by a few hundred packages in a long shift, agents solving hard math problems — humility cuts both ways. Do not underestimate agents on structured tasks. Do not overestimate them on messy social ones. AGENTS.md encodes that humility as "ask when unsure" and "do not invent metrics."
Glasswing-shaped checks
If frontier agents can find thousands of critical flaws, my own repos should invite that scrutiny in staging with scoped credentials. I add a scheduled security agent job that only comments, never patches main. Humans patch.
Finding flaws is allowed. Silent self-patching of production is not in the file — ever.
Template I reuse
Copy AGENTS.md from a known-good repo, delete irrelevancies, fill stack-specific test commands, add client residency notes, commit before the first agent session. Ten minutes. Prevents ten hours of agent folklore.
Closing line in every file
When unsure, ask. When secrets appear, stop. When tests fail, do not claim green. README welcomes humans. AGENTS.md keeps agents from becoming chaos with a commit bit.
Agent PR template line
Pull request template asks: "Did you read AGENTS.md?" with a checkbox. Silly, effective. Glasswing-scale flaw hunting still starts with agents that know the forbidden paths. README welcomes; AGENTS.md gates.
Security agent comments only
Scheduled flaw-finding agents may open issues or PR comments. They may not merge. Glasswing inspiration stops at scrutiny. Humans patch. AGENTS.md says so above the fold beside the India residency notes when relevant.
Residency paragraph
For Pakistan and regional clients, AGENTS.md includes where data may leave the country and which models are allowed. Summit pledges about sovereignty become a paragraph with teeth, not a press quote. Round-tripping hype does not edit that paragraph.
Forbidden paths list
Explicit paths agents may not touch — secrets dirs, production Terraform, payroll exports. AGENTS.md names them. Glasswing energy is welcome on copies of those paths in staging, never on the real ones without a human change window.