APORON-inc / Mikke-App

共同開発のためのGitHub設計書

作成日 2026-08-03 対象 github.com/APORON-inc/Mikke-App（private） 体制 開発者2名

方針の要約 — mainへの直接pushをやめてPR必須（レビューは任意・セルフマージ可）にし、mainマージで自動デプロイする。CI（PR時の自動ビルド検証）は最初は入れず、必要を感じたら後から足す。組織は無料プランのためブランチ保護が使えないので、リポジトリ同梱のpre-pushフックと運用ルールで実質的に守る。最大のコンフリクト源であるLEARNINGS.mdはアプリ別に分割する。

01現状と、2人開発で起きる事故

2026-08-03時点の調査結果（コミット117件・追跡ファイル707件・14アプリ同居のモノレポ）

現在は「mainへ直接コミット（マージコミットは117件中6件のみ）・CI/CDなし・各自のローカルからwrangler手動デプロイ」という1人前提の運用。2人になると次の事故が構造的に起きる：

直接push同士の衝突

2人が同時にmainへpushすると先を越された側はrejectされ、焦ったforce-pushで相手の作業が消えるリスク。

共有ファイルの恒常コンフリクト

LEARNINGS.mdは全コミットの6割強（74/117）が変更する136KBの単一ファイル。CLAUDE.mdも35コミットが変更。2人が同時にセッションを回すと毎回衝突する。

別アプリの変更混入

過去にY5のコミットへY6の変更が混入した事故あり（git add -A禁止ルールで対処中）。人が増えると発生確率が上がる。

「どれが本番？」問題

手動デプロイは「pushしていないローカルの変更」が本番に上がりうる。相手がpullしても本番と同じコードが手に入らない。

02前提と制約

決定済みの方針と、無料プランの制約

決定事項

制約：組織は無料プラン

確認済みの事実

組織APORON-incは無料プラン（7席）。privateリポジトリではブランチ保護・Rulesets・CODEOWNERSが使えない（API 403で確認済み）。つまり「mainへの直接pushをGitHub側で物理的にブロックする」ことはできない。

本設計は無料のまま、①リポジトリ同梱のpre-pushフック（ローカルでpushを拒否）＋②運用ルールの明文化の2枚で実質的に守る。将来Teamプラン（$4/人/月・7席全員分課金で月$28）に上げれば物理ブロックも有効化できるが、不要メンバーの整理とセットで判断するのが得策。

03ブランチ・PR運用ルール

CONTRIBUTING.mdとして明文化する内容（運用の正本）

04リポジトリに追加するファイル

Mikke-App/
├── .githooks/
│   └── pre-push            # mainへの直接pushをローカルで拒否
├── .github/
│   ├── filters.yml         # アプリ別のパス定義（ci/deploy共用）
│   ├── cf-pages-projects.json # ディレクトリ→Pagesプロジェクト名の対応表
│   └── workflows/
│       └── deploy.yml      # mainマージ時: 変更されたアプリだけ自動デプロイ
├── CONTRIBUTING.md         # §03の運用ルールの正本
├── LEARNINGS/              # §06で分割したアプリ別の学びログ
│   ├── refund.md ・ app.md ・ labs.md …
├── LEARNINGS.md            # 索引だけ残す（既存・縮小）
├── CLAUDE.md               # 書き込み先ルールを更新（既存・修正）
└── mikke-labs/package.json # pnpm.overridesでwrangler 4.116.0固定（既存・修正）

pre-pushフック（ブランチ保護の代替）

#!/usr/bin/env bash
while read -r local_ref local_sha remote_ref remote_sha; do
  if [[ "$remote_ref" == "refs/heads/main" ]]; then
    echo "✗ mainへの直接pushは禁止。PRを作成してください。" >&2
    exit 1
  fi
done

各自がclone後に一度 git config core.hooksPath .githooks を実行すると有効になる（セットアップ手順に明記）。強制力はGitHub側の保護に劣るが、協力し合う2人体制なら事故防止として十分機能する。

05自動デプロイ設計

変更されたアプリだけをデプロイする、モノレポ前提のGitHub Actions

deploy.yml — mainマージ時の自動デプロイ

CI（PR時の自動ビルド検証）は今回は見送り

テストコードが存在しない現状では、CIの実質的な仕事は「npm run build が通るかの確認」だけ。まずは各自の手元ビルド確認（§03のルール3）で代替する。「ビルドが壊れたままマージされる」事故が実際に起きて困り始めたら、deploy.ymlと同じ変更検出の仕組みでci.ymlを1ファイル足すだけで導入できる（無料枠に収まる設計は検討済み）。

設計中に判明した重要な問題

app/ だけでなく mikke-refund/ も自動デプロイできない。両者とも商品データ（public/products.json・detail/）が.gitignore除外で、実行時にfetchする作りのため、まっさらなCIランナーからデプロイすると商品カタログが空の状態で本番に上がる。ローカルの手元にはデータが「復元済み」で存在するから今まで問題にならなかっただけ。

→ この2つは当面deploy.ymlの対象から除外し手動デプロイを継続。恒久対応はPhase 2のR2移行（fetch先を絶対URL化し、distへの同梱前提をなくす）。

06コンフリクト火種の解体 — LEARNINGS.md分割

2人同時セッションでも衝突しない書き込み構造へ

136KBの単一ファイルに全アプリの学びを追記する現行運用は、2人開発では毎回コンフリクトする。次のように分割する：

ブランチ命名ルール（1ブランチ=1アプリ）と合わせると、2人が別アプリを触っている限り同じファイルに触れることが構造的になくなる。

07GitHub / Cloudflare側の設定

コード外・orgのadmin権限で実施する作業

08段階導入プラン

0
今回

安全装置の設置

pre-pushフック・CONTRIBUTING.md・LEARNINGS分割・secrets設定・wranglerバージョン固定。CIは入れない（必要を感じたら後から追加）。デプロイはまだ全アプリ手動のまま。

1
今回

自動デプロイ第一弾

deploy.yml有効化。対象はデータ自己完結のアプリ：mikke-y1, y2, y3, y5, y6, y9, y10 ＋ mikke-labsの10アプリ。y7・y8はPagesプロジェクト未作成のためwrangler pages project createを一度手動実行してから追加。

2
別途

商品データのR2移行 → 全アプリ自動化

app/・mikke-refundの商品データをR2へ移行（fetch先を絶対URL化）し、自動デプロイを解禁。同一KV namespace共有（「ひきつぎ」データ競合リスク）の分離もこのタイミングで検討。

09検証方法

  1. pre-pushフック：mainで空コミット→git pushが拒否されることを確認→リセット
  2. deploy.yml：mikke-y6あたりへの無害な変更でテストPRを作成・マージ→該当アプリだけデプロイされ*.pages.devで反映確認。app/・mikke-refundがデプロイされないことも確認
  3. labs系：mikke-labs/apps/配下1アプリの変更PRで対象アプリのみbuild/deployされることを確認
  4. もう1人の環境：clone→セットアップ手順どおりに進めて再現するか確認

新メンバーのセットアップ手順（CONTRIBUTING.mdに記載）

git clone https://github.com/APORON-inc/Mikke-App.git
cd Mikke-App
git config core.hooksPath .githooks   # mainへの直接push防止フックを有効化
git config core.autocrlf input        # Windows環境は改行コード対策も

10申し送り（本設計の対象外）