先週、2年ほど手を入れていない旧作のiOSリポジトリを開きました。アプリ自体はまだ動いており、毎日ユーザーが使ってくれています。でも README を見て、少し恥ずかしくなりました。最初のコミット時に書いた3行の概要と、pod install && open .xcworkspace だけが残っていました。
個人開発を長く続けていても、ドキュメントはどうしても後回しになりがちです。コードは少しずつ育てていくのに、それを説明する言葉のほうは放置してしまう。今回あらためて、私は「作る行為」ばかりに気を取られて、「伝える行為」を軽く見ていたのかもしれないと感じました。
Claude Code を使って、その古い README を書き直しました。この記事はその記録です。
README が放置されると何が起きるか
App Store のレビューをClaudeで分析している（App Store レビュー分析の実装パターンを参照）と、ときどき機能の誤解に基づくレビューが見つかります。「このアプリって○○できないの？」という1つ星。実は iOS 16 以降では設定から有効にできる機能なのに、その説明がどこにも書いてありません。README がしっかりしていれば、App Store の説明文にも自然に転記できたはずのことが抜け落ちていました。
GitHub を使って個人開発している方なら、似た経験があるかもしれません。半年前に書いたセットアップ手順が古くなっていて、自分でもビルドに詰まる。コントリビューターを呼びたいが、どこから入ればよいか分からないリポジトリになっています。
Claude Code に何を渡したか
まず、CLAUDE.md に README の品質基準を書きました。Claude Code はこのファイルを読んでプロジェクトの文脈を把握するので、ここに「どんな README が望ましいか」を明示しておくのが効率的です。
# CLAUDE.md（抜粋）
## ドキュメント品質基準
README.md に含めるべきセクション:
- 概要（1〜2文で何ができるアプリかを説明）
- スクリーンショット（実機の画面）
- 動作環境（iOS バージョン・Xcode バージョン）
- セットアップ手順（CocoaPods / SPM どちらを使うか明記）
- 主要な機能リスト（ユーザー目線の言葉で、技術用語は最小限）
- ライセンス
README は技術者だけでなく、App Store の運営者・潜在的なコントリビューター・自分の1年後が
読むと想定して書くこと。次に、Claude Code のカスタムスラッシュコマンドとして .claude/commands/update-readme.md を用意しました。
# .claude/commands/update-readme.md
このリポジトリのコードと既存の README.md を読んで、更新版の README を生成してください。
手順:
1. src/ または Packages/ 以下の構造を把握する
2. 既存の README.md を読む
3. CLAUDE.md の「ドキュメント品質基準」に従い、不足しているセクションを追加する
4. セットアップ手順は最新の Xcode + Swift バージョンに合わせる
5. README.md を上書きする前に、変更内容のサマリーを提示するこのファイルを用意すれば、次回から /project:update-readme の1コマンドで実行できます。
実際に生成されたものと手直し
Claude Code が生成した README は 120 行ほどで、以下の構成になっていました。
# アプリ名
## 概要
## スクリーンショット（プレースホルダー）
## 動作環境
## セットアップ
## 機能
## アーキテクチャ（自動検出）
## テスト実行
## ライセンス
注目したのは「アーキテクチャ」セクションです。指示していないのに、Claude Code がコードを読んでアーキテクチャパターン（MVVM + Combine）を推測して書いてくれていました。ただ、私のアプリは ViewModel の一部を独自に集約するカスタムパターンを使っているため、ここだけ手で修正しました。
手直しは3箇所だけでした。スクリーンショットのパス追加、アーキテクチャの補足、そして App Store URL の追記。それ以外は生成されたものをそのまま使っています。作業時間は15分ほどです。
Before / After 比較
Before（変更前）:
# MyWallpaperApp
壁紙アプリです。
## セットアップ
pod install && open .xcworkspaceAfter（変更後・抜粋）:
# MyWallpaperApp
毎日の気分や季節に合わせて壁紙を変えられる iPhone アプリです。
4K 対応の 2,000 枚以上の壁紙をカテゴリから選んで、
ホーム画面・ロック画面を自動更新できます。
## 動作環境
- iOS 16.0 以上
- Xcode 16.0 以上
- Swift 5.10
## セットアップ
**CocoaPods を使用する場合:**
\`\`\`bash
pod install
open MyWallpaperApp.xcworkspace
\`\`\`
**Swift Package Manager を使用する場合:**
Xcode > File > Add Packages から直接追加できます。
## 主要な機能
- 2,000 枚以上の壁紙（毎月新規追加）
- ホーム画面・ロック画面への自動設定
- お気に入り登録とコレクション機能
- iOS 18 以降: ウィジェット連携に対応この差は大きいと感じます。「セットアップ」が1行から13行になり、iOS 18 のウィジェット対応という2年間書き忘れていた情報も、Claude Code がコードを読んで発見してくれました。
コードベースが大きい場合の注意点
リポジトリが大きくなるほど、Claude Code がコードを読み込む時間がかかります。私が使っている壁紙アプリは Swift ファイルが 200 本以上あるため、/project:update-readme を実行すると最初の解析だけで数分かかることがあります。
この問題には、.claudeignore で不要なファイルを除外するのが効果的です。
# .claudeignore
*.generated.swift
Pods/
*.xcworkspace/
.build/
除外後は読み込み時間が半分以下になりました。
生成された記述は「事実かどうか」を必ず確認する
便利な反面、注意したい点が一つあります。Claude Code はコードから README を組み立てますが、推測で補う箇所が必ず出てきます。先ほどのアーキテクチャ欄がまさにそうで、MVVM と書かれていても、実際には独自の集約レイヤーが挟まっていました。
私自身は生成後、次の3点だけは必ず目視で確認するようにしています。
- 動作環境のバージョン（
project.pbxprojのIPHONEOS_DEPLOYMENT_TARGETやswift-tools-versionと一致するか） - セットアップ手順（CocoaPods か SPM か、実際の依存管理と食い違っていないか）
- 機能リスト（コードには残っているが、すでに無効化した機能を「使える」と書いていないか）
特に最後の項目は見落としがちです。コメントアウトされただけの旧機能を Claude Code が拾い、README に「対応」と書いてしまうことがありました。README は App Store の説明文の下書きにもなるため、ここで誤った機能を書くと、そのまま誤解レビューの火種になります。生成は出発点、検証は自分の仕事、という線引きを持っておくと安心です。
全体を振り返って — まず README から触ってみてください
新機能の実装や既存バグの修正より先に README を整えることで、自分のプロジェクトへの愛着が戻ってきます。特に半年以上手を入れていないリポジトリがある方は、まず Claude Code に /project:update-readme を走らせてみてください。どんな機能がコードに眠っているか、ドキュメントを書く過程で改めて把握できることがあります。
.claude/commands/update-readme.md のテンプレートは、今日のうちに1リポジトリに設定できる分量です。実際に手を動かすことが、最初の一歩になります。