8 Rules for AGENTS.md: Cutting Token Waste and AI Over-Engineering

X postAYiResource

Drawing from experience across approximately 60 billion processed tokens, Marcos Hernanz from Vercel's Next.js team compiled eight fundamental rules for AGENTS.md. The configuration steers coding agents toward writing pragmatic, minimal code instead of introducing superfluous abstractions and unnecessary dependencies.

Key points

  1. Agents should delete obsolete code directly, avoiding backward compatibility layers, migrations, and fallback logic.
  2. Choose the simplest implementation that satisfies current requirements without speculative abstractions or redundant configuration.
  3. Build systems incrementally: complete a minimal end-to-end working version before expanding, rather than tearing down working code for unbuilt complexity.
  4. Inspect existing project dependencies first and lean on mature libraries and proven patterns instead of reinventing solutions.
  5. Development tools like Cursor, Claude Code, Codex, and Windsurf read AGENTS.md from the repository root automatically.
  6. Crucial caveat: the strict rule against backward compatibility is suited for side projects and prototypes; running it in production poses serious risks to databases and live data.

Why it matters

AI coding agents frequently over-engineer simple solutions with excessive layers and redundant packages. This inflates context tokens and leads to protracted revision loops. A repository-level instruction set curbs verbosity and architectural drift before any code is generated.

Analysis

The rules directly tackle common model failure modes. Large language models tend to default to defensive programming by wrapping old logic in compatibility bridges. Enforcing strict simplicity significantly lowers token usage and maintenance burden. However, as noted in the author's cautionary tale regarding database tables, deploying aggressive rulesets in live production environments without safety boundaries introduces severe operational risks.

Original post

AYi

@AYi_AInotes · 4 August 2026

简直就是省Token焚决！！！ Vercel Next.js团队的老哥，烧了大约60B tokens，总结出一份AGENTS.md，核心就8条规则。 60B tokens什么概念？大概六位数美元。 这8条规则的本质就一句话：让你的AI编程Agent别像个实习生什么都想自己造，要像个干了十年的老油条一样写代码。 直接上规则： 1. t.co/xMZNDQuCjt t.co/IReVC0tw4J

2.9k likes52 replies5k bookmarks403.3k views

View on X
Selected replies (2)
  • @lliu54827 @AYi_AInotes 这8条我读完第一条就想笑，我天天用Claude处理东西最大的教训就是它default会加兼容层，不是模型笨，是它猜更安全的路径就是保留旧代码。 我CLAUDE.md里加了一条不留向后兼容，少写至少三成废代码。 但生产环境那条警告是真的，我自己也差点让它动了不该动的配置文件。
  • @JaxsonZhang2293 @AYi_AInotes 最打动我的是第2条和第5条：宁可先用最简单实现，也别预防性抽象。延伸一点：规则写进 AGENTS.md 只是开始，定期回头删掉过时规则同样重要，不然文件本身又变成新包袱。已收藏。

Mentioned links

Summary generated by AI (Gemini 3.8 Flash, 27 September 2026). It may contain errors – the original source is authoritative.

Related entries

Similar in content, found by the AI search.

  • Repository:DietrichGebert/ponytail

    Ponytail: Agent Skill to Prevent Over-Engineering in AI Coding

    Ponytail is an open-source tool and agent skill designed to enforce extreme minimalism and YAGNI principles in AI coding assistants, significantly reducing bloated code, token costs, and turnaround times.

    127.1kstarsJavaScript

    AI & LLMs· Tool

  • Link:DietrichGebert

    ponytail: A Minimalist Ruleset for AI Coding Agents

    ponytail is a ruleset and plugin designed to make AI coding agents write the minimum viable code. It counters over-engineering by prioritising standard libraries, native platform features, and existing utilities.

    AI & LLMs· Tool

  • X post:Miles Cranmer

    Ponytail: Agent Skill Against Overengineered AI Code

    Miles Cranmer highlights the open-source repository 'ponytail' as an effective prompt-based skill to prevent AI coding agents from generating bloated solutions. The project guides agents towards minimal code and native platform features instead of redundant dependencies.

    1.5kbookmarks47.5kviews

    AI & LLMs· Tool

  • Repository:GonChen/real-engineering-prompt

    Real Engineering Prompt: Minimal Behavioural Directives for Coding Agents

    This open-source project offers a concise instruction template (AGENTS.md) designed to bind modern coding agents to core engineering practices like minimal complexity, scoped modifications, and evidence-backed verification.

    4stars

    AI & LLMs· Resource

  • Repository:multica-ai/andrej-karpathy-skills

    CLAUDE.md Ruleset Based on Andrej Karpathy's LLM Coding Observations

    This repository provides a single CLAUDE.md configuration file designed to improve Claude Code's performance. It translates Andrej Karpathy's observations on common LLM coding pitfalls into four actionable instructions to reduce overengineering and unintended code edits.

    210.3kstars

    AI & LLMs· Resource

Back to the knowledge base

Let's talk about your project

Get in touch

Locations

  • Mattersburg
    Johann Nepomuk Bergerstraße 7/2/14
    7210 Mattersburg, Austria
  • Vienna
    Ungargasse 64-66/3/404
    1030 Wien, Austria

Parts of this content were created with the assistance of AI.