公開アプリ更新時にREADME・仕様書・画面導線を同時に揃える

はじめに

公開中のWebアプリでは、機能を直すだけでは情報が揃いません。アプリ画面に新しい導線を追加しても、GitHubのREADMEや仕様書、外部の使い方解説ページが古いままだと、利用者にも開発者にも伝わりにくくなります。

この記事では、公開アプリを更新するときに、画面・README・仕様書・外部解説ページを同じタイミングで確認するための運用パターンを整理します。

使う場面

公開中のWebアプリに新機能を追加した
使い方解説ページやリリースノートを追加した
ログイン前後のナビゲーションを変更した
GitHub READMEや仕様書が実装内容とずれてきた
CodexなどのAIエージェントに、公開品質まで含めて作業させたい

今回の実例では、作業時間管理Webアプリ「らくログタスク」で、使い方解説ページ、横長ロゴ、退勤忘れ補正UI、OAuth callback修正を行ったタイミングで、アプリ内導線・README・仕様書も同時に更新しました。

なぜ同時更新が必要か

公開アプリでは、利用者が見る入口が複数あります。

| 入口 | 役割 | |---|---| | アプリ画面 | 実際に操作する場所 | | README | 初見の人が概要やURLを確認する場所 | | 仕様書 | 引き継ぎ、保守、実装判断を確認する場所 | | 使い方解説ページ | 利用者が操作手順を確認する場所 | | リリースノート | 何が変わったかを確認する場所 |

画面だけを更新すると、READMEや仕様書が古いままになります。逆に、READMEだけを更新しても、アプリ内にリンクがなければ利用者は解説ページへ辿りつけません。

更新対象チェックリスト

公開アプリの更新時は、次の観点をまとめて確認します。

| 対象 | 確認内容 | |---|---| | アプリ画面 | 新機能への導線、外部解説ページへの導線があるか | | README | 公開URL、使い方解説、GitHub、公式サイトのリンクが最新か | | 仕様書 | 画面仕様、保存ロジック、制約、バージョン履歴が更新されているか | | ナビゲーション | PCとスマホの両方でリンクへ到達できるか | | OGP/紹介文 | SNSやリンク共有時の表示に違和感がないか | | 検証 | lint/build、必要なら画面操作確認を実施したか |

実装時の進め方

機能修正を実装する。
ログイン前、ログイン後、スマホ表示の導線を確認する。
READMEの関連リンクと機能説明を更新する。
仕様書に画面仕様、DB更新仕様、制約、履歴を追記する。
必要なら使い方解説ページやリリースノートを追加する。
npm run lint と npm run build を実行する。
コミットを機能変更とドキュメント更新で分けるか、必要に応じてまとめる。

READMEに置くとよいリンク

READMEは初見の入口です。公開アプリなら、少なくとも次のリンクはまとまっていた方が使いやすくなります。

## 関連リンク

| 種別 | URL |
|------|-----|
| 公開アプリ | https://example.com |
| 使い方解説ページ | https://example.com/post/howto |
| 開発元公式サイト | https://example.com/ |
| GitHubリポジトリ | https://github.com/owner/repo |

仕様書に残すとよい項目

仕様書は、利用者向けというより保守・引き継ぎの入口です。 READMEよりも実装判断に近い情報を残します。

変更日
対象バージョン
公開URL
外部導線
画面構成
操作フロー
DB更新仕様
既知の制約
検証コマンド
バージョン履歴

AIエージェントに依頼するときの指示例

公開アプリの更新なので、画面実装だけでなく、README、仕様書、使い方解説ページ、リリースノート、アプリ内導線も確認してください。
PCとスマホの両方でリンクへ到達できる前提で、必要なリンクを追加してください。
機密情報や環境変数の実値は公開資料に含めないでください。
最後に lint/build と変更ファイル一覧を報告してください。

注意点

READMEに内部事情を書きすぎると、利用者にとって読みにくくなります。一方で、仕様書に何も残さないと、後で保守する人が実装判断を追えません。

公開向けと保守向けで、書く場所を分けることが重要です。

また、画面リンクを追加したら、スマホメニューからも辿れるか確認します。 PCのヘッダーだけにリンクがある状態だと、スマートフォン利用者が解説ページへ辿れないことがあります。

らくログタスクでの実例

らくログタスクでは、β0.5.6の更新で、使い方ガイドへのリンク追加、退勤忘れ補正UI、OAuth callback修正を行いました。

このとき、アプリ画面だけでなく、README、仕様書、バージョン情報、外部解説ページへの導線を合わせて更新しています。公開アプリでは、このように「機能」「説明」「導線」を同時に揃えることで、利用者にも保守者にも分かりやすい状態を保てます。

まとめ

公開アプリの更新では、コード変更だけでなく、README、仕様書、使い方解説ページ、リリースノート、アプリ内導線を同時に確認します。

特にAIエージェントへ作業を依頼する場合は、「実装だけで終わらせない」ことを明示すると、公開後に情報がずれるリスクを減らせます。