Vercel CEO Guillermo Rauch wants human-written READMEs and agent-ready docs
His proposal separates public explanations for developers from denser instructions for coding agents, with human editing as the quality bar.
By RuntimeWire Staff · Published
Primary source: X
Why it matters
As coding agents become users of developer tools, documentation has to support both fast execution and human understanding. Rauch's proposal makes audience, rather than AI authorship, the organizing choice.
Guillermo Rauch (@rauchg), Vercel's founder and CEO, argues that public READMEs should be written for people while internal documentation can use more utilitarian language for coding agents. He laid out the distinction on October 4th.
Rauch learned English by reading software manuals and taught himself web development at 11, according to GV's profile. His open-source work helped shape Vercel, and he co-created Next.js, a framework introduced in a 2016 Vercel post. His proposal makes audience a design choice: a README can explain why a project exists and how a person should approach it; agent-facing notes can prioritize concise, actionable directions.
A person learning a framework may need context, examples and a sequence that builds understanding. An agent working inside a codebase may need the relevant files, constraints and commands without the tutorial's narrative. One document can try to do both jobs, but optimizing for one reader can make it slower for the other.
Rauch made that tradeoff explicit in replies. He agreed with Fatih Kadir Akin that some "tutorials for humans" could be inefficient for agents, which should go straight to source code. He also endorsed "human-edited" as a useful distinction as models improve at writing, and said producing this kind of material "requires heavy editing" in a later reply.
Editing sets a boundary for the proposal. If a model can draft clear prose, authorship alone says little about whether a document works. Authors still need to decide what belongs in it, check that instructions match the code, and make the intended reader's next step obvious. Rauch's framing keeps human judgment in the process, even when the final text is terse enough to suit an agent.
A familiar Vercel problem, with a new reader
Vercel's early product, then called now, was built around reducing the complexity of getting web applications online. In its 2020 account of the ZEIT-to-Vercel rebrand, the company described its original goal as letting developers deploy apps with a single command while handling details such as routing and SSL. Rauch's documentation argument follows a similar principle: remove material that does not help the intended user complete the task.
Vercel's 2016 Next.js announcement introduced the framework's principles in a blog post and pointed readers to the README to learn how to use it. That separates project rationale from operating instructions, though it does not establish that Vercel has adopted the formal human-facing and agent-facing split Rauch is now discussing.
The timing also fits Vercel's broader public positioning around agents. In its June 30th recap of Vercel Ship 2026, the company described infrastructure designed for agents and positioned Vercel as a place where coding agents can deploy software. That is Vercel's own framing, and Rauch's thread is an individual argument rather than a company policy announcement. Still, documentation is one place where an agent-oriented platform meets the code it is meant to operate.
For teams maintaining libraries and developer platforms, a second documentation track could make agent tasks more direct. It also creates upkeep: each set of instructions must stay aligned with the code, and maintainers need to know which material should change when behavior changes. Sending agents to source code can avoid duplicating some explanations, as Rauch suggests, but source code still needs enough structure for an agent to identify the right file and interpret it correctly.
Rauch's rule: write for the reader in front of the document. The test is whether an agent can act accurately from the shorter instructions while a developer can still understand the choices and concepts behind the tool. Keeping those jobs separate may help; human editing remains the work that makes either version trustworthy.