Last week I opened a repository I hadn't touched in about two years. The app still works — users open it every day — but the README stopped me cold. Three lines of description from the initial commit, and a single setup command: pod install && open .xcworkspace. That was it.
Like a lot of solo developers, I consistently prioritize writing code over writing about code. The app grows steadily, but the words that explain it sit untouched. Looking at that README, I realized I'd been treating the act of building as the only thing that mattered, and quietly undervaluing the equally important work of explaining what I'd built.
So I used Claude Code to rewrite the README. Here's what I learned.
When a Neglected README Actually Hurts You
The clearest signal came from App Store reviews. I use Claude to analyze review patterns (see App Store Review Analysis with Claude API), and occasionally I find one-star reviews based on a misunderstanding of what the app can do. "Can't change wallpaper automatically" — except you can, through the iOS Settings page since iOS 16. That feature existed. The README didn't mention it, so neither did the App Store description.
A good README pays forward in ways that are easy to underestimate: it becomes source material for App Store copy, for onboarding potential contributors, and for your own memory six months later when you pick the project back up.
What I Gave Claude Code to Work With
The first step was updating CLAUDE.md with explicit documentation quality standards. Claude Code reads this file to understand the project's context, so spelling out what a good README looks like here saves a lot of back-and-forth.
# CLAUDE.md (excerpt)
## Documentation Standards
README.md must include:
- Summary (1–2 sentences describing what the app does, in user-facing language)
- Screenshots (real device screenshots, not simulator)
- System requirements (iOS version, Xcode version)
- Setup instructions (specify CocoaPods or SPM explicitly)
- Feature list (user-facing language, minimal jargon)
- License
Write the README as if three audiences will read it:
App Store reviewers, potential contributors, and yourself in 12 months.I then created a custom slash command at .claude/commands/update-readme.md:
# .claude/commands/update-readme.md
Read this repository's code and the existing README.md, then generate an updated README.
Steps:
1. Scan the src/ or Packages/ directory structure
2. Read the existing README.md
3. Follow the documentation standards in CLAUDE.md
4. Add any missing sections
5. Update setup instructions to match the current Xcode + Swift version
6. Before overwriting README.md, show a summary of planned changesOnce this file exists, /project:update-readme runs the whole process in one command.
What Got Generated — and What I Fixed
Claude Code produced a 120-line README with the following structure:
# App Name
## Overview
## Screenshots (placeholder paths)
## System Requirements
## Setup
## Features
## Architecture (auto-detected)
## Running Tests
## License
The architecture section surprised me. I hadn't asked for it. Claude Code read the Swift files, inferred the MVVM + Combine pattern, and documented it. The inference was mostly correct — I use a custom aggregation pattern on top of MVVM — so I updated that section by hand. That was one of only three manual edits. The other two were adding the App Store URL and the screenshot paths.
Total time: about 15 minutes. Most of that was the screenshots.
Before / After
Before:
# MyWallpaperApp
A wallpaper app.
## Setup
pod install && open .xcworkspaceAfter (excerpt):
# MyWallpaperApp
An iPhone app for changing your wallpaper to match your mood or the season.
Browse 2,000+ 4K wallpapers by category, with automatic home screen
and lock screen rotation.
## System Requirements
- iOS 16.0 or later
- Xcode 16.0 or later
- Swift 5.10
## Setup
**CocoaPods:**
\`\`\`bash
pod install
open MyWallpaperApp.xcworkspace
\`\`\`
**Swift Package Manager:**
Add packages directly via Xcode > File > Add Packages.
## Features
- 2,000+ wallpapers (new additions monthly)
- Automatic home screen and lock screen updates
- Favorites and collections
- iOS 18+: widget integration supportThat iOS 18 widget integration note is something I had never written down anywhere. Claude Code found it in the code and surfaced it in the documentation automatically.
When the Codebase Is Large
Larger repositories take longer for Claude Code to parse. My wallpaper app has over 200 Swift files, and the initial analysis for /project:update-readme takes a few minutes. The practical fix is .claudeignore:
# .claudeignore
*.generated.swift
Pods/
*.xcworkspace/
.build/
With those exclusions in place, parse time dropped by more than half.
Always Verify Whether the Generated Text Is True
There's one caveat worth keeping in mind. Claude Code assembles the README from your code, but it will always fill some gaps by inference. The architecture section was exactly that: it said MVVM, when in reality there's a custom aggregation layer on top.
After generation, I always check three things by hand:
- System requirement versions (do they match
IPHONEOS_DEPLOYMENT_TARGETandswift-tools-versionin the project?) - Setup instructions (CocoaPods vs. SPM — does it match the actual dependency manager?)
- The feature list (is it claiming a feature that still exists in code but was already disabled?)
That last point is the easy one to miss. I once watched Claude Code pick up an old, commented-out feature and write "supported" in the README. Since the README often becomes the draft for your App Store copy, a wrong feature here is exactly the kind of thing that seeds a misunderstanding review. Treat generation as the starting point and verification as your own job, and you'll stay out of trouble.
A Simple Starting Point
Before adding the next feature, try running Claude Code on an old project's README. The .claude/commands/update-readme.md template above takes about five minutes to set up. What you get back is not just better documentation — it's a catalog of what your codebase actually contains, some of which you may have forgotten.
Pick one repository that's been sitting untouched. Set up the CLAUDE.md standards and the slash command. Run it. The work it takes to fix the three lines Claude gets wrong is far less than the work of writing the whole thing from scratch.