アプリ開発エンジニアによる、個人開発アプリを1人で回す「管理の仕組み」全部見せます｜フォルダ構成・ドキュメント・Git・CI/CD・HP更新

システム開発の仕事を5年やってきた、アプリ開発エンジニアです。前回の記事では、ぬりえアプリ「いろつな」を企画から公開・運用まで1人で作った話を書きました。
https://note.com/cute_viola332/n/n8a6010659147

ありがたいことに、「AIに何を任せて、何を自分で決めたか」の部分に反応をいただきました。今回はその裏側、1人と AI（Claude Code）でプロジェクトを回すための「管理の仕組み」を、実際のフォルダ構成やファイル名のまま紹介します。

いろつなは、扱うものが意外と多いです。

• iOSアプリ（Flutter）

• サーバー側の処理（Firebase Functions・データベース・ストレージ）

• 公式サイト（WordPress）とブログ（日英で約70本。予約投稿を含む）

• X・Pinterest への投稿、App Store のストア素材

これを1人で、しかも AI にかなりの作業を任せながら回しています。「いろいろ管理しているけど、それなりにうまく回っている」形がどうなっているのかを、順番に書きます。

1. 全体像：2つのGitリポジトリと「Gitに入れない資料」

まず全体です。手元のフォルダは、こうなっています。

IROTSUNA/
├── app/                 … iOSアプリ（Flutter）
├── firebase/            … サーバー処理（Functions）・データベースのルール
├── 運用/                 … 施策ログ・使っているサービス一覧・自動化一覧・ブログ戦略
├── .claude/commands/    … AIに渡す「決まった作業の手順書」（カスタムコマンド）
├── .github/             … CI（GitHub Actions）の設定
├── 仕様書/               … 今のアプリの仕様（01_アプリ概要 〜 06_システム構成）
├── document/            … 設計の背景・戦略・テスト仕様・システムの流れ図
├── 参考資料/             … 開発初期のワイヤーや古い仕様書（判断には使わない）
├── LP/IROTSUNA/         … 公式サイトのWordPressテーマ（別リポジトリ）
├── CLAUDE.md            … AIが最初に読むルールと地図
└── PROGRESS.md          … 進捗（実装済みの一覧と保留中のタスク）

ポイントは2つあります。

1つ目は、リポジトリを2つに分けていることです。 アプリとサーバー処理のリポジトリと、公式サイトのリポジトリです。サイトは push するとそのまま本番に反映されるので、アプリの作業中のコミットが紛れ込まないよう、分けています。

2つ目は、フォルダごとに「どれくらい信じていいか」を決めていることです。 CLAUDE.md に、こんな表を書いています。

• app/・firebase/：コード／いちばん正確な仕様

• 仕様書/：今の仕様／実装の主な参照先

• document/：設計の背景・戦略・分析／最新・参照してよい

• 参考資料/：初期の資料／古い。判断に使わない

AI は、フォルダにある資料を同じ重さで読んでしまいます。開発初期のワイヤーフレームを読んで、今の実装と違う判断をすることが何度かありました。「ここは参考程度」と書いておくだけで、こうしたズレがかなり減りました。

もう1つ、大きな機能を足すときは、資料をサブフォルダに分けています。 デジタルで塗る機能を作ったときは、document/塗り機能/ と 仕様書/塗り機能/ を作りました。うまくいかなかったら、そのフォルダへの参照を外せば元に戻せる、という逃げ道を先に用意しておく考え方です。

2. Gitに入れるもの・入れないもの（許可リスト方式）

.gitignore は「全部無視して、必要なものだけ許可する」書き方にしています。

# いったん全部無視する
*

# 管理したいフォルダだけ許可する
!app/
!app/**
!firebase/
!firebase/**
!.claude/commands/**
!.github/
!.github/**
!運用/
!運用/**

普通は「入れたくないものを並べる」書き方が多いと思います。ただそれだと、新しく作ったファイルが知らないうちにコミットされます。APIキーの入った設定ファイルや、サービスアカウントの鍵などです。

許可リスト方式なら、新しいフォルダを作っても、許可しない限り Git には入りません。AI がファイルをどんどん作る開発では、この「うっかり入らない」安心感が大きいです。

ただし、この書き方には落とし穴があります。入れたいものも、許可し忘れると静かに入らないことです。たとえば CI の設定（.github/）を許可し忘れると、CI は動かないままです。なので、新しいフォルダを Git に入れたいときは許可リストにも足す、というルールを CLAUDE.md に書いています。

逆に、運用/ はあえて Git に入れています。施策ログ（後で書きます）のように、「いつ何を変えたか」を履歴として残したいものだからです。

3. ドキュメントの役割分担

ドキュメントは、役割ごとにファイルを分けています。主なものだけで約20ファイル、合わせて5,000行ほどあります。

• CLAUDE.md：プロジェクトのルールと「どこに何があるか」の地図／機能を足したら必ず直す

• PROGRESS.md：実装済みの一覧と、保留中のタスク／実装済みは絶対に消さない。保留は理由と再開条件まで書く

• 運用/施策ログ.md：戦略をどう変えたか・何をしたか・結果どうなったか／時系列で追記。過去の記録は消さない

• document/SYSTEM_FLOW.md：アプリとサーバーのやり取りの流れ図（Mermaid）／通信や大事な処理を変えたら必ず更新

• document/TEST_CASES.md：テストが何を確かめているか／テストを足したら追記

• 運用/SERVICES.md：使っている外部サービスと、管理画面・キーの置き場所／キーそのものは書かない

• 運用/自動化一覧.md：定期実行・自動で動く処理の一覧／処理を足したら追記

特に効いているのが、「消さない」ログを2つ持っていることです。

PROGRESS.md は「何を作ったか」のログです。完了したことを下に足して積み上げていき、保留にしたものには「なぜ保留か」「何が起きたら再開するか」を書きます。数週間後の自分や AI が読んでも、迷わずに続きから始められます。

施策ログ.md は「何のためにやったか」のログです。最近いちばん大事にしているファイルかもしれません。

### 2026-10-23　1.6.0 が承認／HP を「みんなのぬりえ美術館」に作り替え
**何を変えたか（戦略）** …
**何をしたか** …
**見るもの（結果は「結果の記録」に書く）** …

最初に「施策前の数字」を書き、施策ごとに「戦略の変更・やったこと・何を見るか」を追記します。7日・14日・30日後に数字を見て、結果の表に書き足します。

コードの履歴は Git が残してくれます。でも「なぜその変更をしたのか」「やってみてどうだったのか」は、どこにも残りません。これを残しておくと、AI に「次の施策を考えて」と頼むときにも、過去の判断を踏まえた提案が返ってきます。

AIの「記憶」には、失敗からの教訓だけを書く

Claude Code には、会話をまたいで覚えておくメモの機能があります。ここには同じ失敗をくり返さないための教訓だけを書くようにしています。たとえば、こんなものです。

• アプリのバージョンを上げたら、Xcode が読む設定ファイルも書き換える（書き換えないと、アーカイブしたときに古いビルド番号のままになる。一度これで出し直した）

• App Store の再提出の手順を伝えるときは、審査への返信のタイミングと「提出を取り下げない」注意まで、1つの手順に入れる（取り下げると審査待ちの列の後ろに戻る。一度これで待ち時間が延びた）

コードを読めばわかることは、メモには書きません。メモが増えすぎると、肝心の教訓が埋もれるからです。

4. アプリのバージョンとブランチの管理

バージョン番号

Flutter のバージョンは pubspec.yaml の1行で管理しています。

version: 1.6.0+26

1.6.0 がユーザーに見えるバージョン、+26 がビルド番号です。App Store に同じバージョンを出し直すときは、ビルド番号だけを上げます。1.6.0 は審査中の修正で、ビルド番号を 23 → 24 → 25 → 26 と上げながら、何度か出し直しています。

ブランチ

ブランチは、バージョンごとに切っています。

• dev-1.7.0 など：次のバージョンの開発

• release-1.6.0：審査に出しているバージョンの修正だけを入れる

• prod/v1.3.0 など：1.3.0 までの、ストアに出した時点を残す旧方式（今はタグに置き換え）

• feature/〇〇・fix/〇〇：大きめの機能や、切り出したい修正

• main：ストアに出ている版。承認されたら release ブランチをマージする。直接はコミットしない（運用記録の追記だけ例外）

• タグ vX.Y.Z：承認されたビルドのコミットに付ける（例：v1.6.0 ＝ 1.6.0+26）

1.6.0 の審査を待っている間に、1.7.0 の開発も進めたい、ということがよくあります。そのときは git worktree で、同じリポジトリを2つのフォルダに同時に開いています。

IROTSUNA/          … 審査中は release-1.6.0（修正用）、承認後は main（ストアに出ている版）
IROTSUNA-dev170/   … dev-1.7.0（次の開発）

ブランチを切り替えなくていいので、「審査の指摘に今すぐ対応したい」ときも、開発中の作業をしまわずに済みます。release 側で直したものは、その都度 dev 側にマージして追いつかせています。

コミットメッセージ

コミットメッセージは「種類(場所): 何をしたか」を日本語で書いています。

feat(coloring): バケツ塗りを「領域マップ」方式にして、細い線からの漏れと白い塗り残しをなくす
fix(startup): 起動時にスプラッシュ画面で止まることがある問題を修正
chore(release): 起動時の修正を含めて再提出用に 1.6.0+26 に変更
docs(ops): 1.6.0 の承認と HP の美術館リニューアルを施策ログに記録

ほとんど AI が書いていますが、形をそろえておくと、git log を眺めるだけで「このバージョンで何が変わったか」がわかります。ストアの「新機能」の文章も、ここから作れます。

リリースだけは人の手で

AI に頼むのはバージョン番号を上げるところまでです。ビルド、アーカイブ、App Store への提出は自分でやります。審査に出すものは、最後に自分の目で確かめたいからです。CLAUDE.md にも「ビルドはしない」と書いてあります。

承認されたあとの手順も、1つのコマンドに

App Store で承認されたあとにやることも、更新漏れがないように決めています。/release-done というカスタムコマンドにして、承認されたら必ずこれを実行します。

1. 状態を確かめる（ビルド番号が承認されたものと同じか、CI が成功しているか）

2. 承認されたビルドのコミットに vX.Y.Z のタグを付ける

3. release ブランチを main にマージして push し、main の CI が通るのを確認する

4. 次の開発ブランチに main をマージし、そちらの CI も確認する

5. PROGRESS.md と施策ログに記録する

6. 何をしたか報告する

手順の途中で問題が見つかったら、そこで止まって報告する決まりです。ビルドと提出は、ここでも人がやります。

あわせて CLAUDE.md には、こんなルールも書いています。

• push したら、CI の結果を確認してから「完了」と報告する

• 手元の Flutter を上げたら、CI の版も同じ日に上げる（版が違うと、手元では通るのに CI だけ落ちる）

• パッケージの版を固定する pubspec.lock も Git に入れる（入れないと、CI が毎回新しい版を取ってきて結果が変わる）

• 新しいフォルダを Git に入れたいときは、.gitignore の許可リストに足す

AI は CLAUDE.md を毎回読むので、ここに書いておけば、次に同じ場面が来たときに思い出してくれます。

5. CI/CD：何を自動にして、何を手で残しているか

アプリ：GitHub Actions でテストを回す

アプリのリポジトリでは、GitHub Actions で次の順番にチェックしています。

1. 依存関係のインストール

2. 整形のチェック（dart format。自動生成ファイルは除く）

3. コード生成（データモデルなどの自動生成ファイル）

4. 静的解析（flutter analyze）

5. テスト（flutter test）

CI は、main・dev-*・release-*・feature/〇〇・fix/〇〇 のどのブランチに push しても動きます。サーバー処理（Firebase Functions）のビルドとテストも、別のジョブとして同時に回します。

Flutter の版は、手元と同じ版に固定しています。版が違うと整形や解析の結果が変わり、「手元では通るのに CI だけ落ちる」が起きるからです。静的解析は、「こう書くとより良い」程度の情報では落とさず、警告とエラーがあれば止める設定にしています。

さらに手元にも、Git の pre-push フックを入れています。push する前に flutter test が走り、1件でも失敗すると push が止まります。CI は「全部のブランチで、同じ条件でもう一度確かめる」役割です。

テストは今、30ファイル・約230件あります。サーバー側の処理にもテストがあり、こちらは Node.js のテストランナーで回しています。

開発のルールとして、実装の前にテストを書くことを徹底しています。テストを書いて失敗を確認し、通る最小限のコードを書いて、整理してコミットする。この一連の流れは /basic-test というカスタムコマンドにして、毎回同じ手順で回るようにしました。

本番に触れずに確認する：エミュレーター

Firebase には、データベースや認証を手元で動かせるエミュレーターがあります。これに、テスト用のデータを入れるスクリプトを組み合わせています。

firebase emulators:start --only auth,firestore,functions,storage
node functions/scripts/seed-emulator.js
flutter run --dart-define=USE_EMULATOR=true

最後のオプションを付けて起動すると、アプリはエミュレーターにつながり、デモ用のユーザーで自動でログインします。本番のデータには一切触れません。

このしくみの上で、画面を順番に操作する自動テスト（integration test）も動かしています。App Store のスクリーンショットや、X に載せる「塗っている様子」の動画も、このテストで撮っています。見た目を直したら撮り直す、ができるようになったのは大きかったです。

サーバー処理のデプロイは手動で、関数ごとに

サーバー側（Firebase Functions）は、自動デプロイにしていません。直した関数だけを指定して、手でデプロイしています。

firebase deploy --only functions:generateColoring

関数が20本以上あるので、全部まとめて出すと、関係ないところまで巻き込みます。影響範囲を小さくしたいので、あえて手動にしています。

本番のデータを直す作業（データの移行など）は、スクリプトにして firebase/functions/scripts/ に残しています。本番に入るための権限は、作業のたびにログインして、終わったら取り消すようにしています。

6. HP（公式サイト）とブログの更新

push したら1〜2分で本番に出る

公式サイトは WordPress のテーマを自作していて、別のリポジトリで管理しています。main ブランチに push すると、GitHub Actions が動いてサーバーに反映されます。

流れはこうです。

1. GitHub の Secrets に入れておいた SSH の鍵で、サーバーに接続する

2. rsync で、テーマのフォルダをサーバーと同じ状態にそろえる

3. ブログの原稿や作業用のスクリプトは除外する

push してから1〜2分で本番に出ます。サーバーの管理画面にログインしてファイルを上げる、という作業はもうしていません。

少し工夫しているのは、CSS と JavaScript のバージョン番号を、ファイルを最後に更新した時刻にしていることです。こうすると、ファイルを直すたびに読み込み先の URL が変わるので、ブラウザやサーバーのキャッシュで古い見た目が残る、ということが起きません。

SEO の設定（タイトル・説明文・SNS 用の画像・構造化データ）は、基本的にテーマの functions.php にまとめています（無料ぬりえのページだけ、各テンプレートで上書き）。プラグインに分散させると、どこで何が出ているのか追えなくなったからです。

ブログ記事は「フォルダ単位」で Git に入れる

ブログ記事は、1本ごとにフォルダを作っています。

記事/
├── 001-ぬりえの効果/
│   ├── article.html   … 本文
│   ├── meta.json      … タイトル・キーワード・公開日・状態（ready / done）
│   └── images/        … 記事の画像3枚
└── 001en-benefits-of-adult-coloring/   … 英語版（日本語版の翌日に公開）

記事を作るときは /blog-article で、テーマ・公開日の提案から、本文と画像の作成まで進めます。日本語版と英語版のペアごとに AI のエージェントを分けて立ち上げているのは、1つに何本も書かせると、後の記事ほど文章が似てくるからです。

アップロードは /blog-upload です。画像の抜けをチェックしてから、自分が確認して、WordPress の API で予約投稿します。投稿が終わると meta.json の状態が done になり、投稿の記録ファイルに1行足されます。

本当は GitHub Actions から自動で投稿したかったのですが、サーバーのファイアウォールで外からの接続が止められるため、投稿だけは手元の PC から実行しています。全部をクラウドで自動化できなくても、投稿の前に人が確認する1ステップを挟む形の方が、結果的に安心して回せています。

公開前の見た目チェック

最近 HP を大きく作り替えたときは、公開前に、ヘッドレスの Chrome でページを自動撮影して確認しました。PC とスマホ、英語表示、「動きを減らす」設定の4パターンです。

崩れていないことを確かめてから push するので、作り替えのような大きな変更でも、安心して本番に出せました。

7. 1つの作業が終わるまでの流れ

ここまでの仕組みが、1つの作業の中でどうつながっているかをまとめます。たとえば「塗り絵の機能の不具合を直す」場合です。

1. 自分が、何を直したいかを短く伝える

2. AI がテストを書いて、失敗することを確かめる

3. 直して、新しいテストも、既存のテスト全部も通ることを確かめる

4. 必要ならエミュレーターとシミュレーターで、実際に触って確かめる

5. コミットして push する（push の前にフックでテストが走る）。push したら CI の結果を確かめる

6. PROGRESS.md に完了を追記する（通信の流れを変えたら SYSTEM_FLOW.md の図も、テストを足したら TEST_CASES.md も）

7. 施策として意味のある変更なら、施策ログにも書く

8. ストアに出す時期なら、バージョン番号を上げる。ビルドと提出は自分でやる

手順の 6 と 7、「記録を更新する」まで含めて1つの作業、と CLAUDE.md に書いておくのがコツです。記録を後でまとめて書こうとすると、だいたい忘れます。

8. 回してみてわかったこと

置き場所と信頼度を決めると、AI も自分も迷わない。 資料が増えるほど、「どれが今の正解か」がわからなくなります。フォルダの役割と信頼度を1枚の表にしておくだけで、ずいぶん楽になりました。

「消さないログ」は2種類いる。 何を作ったか（PROGRESS.md）と、何のためにやって、結果どうだったか（施策ログ）。前者だけだと、作ることが目的になります。後者があると、「この施策は効いたのか」を数字で振り返れます。

自動にしない部分を、先に決めておく。 アプリのビルドと審査への提出、本番データの変更、外に出す言葉の最終確認。ここは人が見る、と決めておくと、それ以外は安心して AI に任せられます。

仕組みは「動いているのを確かめる」までが仕組み。設定ファイルがあることと、それが動いていることは別です。今は push のたびに、CI の結果を見てから完了にしています。

失敗は、その日のうちにルールにする。 ビルド番号の件も、再提出の件も、その日のうちに AI のメモに書きました。同じ失敗は今のところくり返していません。

1人の開発では、作ることより「続けること」の方が難しいと感じています。仕組みを整えるのは地味ですが、1人でもここまで回せる、という実感があります。

アプリ開発や業務の自動化（スプレッドシートの転記、問い合わせ対応、LINE の自動応答など）のご相談は、ココナラで受けています。「これって作れる？」「自動化できる？」という方は、気軽にどうぞ。

https://coconala.com/users/2677482

いろつな（App Store）: https://apps.apple.com/app/id6782540224
公式サイト: https://irotsuna.com