Does Your GitHub README Decide What Coding Agents Recommend? A 2026 Analysis

No study tests README content against coding agent picks directly. Here is what the evidence does show about training data, live retrieval, and project instruction files, plus what dev-tool teams can do about it in 2026.

Key takeaways

  • No published study measures the effect of README content on what coding agents recommend. Anyone claiming a direct causal link is guessing.
  • Agents like Claude Code mostly pick from training-data priors and the stack already in the project, not from reading marketing copy (Amplifying.ai's "What Claude Code Chooses" study).
  • In live-retrieval channels, GitHub is the most cited software domain in ChatGPT, at 1.2% of software citations (Promptwatch Data, Sep 28 to Oct 4, 2026).
  • Coding agents do fetch READMEs, docs and .md files to finish tasks, so a clear README matters at the moment of use, even if it rarely decides the first pick.
  • The most direct lever you control is a per-project instruction file (CLAUDE.md or AGENTS.md), which tells the agent what to use every session.

The question behind the question

If you maintain a developer tool, SDK or API, you have probably wondered whether polishing your README changes what Claude Code, Codex or OpenCode suggests when a developer asks "what should I use for X?"

It is a reasonable thing to wonder. READMEs are the front door of almost every open source project. But I went looking for a study that tests README content against agent recommendations, and I could not find one. So this guide does something more useful than pretending the answer is clean: it separates what is measured, what is plausible, and what is just folklore.

The short version: the README is probably not the deciding factor in the initial pick, but it is not irrelevant either. Which of those two moments you are optimizing for changes what you should do.

Two different moments: choosing and using

A coding agent touches your project at two distinct points.

  1. Choosing. A developer says "add auth" or "I need a queue" and the agent decides which tool to reach for.
  2. Using. The agent has already decided (or the developer told it) and now has to figure out how to install, configure and call the tool correctly.

READMEs and docs matter a lot more in the second moment. The first is dominated by something else.

What actually drives the pick

The best evidence on choosing comes from Amplifying.ai's report "What Claude Code Chooses". The method was simple: prompts contained no tool names, only open questions like "what should I use?", run against existing codebases. The report states an 85% extraction rate and 2,073 primary picks across 20 categories.

A few results stand out:

  • The single most common primary pick was custom/DIY, at 252 of 2,073 (12%). In 12 of 20 categories, Claude Code frequently builds its own solution rather than recommending a product.
  • Authentication was 48% custom/DIY overall, and 100% in Python.
  • Feature flags: LaunchDarkly got 21% of picks against 69% custom/DIY.
  • Where agents did pick third-party tools, they converged on Vercel, PostgreSQL, Stripe, Tailwind CSS, shadcn/ui, pnpm, GitHub Actions, Sentry, Resend and Zustand.
  • All three models tested picked the same top tool in 18 of 20 categories within an ecosystem.
  • Well-known tools can still lose. Redux got 0 primary picks, and Prisma got 0 from Opus 4.6.

The authors are careful about their own limits. The picks reflect training data, RLHF tuning and the system prompt, "not independent evaluation of tool quality." Quality cannot be separated from how often a tool appeared in training data, and some picks are tautological (FastAPI for a FastAPI project).

Notice what is missing from that list of drivers: nothing in it says "the README was persuasive." That fits the framing in the study and in the Hacker News discussion around it, where commenters said agents choose from stack context and training data, not marketing copy. One commenter credited Tailwind's win to training-data structure, since styling and HTML sit together in the same files. That is anecdote, but it is a plausible mechanism.

The Columbia DAPLab post "Your AI Agent Doesn't Care About Your README" makes a related point from the other direction: agents need to know where things live, what rules to follow and how to implement changes, not the high-level overview that fills most READMEs.

Where the README does matter

Live retrieval and citations

Some agents and AI search products do not rely only on memory. They fetch pages. In Promptwatch's data on ChatGPT software prompts (Sep 28 to Oct 4, 2026), github.com was the most cited software domain at 1.2% of all software citations, ahead of learn.microsoft.com at 0.98% and G2 at 0.73%. By source type, docs and help centers earned the largest share at 2.64%, vendor sites 2.01%, review sites and analysts 1.57%, and GitHub 1.2%. You can read the full breakdown in Promptwatch's software citation report.

Two cautions. These are shares of all software citations, not shares of the 23 domains charted, which together earn 7.89%. And the data covers ChatGPT search citations, not what Claude Code or Codex pick. They are different channels. Still, it tells you that a public, crawlable GitHub presence and good docs are part of how AI search sees developer tools.

Favicon of Promptwatch

Promptwatch

Track and optimize your brand visibility in AI search engines
View more
Screenshot of Promptwatch website

Agents fetch READMEs while working

Promptwatch's Markdown in AI Search report (published Feb 19, 2026) measured the last 7 days of citations across ChatGPT, Claude, Perplexity and AI Overviews. HTML was 99.94% of citations and markdown (.md) just 0.05%. So markdown is not how AI search cites you.

But the logs tell a different story for agents. Promptwatch saw a large uptick in docs and site information crawled by Claude's bot (powering Claude Code) and OpenAI's bot (powering Codex), with agents fetching "specific docs, READMEs, and API references to complete coding tasks." The request-path table shows /docs/**/*.md paths fetched by anthropic-claudebot and openai-searchbot, with the top path at 3,241 requests, then 2,870 and 1,934.

That supports a modest claim: agents read READMEs and docs when they need to do something with a tool. A broken or vague README makes your tool harder to use correctly, which can hurt you after the pick, when the agent gives up and writes the thing itself.

The evidence at a glance

ClaimEvidenceStrength
README content decides the initial agent pickNone foundNo evidence
Picks follow training data and project contextAmplifying.ai study (2,073 picks, 20 categories)Good, with stated caveats
GitHub is heavily cited in AI search for softwarePromptwatch Data, 1.2% of software citationsGood, ChatGPT only
Agents fetch READMEs and docs during tasksPromptwatch crawler logs, Markdown reportGood for access, not for influence
Users can override defaults with instruction filesCLAUDE.md and AGENTS.md pattern, HN reportsPractical, anecdotal

The lever you actually control: CLAUDE.md and AGENTS.md

If you are a developer rather than a vendor, the strongest way to change what an agent recommends in your project is not a README at all. It is a per-project instruction file the agent loads every session. Claude Code reads CLAUDE.md, and many other agents read AGENTS.md. Hacker News commenters reported that Claude Code defaults to npm, and that users override this with lines like "use bun" or "uv for python". The course repo behind decodingai's coding-agent tutorial shows both files in use.

A minimal example:

# AGENTS.md

## Stack
- Package manager: pnpm (never npm or yarn)
- ORM: Drizzle
- Tests: Vitest

## Rules
- Use the existing auth module in /lib/auth. Do not write a new one.
- Run `pnpm test` before declaring a task done.

## Where things live
- API routes: /app/api
- Shared types: /lib/types

This lines up with the DAPLab observation: agents benefit from where things live and what rules to follow, not from a project pitch. It is also worth noting that the README and the instruction file serve different readers. The README is for humans who are deciding. The instruction file is for the agent that has already been told what to do.

What tool maintainers should do

The Amplifying report gives vendors two uncomfortable options: become "the primitive it builds on top of," or be clearly better than what an agent can build in 30 seconds. A README cannot fake either. But there are things within your control.

Make the README usable by a machine

  • Put install and quick-start commands near the top, in copy-pasteable code blocks.
  • Be specific. "Follow patterns" tells an agent nothing. "Call client.init({ apiKey }) before any other method" does.
  • State version requirements and breaking changes plainly.
  • Link to API references that are plain HTML or markdown, not content rendered only by client-side JavaScript. Promptwatch's advice is to fix client-side rendering first.

Keep docs crawlable

Promptwatch recommends reserving .md endpoints for developer docs rather than building markdown mirrors of marketing pages. A docs tree that an agent can fetch as clean markdown is cheap to maintain and matches how agents are already requesting content.

Check whether AI bots can actually reach you

If your docs sit behind a CDN rule or a robots.txt that blocks AI user agents, none of the above matters. Promptwatch's free Agentic Readiness Check and its AI crawler URL inspector show which crawlers can read a page, and its AI crawler logs show whether bots such as ClaudeBot or OAI-SearchBot are really fetching your docs and where they hit errors.

Track what agents say about you

Because there is no clean theory here, measurement beats guessing. Run the same open-ended prompts a developer would ("what should I use for feature flags in a Next.js app?") and see whether you appear. Promptwatch tracks coding agents including Codex, Claude Code and OpenCode alongside ChatGPT, Gemini and Perplexity, so you can see whether a README or docs change moves anything. Its prompt tracking lets you watch the answers over time rather than relying on a single spot check. If you want to compare options in the category, the GEO software directory lists the alternatives.

A realistic expectation

Here is my honest read. For widely used categories, the agent's default is baked in long before it sees your repo. Redux getting zero primary picks despite being famous is a good reminder that awareness does not equal selection. If you are a new or niche tool, a better README will not displace the incumbent that the model saw ten thousand times.

What a better README and docs can do is help you win on the margins: being recommended when the developer names a category and the agent has no strong default, being used correctly once picked, and being cited when an AI search product fetches live sources. That is real, just smaller than the headline question implies.

I would also be wary of anyone selling a README formula for agents. The only study in this area explicitly says it cannot separate quality from training frequency. Treat any single-number claim about README impact as unproven.

Checklist

  1. Rewrite vague README guidance into exact commands and call signatures.
  2. Serve docs as crawlable HTML, with .md endpoints for developer docs if you can.
  3. Confirm AI crawlers are not blocked, using the free readiness and crawler checks.
  4. Publish an AGENTS.md or CLAUDE.md in your own projects, and give users a snippet they can paste into theirs that names your tool.
  5. Keep your GitHub presence and review-site profiles current, since both show up in AI search citations.
  6. Re-run open-ended prompts monthly and record whether you are picked, cited, or skipped.

Bottom line

Your README does not decide what coding agents recommend. Training data and project context do most of that work. But agents do read READMEs and docs while building, GitHub is a heavily cited source in AI search, and instruction files give developers a direct way to steer choices. Optimize the README for use, optimize the docs for access, and measure the result instead of assuming it. For deeper data on how AI systems pick and cite sources, see Promptwatch Data.

Share:

© 2026 Surferstack · Find the best Marketing tools for your GTM motion · RSS

Surferstack is an affiliate review site. When you click links to vendors or buy through links on our site, we may earn an affiliate commission at no extra cost to you.

Surferstack is a review website based on user reviews on Reddit and G2, and on publicly available information. We keep everything as up to date as possible, but pricing and features can change. Always confirm the details with the vendor before purchasing.