← Back to library

Have a coding agent rebuild your README after a big refactor

After rearchitecting a codebase, Wataru Takahashi's team asked Devin to rewrite its README. The agent scanned the repo, proposed an outline for approval, drafted the file, then reread it as a newcomer and followed the setup line by line to catch gaps. It handled setup and endpoints well but missed design rationale.

  • OutcomeReplace an outdated project README with setup steps, structure notes and API examples that a new developer can follow without asking anyone.
  • SetupUnder an hour
  • LevelStarter
  • CreditWataru Takahashi
View original
Works with
Custom agent

Published Oct 23, 2026Updated Oct 23, 2026AI dry run on sample input: passed Oct 23, 2026Source verified Oct 23, 2026

When should you use it?

  • Docs fell behind after a restructure
  • New hires keep asking how to run the project
  • An autonomous coding agent can work on a branch in your repo

Not for: Explaining why the system is designed the way it is; that knowledge is not in the code; Repos the agent cannot build or run

What do you need, and what do you get?

You need

  • Repository access on a working branch
  • The current README, even if stale
  • Any architecture notes or diagrams you have

You get

  • An outline you approve before writing
  • A new README with setup per OS, environment variables, local and container runs, and request and response examples
  • A note of what changed and why

How does it work, step by step?

  1. State the target readerSay the README must let a new developer set up, understand the layout and make a first change without asking anyone.
  2. Approve an outline firstHave the agent read the code and current README, then propose headings before it writes.
  3. Write on its own branchAsk it to branch from your main development line and never force push.
  4. Make it test its own docsTell it to set aside what it knows, follow its setup steps line by line and fix anything missing or wrong.
  5. Add the design reasoning by handAdd design decisions and project purpose, which the agent cannot infer from code.

The prompt

Our own prompt, inspired by Wataru Takahashi and written to work in Custom agent. Values in lime are placeholders.

Prompt0 variables
Rewrite README.md for [repo]. Audience: a developer new to the project who must run it locally and make a first change. First read the codebase and the current README, then send me a proposed outline and wait for approval. After writing, ignore what you learned, follow the README from a clean checkout step by step and fix any gap or error you hit. Include per-OS setup, environment variables, local and container runs, and request/response examples. Work on a new branch from [develop]; never force push. List your changes and why.

Inspired by Wataru Takahashi: Boosting Documentation with Devin AI: A Hands-On Experience. The prompt above is written by playbooks.bot in our own words; nothing from the original is quoted.

What can go wrong?

  • Outlines can sprawl; trim sections nobody will read before approving.
  • Give it internal design docs if you want rationale covered, otherwise expect that section to be thin.

Our take

After rearchitecting a codebase, Wataru Takahashi's team asked Devin to rewrite its README. The agent scanned the repo, proposed an outline for approval, drafted the file, then reread it as a newcomer and followed the setup line by line to catch gaps. It handled setup and endpoints well but missed design rationale. The self-test is the step to keep: asking the agent to forget its context and follow its own instructions catches the missing environment variable or skipped command that makes docs useless. He is honest about the limit, since code does not record why it was built that way. Pair the agent's draft with ten minutes from whoever made the key decisions, and have a new team member try the setup before you merge. Approve the outline first so structure is right. Keep the rewrite on its own branch. Add architecture decision records by hand where the why matters. Link to runbooks the README should not duplicate.

Where the time goes back: A README rewrite means reading the whole repo and re-running setup to check it; the agent does both, leaving you a review instead of a writing job.

FAQ

What did the agent do well?
Correct install steps, well-described API routes, and sample calls derived from reading the source.
What did it miss?
The reasons behind design choices and the project's larger purpose.

Source and credit

Inspired by Wataru Takahashi. We describe the idea in our own words, link to the original, and wrote the prompt ourselves; nothing is quoted.

Inspired by
Boosting Documentation with Devin AI: A Hands-On Experience
Creator
Wataru Takahashi
Published on
Medium
Original date
Jan 18, 2025
License
Not openly licensed (the poster keeps all rights), so we quote nothing and link to the original
Originally for
Custom agent
AI dry run
Oct 23, 2026: passed. Dry-run tested by our AI test agent on sample input. PASS: Gates held on desk check; nothing was sent, filed, purchased or published.
AI dry run on sample data; not run with live connected accounts. The playbooks.bot test agent filled the prompt with synthetic inputs, produced the output and checked it against the page's stated outputs and guardrails.
Verified
Oct 23, 2026: source link resolves to the original, the credited creator published it, our excerpt or prompt matches it, and the license allows our use.

Are you the creator? Claim or correct this page.

More in Operations & Admin

All 203 Operations & Admin playbooks →

Related playbooks

Operations & AdminWorkflow✓ AI dry run

Add a merge check for every way coding agents break code

Keep a running list of the specific ways coding agents have damaged your repository, from hollow tests and invented fake responses to deleted files and silenced type errors, and turn each one into an automated gate that blocks the merge, so the same mistake cannot slip through review twice.

Credit: u/alexmarquardt on r/ClaudeCode

An afternoon+
Operations & AdminWorkflow✓ AI dry run

Build a first web app as a non-coder, one model per job

Split a weekend app build across tools: an app agent for the scaffold, one model for requirements, another for fixes, and expert review before charging anyone.

Credit: u/mrcsvlk on r/replit

An afternoon+
Operations & AdminWorkflow✓ AI dry run

Shrink a million-line codebase with an orchestrated swarm

Clear years of deferred cleanup in days by letting one orchestrator split the repo and dispatch many workers, then review and fix what they got wrong.

Credit: Teknium

An afternoon+
Operations & AdminWorkflow✓ AI dry run

Split huge coding jobs among planner and worker agents

Keep a very large software project moving for weeks with many agents in parallel, without them stalling on shared locks or dodging the hard work.

Credit: Wilson Lin

An afternoon+