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.
- Choosing. A developer says "add auth" or "I need a queue" and the agent decides which tool to reach for.
- 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.

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
| Claim | Evidence | Strength |
|---|---|---|
| README content decides the initial agent pick | None found | No evidence |
| Picks follow training data and project context | Amplifying.ai study (2,073 picks, 20 categories) | Good, with stated caveats |
| GitHub is heavily cited in AI search for software | Promptwatch Data, 1.2% of software citations | Good, ChatGPT only |
| Agents fetch READMEs and docs during tasks | Promptwatch crawler logs, Markdown report | Good for access, not for influence |
| Users can override defaults with instruction files | CLAUDE.md and AGENTS.md pattern, HN reports | Practical, 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
- Rewrite vague README guidance into exact commands and call signatures.
- Serve docs as crawlable HTML, with .md endpoints for developer docs if you can.
- Confirm AI crawlers are not blocked, using the free readiness and crawler checks.
- 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.
- Keep your GitHub presence and review-site profiles current, since both show up in AI search citations.
- 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.