Cursor Rules は PR ごとに進化する — ルール肥大化問題と運用の工夫
AI 主体で執筆関連記事（シリーズ）
- Cursor × iOSアプリ開発：クラッシュ修正から CI 構築まで、AIと進めた1日の記録
- AIコーディングで同じ失敗を繰り返さないために：Google Drive API と Xcode Cloud の教訓
- Cursor Rules は PR ごとに進化する（本記事）
はじめに
シリーズ 2 記事で、AI が同じカテゴリの失敗を繰り返す問題に対して、Cursor Rules に制約を蓄積する運用を紹介した。Google Drive API v3 の PATCH 制限や Xcode Cloud のビルド番号など、個別のハマりポイントをルールファイルに書けば、AI は二度と同じ失敗をしない。
今回、60d Memo v1.0 を App Store にリリースするまで開発を続けた結果、ルール運用の次のレイヤーの問題が浮かび上がった。それは:
- ルール自体が肥大化し、読まれなくなるリスク
- ドキュメント（CHANGELOG 等）が陳腐化する現象
- ファイル間で重複・矛盾が生じる
この記事は、リリース直後にこれらの問題をどう発見し、どう運用ルールとして組み込んだかの記録だ。
問題1：CHANGELOG の陳腐化
v1.0 リリース時、CHANGELOG.md を確定しようとしたら衝撃の事実が発覚した。
[Unreleased] セクションに記載されていたのは 4 項目。しかし実際に v1.0 に含まれた機能はタグ、アーカイブ、エクスポート、並列同期、UI 改善など 20 項目以上。
## [Unreleased]
### Added
- Export: Export all memos as JSON or Markdown (#31)
- Feedback: "Send Feedback" link in Settings (#33)
- Sync safety: Rollback on sync failure (#35)
- Testing: 38 unit tests for sync logic (#29)
### Changed
- Refactored sync decision logic into SyncResolver (#29)半年間の開発で積み上げたほとんどの機能が、CHANGELOG に一切書かれていなかった。
原因
CHANGELOG を「リリース時にまとめて書くもの」として扱っていた。PR の作業中に追記する習慣がなく、開発が進むにつれて詳細を忘れる。リリース時に PR 履歴を辿って書こうとしても、もはや網羅できない。
対策：PR ごとの [Unreleased] 更新をルール化
Cursor Rules の github-workflow.mdc に、PR フローの一環として次のステップを追加した:
### 3.5. CHANGELOG の更新
- ユーザー向けに意味のある変更は必ず CHANGELOG.md の
[Unreleased] セクションに追記する
- 追記は PR の作業の一部として同じブランチ上で行う
（リリース時にまとめて書かない）
- カテゴリは Keep a Changelog に従う:
Added / Changed / Fixed / Removed / Deprecated / Security
- Issue 番号を末尾に (#N) で付けると追跡しやすい
#### 追記不要なケース
- テストのみの追加・変更
- 内部リファクタリング（ユーザーに見えない）
- ドキュメント・コメントのみ
- CI/ビルド設定
- todo.md / .cursor/rules/ の更新
迷ったら「このアプリのユーザーがリリースノートで見たいか？」で判断する。さらに PR テンプレートにもチェックリストを追加し、AI が PR 作成時に必ず CHANGELOG 更新を確認するようにした。
## Checklist
- [ ] CHANGELOG.md の [Unreleased] を更新した
（ユーザー向け変更の場合）
- [ ] LP / ブログ側の更新が必要な変更ではない
（必要なら別途対応済み）ポイント: CHANGELOG はリリースの産物ではなく、日々の作業の産物である、という発想の転換。
問題2：ルールファイルの重複と陳腐化
リリース後にルールファイル全体を読み直したところ、次のような問題が見つかった。
具体例：CI の記述が矛盾
project-context.mdc には次の記述があった:
GitHub Actions: main への push と main 向け PR の
ときにビルド・テストを実行するしかし実際の github-workflow.mdc には:
トリガー: main 向け PR のみ
（main への push では実行しない）過去の一時期、push トリガーでも動かしていたが、無料枠の消費を抑えるために PR のみに絞った。そのとき片方のルールしか更新しなかったため、情報が矛盾した状態で放置されていた。
具体例：ローカライズルールが 2 ファイルに散在
swift-conventions.mdc と swiftui-patterns.mdc の両方に「ローカライズ」セクションがあり、書かれている項目が微妙に異なっていた。どちらに書けばよいか分からず、AI も参照に迷う。
対策：定期棚卸しと 1 箇所集約
リリース直後はルールを読み直すモチベーションが高い。これを利用して次を実施した:
- 全ルールファイルを精読し、矛盾・重複をリストアップ
- トピックごとに唯一の記述場所を決める
- 他の場所はポインター（
詳細は XXX を参照）に置き換える
例えばローカライズは swiftui-patterns.mdc に集約し、swift-conventions.mdc からは削除した。
問題3：ルールの肥大化
v1.0 に向けて開発を進める過程で、Cursor Rules に追加されたのは:
- GitHub Flow のルール
- リリースフロー
- CHANGELOG 運用
- 関連リポジトリ（LP 側）との連携
- iOS 17+ の API 採用方針
- クロスプラットフォーム契約（Drive JSON スキーマ）
- SwiftData マイグレーション方針
- Privacy Manifest 対応
- Dark Mode / VoiceOver / Dynamic Type
- ログのプライバシー指定
これだけあると、人間が通読しなくなる。AI は自動で読むが、人間が全体像を把握できないと、新しいルールを追加するときに重複や矛盾を生みやすい。
対策：メタルール
ルールを書く側（＝自分 + AI）が守るべきルールのためのルールを決めた。
| メタルール | 狙い |
|---|---|
| 各ファイル冒頭に TL;DR を入れる | 3 行で内容がわかる状態を保つ |
| トピックごとに「唯一の記述場所」を決める | 重複を生まない |
参照頻度の低いルールは alwaysApply: false に |
常時ロードから外し、該当ファイル編集時のみ参照 |
| 四半期に一度、全ルールを棚卸し | 陳腐化・矛盾を検知する |
| リリース後に必ず見直す | モチベーションが高いタイミングを活用 |
特に最後の「リリース後に見直す」が効く。リリース直後は開発の全体像を俯瞰しやすく、「このルールは不要」「あのルールは追加すべき」という判断がしやすい。
ルールは成長する：シリーズで振り返る
3 本の記事を通じて、Cursor Rules の扱い方は次のように変化してきた。
| 記事 | ルールの位置付け |
|---|---|
| 1. Cursor × iOS 開発 | セットアップ — 初期のコーディング規約を書く |
| 2. 同じ失敗を繰り返さない | 蓄積 — ハマりポイントを見つけ次第追記する |
| 3. PR ごとに進化する（本記事） | 運用 — 肥大化・陳腐化を防ぐ仕組みを組み込む |
最初はルールは「書いて終わり」だと思っていた。しかし実際には、コードベースと同じように成長し、リファクタリングが必要。ルールは静的なドキュメントではなく、生きたコードの一部だ。
個人開発における意義
個人開発者は、チーム開発と違って「ルールを読むメンバー」が基本的に自分しかいない。それでも Cursor Rules に投資する意味は大きい。
1. 未来の自分がユーザー
3 ヶ月後、半年後に同じプロジェクトに戻ったとき、当時の設計判断や API の罠を覚えていられるだろうか。ほぼ無理だ。ルールファイルは未来の自分への申し送りになる。
2. AI への指示が安定する
会話のたびに前提を繰り返し説明する必要がなくなる。「Google Drive API を使うときは」「ローカライズするときは」といった文脈が、自動で AI に伝わる。
3. 新しいツールに移っても資産になる
Cursor Rules は Cursor 固有の仕組みだが、中身はただの Markdown。Claude Code の CLAUDE.md、GitHub Copilot の instructions、将来の別ツールでも、テキストの流用は容易。「AI が読むべき前提条件を蓄積する」という習慣そのものが資産だ。
まとめ
Cursor Rules の運用は 3 段階で成熟する:
- セットアップ — コーディング規約・アーキテクチャを書く
- 蓄積 — 開発中に発見したハマりポイントを追記する
- 運用 — 肥大化・陳腐化・重複を防ぐメタルールを組み込む
3 段階目の「運用」で重要な 3 つの仕組み:
- PR ごとにドキュメント（CHANGELOG 等）を更新する習慣をルール化
- トピックごとに唯一の記述場所を決め、重複を作らない
- 定期棚卸し（リリース後が最適）で陳腐化を検知
ルールは書いた瞬間から腐り始める。腐る前に直す仕組みを組み込んでおけば、プロジェクトが大きくなっても AI が賢く動き続ける。
そしてルールを育て続ける最大の恩恵は、自分がプロジェクトの複雑さに飲み込まれなくなること。個人開発でもコードベースは予想以上に複雑化する。ルールファイルという外部化された記憶装置があれば、その複雑さを AI と分担できる。
シリーズはここで一旦区切りだが、ルール自体はこれからも増え続ける。次の記事を書くときには、また新しい運用課題が見つかっているだろう。