AGENTS.md Convention

What is it

AGENTS.md is a plain-text convention file placed at the root of a repository that tells AI coding agents how to behave in that codebase. Think of it as a README written for machines instead of humans: it encodes constraints like "don't write manual-style marketing copy," "always use the project's Result type instead of throwing," or "never touch files under /legacy." Developers discovered that Claude Code, Cursor, Codex, and similar agents will read these files and adjust their output accordingly, so the file becomes a persistent correction layer that stops you re-explaining the same preferences in every prompt.

The business significance is bigger than the file format. AGENTS.md is the visible tip of a shift toward "agent configuration as code" — a new class of developer artifacts (instruction files, tool allowlists, MCP server manifests, permission scopes) that need to be authored, versioned, linted, shared, and audited. Every convention that reaches critical mass creates tooling demand around it: linters for CSS, formatters for JS, policy engines for Kubernetes. AGENTS.md is at the pre-tooling stage, which is exactly where indie developers have historically won.

Why now

Three things converged in late 2025 and early 2026 to make this happen now rather than a year earlier. First, agentic coding tools crossed the usability threshold: Claude Code, Cursor, Windsurf, Codex CLI, and Gemini CLI all became daily drivers for a meaningful slice of professional developers, and each of them independently implemented some form of project-level instruction file. Second, the pain became acute. As agents write a larger share of code, teams hit the same failure mode repeatedly — the agent produces technically correct but stylistically wrong output, and every developer on the team writes a different workaround. A shared file is the obvious fix. Third, the naming converged. The community settled on AGENTS.md as a vendor-neutral name instead of each tool inventing its own (CLAUDE.md, .cursorrules, .windsurfrules), which is the precondition for any ecosystem to form.

The timing signal is the "gstack shares a full Claude Code setup" thread — when practitioners start publishing their entire configuration, you know the practice has moved from individual hack to community norm. That's the moment tooling demand appears. A year ago the user base was too small; a year from now the big vendors will likely ship first-party solutions. The window is now.

Market Evidence

The evidence base is thin and early: 2 independent sources (juejin and GitHub), 2 total mentions, a 100% growth rate, and a stage classification of "nascent." A 100% growth rate on a base of 2 is mathematically meaningless — it just means the term went from 1 mention to 2. The trend score of 62/100 reflects genuine signal, but the opportunity, market, competition, and demand scores all sit at 0/100, meaning the scoring model has essentially no data to work with.

Read this honestly: this is a pre-demand signal, not validated demand. What makes it worth attention anyway is that the two sources are qualitatively different — a Chinese developer community post (juejin) and a GitHub artifact (a shared config) — which suggests organic, cross-community adoption rather than a single influencer pushing a term. The GitHub side is the stronger signal because shared configs are a revealed preference: someone spent effort packaging their setup for others, which people only do when they believe it's valuable.

My position: treat this as a watch-and-probe opportunity, not a build-now opportunity. The correct action today is cheap validation (see Action Plan), not a 3-month build. If mentions cross 50 across 5+ independent sources within 60 days, upgrade to build.

Who's Behind It

No single company owns AGENTS.md — that's the point of the name — but several actors shape its trajectory. Anthropic's Claude Code team popularized the CLAUDE.md pattern and its AGENTS.md compatibility, and Anthropic has the strongest incentive to make agent configuration portable because it lowers switching costs to Claude Code. Cursor (Anysphere) and Windsurf (Cognition) each maintain their own rule-file formats and have historically preferred lock-in, so they are reluctant participants. OpenAI's Codex CLI and Google's Gemini CLI are the swing votes: if both adopt AGENTS.md natively, the convention wins.

On the community side, the "whales" are the high-profile indie developers who publish their full setups — the gstack-style config sharers on GitHub and X. These people are the distribution channel. They have 10k-100k followers, they publish dotfiles, and their recommendations move adoption. There is also a long tail of awesome-list maintainers curating AGENTS.md examples.

Competitive dynamics to watch: the moment one major vendor ships a hosted "agent config registry," the indie window narrows sharply. Until then, the space is unowned.

TAM & Market Size

The buyer is a professional software developer or engineering team lead who uses agentic coding tools daily. Sizing from the bottom: GitHub reported over 100 million developers in 2024, but the relevant slice is far smaller — the population of developers paying $20/month for Cursor or Claude Code. A reasonable estimate is 2-5 million globally as of early 2026, growing fast. Of those, the share who actively maintain agent config files today is maybe 5-10%, i.e., 100k-500k people. That's the early-adopter core.

Willingness to pay is the open question. Individual developers already pay $20-40/month for their AI tools and are reluctant to add a fourth subscription. But teams are different: an engineering manager with 20 developers on agentic tools will pay for anything that reduces review friction, because a 5% productivity loss across 20 engineers dwarfs a $200/month tool cost. So the realistic paid segment is teams, not solo developers.

Price tolerance: $10-15/month per seat for individuals, $20-30/seat/month for teams with admin features, $500-2,000/month for enterprise with audit logs and SSO. The demand score of 0/100 reflects missing data, not absent demand — but it does mean you must validate willingness to pay before building anything paid.

Competitive Landscape

The competitive field is nearly empty, which cuts both ways. Existing players fall into three buckets. First-party vendor features: Claude Code's built-in CLAUDE.md support, Cursor Rules, Windsurf Rules — these are free, bundled, and will always be "good enough" for most users. This is the real competitor, not a startup. Awesome-lists and template repos: free GitHub collections of example AGENTS.md files. Useful, zero monetization, and they establish the "this should be free" expectation. Adjacent tooling: prompt-management and AI-observability tools like LangSmith, PromptLayer, and Braintrust, which handle prompt versioning but ignore repo-level agent config entirely.

The gap: nobody offers linting, validation, drift detection, or team governance for agent config files. Nobody answers "did someone weaken our AGENTS.md in this PR?" or "does this config actually improve agent output, and by how much?" Those are the defensible wedges, because they require measurement infrastructure and team workflows that free templates can't provide.

If Big Tech enters — most likely Anthropic or GitHub shipping native config management — you have roughly 6-12 months of differentiation before the feature becomes table stakes. Compete by owning the cross-vendor story (one config, many agents) and the team workflow story (review, audit, metrics), which single-vendor tools structurally can't tell.

Business Model

Recommendation: freemium SaaS with a usage-metered API tier, targeting teams. Here's why this fits. The free tier (single repo, basic linting, AGENTS.md generation from your existing codebase) is your distribution engine and directly competes with free templates. The paid team tier ($25/seat/month, minimum 3 seats = $75/month) adds shared config libraries, PR-level diff review with drift alerts, and a dashboard showing agent-output quality before/after config changes. The API tier ($0.01/call or $99/month for 50k calls) serves CI pipelines and platform teams who want to enforce config rules automatically.

Pricing rationale: $25/seat sits below the psychological "another AI subscription" threshold while a 3-seat minimum gets you to $75/month, enough for positive unit economics on a self-serve motion. The API tier captures the highest-value customer — the platform engineer who wants to gate merges — without forcing them into seat-based pricing.

12-month forecast, assuming validation succeeds by month 2 and launch by month 3: conservative 40 paying teams averaging $90/month = $3.6k MRR by month 12; base 150 teams averaging $110/month = $16.5k MRR; optimistic 400 teams plus API usage = $50k MRR. CAC estimate: $60-120 via content and community channels (GitHub, X, dev newsletters), payback under 2 months at $90/month ACV. Paid acquisition is not viable at this price point — stay organic.

MVP Blueprint

Build in 5-7 days. Core features only:

1. AGENTS.md generator — paste a GitHub repo URL, get a draft AGENTS.md inferred from the codebase (framework, test runner, style conventions, directory structure). This is the hook; it's also the hardest part, so use a single LLM call with a well-structured prompt over a repo tree summary rather than building AST analysis.
2. Linter — validate a config file against a schema plus opinionated rules (contradictory instructions, references to nonexistent paths, instructions that conflict with detected tooling). Ship ~15 rules.
3. Diff view — show what changed in AGENTS.md between two commits with a plain-English summary of the behavioral impact.
4. Shareable library — public URLs for configs, with a "copy to my repo" button.

Cut everything else: no dashboard, no auth beyond GitHub OAuth, no team seats, no billing on day one. Gate the linter behind a waitlist to measure intent.

Tech stack: Next.js on Vercel, Postgres via Supabase, GitHub App for repo access, one LLM provider (Claude or GPT) behind a thin abstraction so you can swap. Use Stripe only when you have 10 waitlist converts. Launch on GitHub (as an open-source linter + hosted generator), X, and r/ExperiencedDevs. The open-source linter is your distribution; the hosted generator is your product.

Commercial Opportunities

Direction 1: Agent config governance for teams. Product: PR bot that reviews AGENTS.md and rule-file changes, flags drift, and posts a quality score. Target: engineering leads at 20-200 person companies using Cursor/Claude Code. Expected revenue: $2k-15k/month at $25/seat. Why it beats alternatives: it slots into existing PR workflow, requires zero behavior change, and has a clear buyer (the lead who's tired of inconsistent agent output).

Direction 2: Config benchmarking service. Product: measure whether a given AGENTS.md actually improves agent output on your repo, using a fixed task suite. Target: platform teams and AI-forward startups. Revenue: $500-3k/month per customer as a consulting-plus-tool hybrid. Why it beats alternatives: nobody else measures this, and the data you accumulate becomes a moat.

Direction 3: Cross-vendor config compiler. Product: one source of truth that compiles to CLAUDE.md, .cursorrules, AGENTS.md, and Gemini configs. Target: developers using two or more agents. Revenue: $5-10/month individual, $99/month team. Why it beats alternatives: solves a real, growing annoyance and positions you as vendor-neutral, which single vendors can't credibly do.

Product Ideas

🥇 AgentLint — "ESLint for your AGENTS.md." One-line value prop: catch contradictory, stale, and ineffective agent instructions before they cost you a bad PR. Target user: developers already maintaining an AGENTS.md or CLAUDE.md who've been burned by an agent ignoring or misreading it. Why now: the file convention just standardized, so a linter has a stable target; six months from now a vendor will ship this natively, so speed matters. Monetization: free CLI, $25/seat hosted dashboard with PR integration.

🥈 ConfigForge — "Your agent config, compiled for every tool." One-line value prop: write your rules once, sync them to Claude Code, Cursor, Windsurf, and Codex automatically. Target user: developers who switch between two or more agents, which is increasingly common as teams standardize on one but individuals experiment. Why now: format fragmentation is at its peak and will resolve eventually — this is a 12-24 month business, not a decade one, which is fine for an indie. Monetization: $8/month individual, $99/month team with a shared library.

🥉 AgentConfig Bench — "Prove your AGENTS.md actually works." One-line value prop: run a fixed task suite against your repo with and without your config, and see the measured improvement. Target user: platform teams and AI-tooling leads who need to justify config investment. Why now: as agent spend grows, "does this help?" becomes a budget question. Monetization: $500-2,000/month per customer, sold as a service first, productized later.

Priority order reflects time-to-revenue: AgentLint is fastest to build and clearest to explain; ConfigForge has a bigger ceiling but depends on fragmentation persisting; AgentConfig Bench has the highest ACV but the longest sales cycle.

SEO Opportunity

Search volume is near zero today — "AGENTS.md" is a nascent term, and SEO difficulty is effectively 0/100 because nobody is competing. That's an unusual gift: you can own the SERP with three good articles. Target long-tail keywords: "AGENTS.md examples," "AGENTS.md vs CLAUDE.md," "how to write AGENTS.md," "AGENTS.md best practices," and "AGENTS.md linter." Content strategy: publish the definitive reference page plus a curated examples gallery, and make the linter's docs the canonical "how to validate" resource. Rank now while the term is unclaimed; the traffic arrives when the term does.

Risk Assessment

The thesis breaks in three ways. Tech risk: vendors converge on a first-party solution and AGENTS.md becomes a native feature of every tool, leaving no room for third-party tooling. This is the most likely failure mode — Anthropic and GitHub both have the incentive and the distribution. Market risk: the convention fizzles because developers find per-prompt correction good enough, or because agent quality improves to the point where config files matter less. Execution risk: you build a linter for a file format that's still shifting, and spend your MVP budget chasing schema changes.

Cheap validation before building: (1) publish a free AGENTS.md linter as an open-source CLI and count GitHub stars and npm downloads over 30 days — 500 stars or 2k downloads means real demand; (2) post a landing page for the hosted version and measure waitlist conversion; (3) interview 5 developers who maintain a config file and ask what they'd pay to stop maintaining it by hand.

Walk away if: mentions stay under 20 after 60 days, the open-source linter gets under 100 stars in a month, or a major vendor ships native config governance before your MVP launches.

Action Plan

Today: search GitHub for AGENTS.md and CLAUDE.md files, count how many repos have one, and read the top 20 to understand what people actually write. This takes two hours and gives you the real corpus.

Week 1: ship the open-source linter (10 rules, CLI only, no backend) and publish it with a clear README. Post to X, r/ExperiencedDevs, and Hacker News. Stand up a one-page landing site for the hosted version with an email waitlist. Goal: 100 stars and 50 waitlist signups.

Month 1: if the linter clears 300 stars, build the hosted generator and diff view, and start charging $25/seat with a 3-seat minimum. Target 5 paying teams. If it doesn't clear 100 stars, stop and reassess.

Month 3: with 15-20 paying teams, add the PR bot integration and the cross-vendor compiler. Begin publishing the SEO reference content. Target $2k MRR and a clear read on whether the team-governance wedge is holding. If MRR is under $500 by month 3, walk away — the window is too short to grind on a slow start.

Related Terms

MCP (Model Context Protocol) — Anthropic's standard for connecting agents to tools and data; AGENTS.md governs how an agent behaves, MCP governs what it can reach. Together they form the two halves of agent configuration, and a product spanning both is a natural expansion path. CLAUDE.md / .cursorrules — the vendor-specific predecessors that AGENTS.md generalizes; their fragmentation is the core business opportunity. Agentic coding tools — the demand driver; every new user of Claude Code or Cursor is a potential AGENTS.md author. Watch MCP adoption closely: it's the adjacent standard most likely to absorb AGENTS.md tooling.