配布資料 11毎日の開発フローマニュアル

題材プロジェクトの実運用（約9ヶ月・5,850コミット）を一般化したランブック。 持ち帰って【 】の箇所を自分のプロジェクトの値に置き換えて使ってください。

1日の基本形はこうなります。

セッション開始 → 着手順決定 → イシューごとの実装ループ（複数周）→ バッチ検証とデプロイ → 完了処理 → セッション終了

手順そのものは平凡だと思います。効いているのは順序ではなく、どこで止まるかのほうです。 各所にフックが仕込んであって、飛ばそうとすると止まります。だから見ていなくても任せられます。

0. 前提となる運用の意味論

このフローは次の合意の上に成立する。導入時にチームで先に決めること:

• すべての作業はイシュー起票から始まる。イシューのない変更は存在しない
• イシューステータスの意味: In Progress =作業中 / In Review =マージ済み・デプロイ待ちキュー / Done =staging 検証完了後のみ
• ブランチは必ず最新 master から fix/*・feature/* を切る。マージは通常マージのみ（squash 禁止）
• 検証の階段（下記 3-5）を全段通るまで「完了」と言わない
• staging デプロイはセッション原則1回のバッチ。イシューごとの逐次デプロイはしない

1. セッション開始（約10分）

1. 記憶の引き継ぎ: 記憶システムの最近更新トピックを個別に全件読み切る（広い曖昧検索はしない）。メモリのインデックスも確認する——記憶ソースが複数ある場合、片方だけの参照は片落ち
2. キューの棚卸し: In Review（デプロイ待ち）と In Progress（中断中）を一覧し、前セッションからの持ち越しを把握する
3. git 状態確認: git checkout master && git pull。前セッションの未コミット残骸がないか git status
4. モードの確認: 今日の指示は「確認して」（調査・計画のみ・編集禁止）か「実行して」（staging 検証まで一気通貫）か。曖昧なら確認する

2. 着手順の決定

1. Bug ラベル最優先。次にユーザーの明示指示、その次にキューの古い順
2. 作業中に見つけた別問題は、その場で直すか即時起票する。「別セッションでやろう」という先送りは禁止——先送りされた問題は消える
3. 規模で進め方を変える: 3ステップ以上はプランモードで計画してから / 5タスク以上はサブエージェント駆動（計画→探索→実装並列→テスト生成→レビュー）/ 大規模仕様変更は exploration 文書から（→ chronicle/02）

3. イシューごとの実装ループ（1イシュー = 1周）

1. イシューを In Progress に変更
2. 原因調査: 原因が判明したら根本原因と修正方針をイシューにコメント（未来の自分と AI のため）
3. ブランチ作成: 必ず最新 master から。

   git checkout master && git pull origin master
   git checkout -b fix/【ISSUE-ID】-【短い説明】
   

4. 実装: バックエンド → フロントエンドの順。既存パターンに合わせ、1PR=1レイヤーを守る（差分200行超で分割を再検討）
5. 検証の階段（順番に全段。飛ばさない）:

   段	コマンド例	合格条件
   型	npx tsc --noEmit	エラーゼロ
   単体	【make test-unit】	全 PASS。金銭・数量ロジックは成分別 assertion
   コンテナ	docker compose build && docker compose ps	ビルド成功・全 healthy
   E2E	【make test-e2e】	該当範囲 PASS（緑表示を鵜呑みにせず対象 spec の実行を確認）
   文書	関連ドキュメント特定	同一コミットで現行仕様を反映（挙動不変時のみ理由付きスキップ可）

6. PR 作成 → イシューに PR を Resources として登録
7. 通常マージ: gh pr merge --merge（squash 禁止）。コンフリクトは解消してからマージ・PR のオープン放置禁止
8. イシューを In Review に変更（= デプロイ待ちキュー投入）。ここで Done にしない

dev ブラウザテストは per-PR 必須ではなく、バッチ単位でまとめてよい（次節）。ただし per-PR ゲート（型 + 単体 + ビルド緑）は必須。

4. バッチ検証とデプロイ（セッション内のマージが一段落した時点で1回）

1. dev 一括ブラウザ検証: キュー内全イシューの観測可能な変更を開発環境（localhost）で検証する。
   • リンク・ボタン遷移のみで到達する（URL 直接入力は導線検証にならない）
   • 目視・スクリーンショット・DOM 引用の3点セットを記録する（grep と computed style だけで完了にしない)
   • 実フローで検証する（トップページが表示された、では不十分。価値が届く最終画面までデータを通す）
   • 空表示の画面は「実装済みでデータが無い」のか「ハリボテ」なのかを必ず判別する
2. 問題なければ staging デプロイ（セッション原則1回）:
   • 非同期起動スクリプト + 完了マーカーの短時間ポーリングで監視（長時間 SSH 監視は禁止 → 事例 #10）
   • DB マイグレーションを含む場合は起動前に手動 DB バックアップ
3. staging 一括ブラウザ検証: dev と同じ基準で全キューイシューを検証
4. 単独デプロイの例外条件（バッチに混ぜない）: DB マイグレーション / 金銭フローのバックエンド変更 / 緊急バグ修正
5. 問題発見時: 該当イシューを In Progress に戻して修正 → 修正 PR をマージしてからバッチに再合流

5. 完了処理（バッチ検証後にまとめて）

1. テスト結果を各イシューにコメント: テスト項目・OK/NG・スクリーンショット要約（dev + staging 両方）
2. 完了コメント: 実装内容・変更ファイルの要約
3. Done 化: staging 検証完了後のみ。Done にする直前にイシューの最新ユーザーコメントを再読する（追加指示の見落とし防止)

6. セッション終了（切り上げ前チェック）

1. In Review キューが残っているなら、デプロイ + 一括テストまで済ませてから切り上げる（キュー放置での持ち越し禁止）
2. 記憶の同期: 専用の同期手順で実行（手動の部分的な保存は取りこぼす → 事例 #02）。引き継ぎ要点は1件・簡潔に
3. CI 消費量の確認: 当月の実行回数を確認し、無料枠の消費感覚を持つ（→ 事例 #03）
4. 未完了イシューのステータスと次アクションをイシューコメントに残す

7. デイリー禁止事項ダイジェスト

• squash マージ / worktree からのブランチ作成 / 引数なしの docker compose up -d（staging・本番）
• URL 直接入力でのブラウザテスト / grep・computed style だけでの完了宣言 / 人間目視なしの UI 変更完了
• 本番デプロイ（ユーザーの明示指示 + 許可時間帯のみ。AI の自己判断では絶対に不可）
• 金銭ロジックへの「最小差分・今夜反映」推奨 / 本番での金銭テスト
• 失敗テストの skip 逃げ / 「別セッションで」への先送り / Done の前倒し

8. 自プロジェクトへのカスタマイズガイド

1. 【 】をすべて自PJの値に置換する（テストコマンド・ブランチ規約・環境名）
2. 自PJの「検証の階段」を定義する——段の数より「全段通るまで完了と言わない」の合意が本体
3. 最初に入れる hook は次の3本（推奨導入順）。文書のルールは hook で強制されて初めて守られる（→ catalog/01_hooks.md）
   1. 本番操作の絶対ガード
   2. マージ前チェックリスト
   3. デプロイ頻度ガード
4. このマニュアル自体をリポジトリに入れ、コード変更でフローが変わったら同一コミットで更新する（→ chronicle/01 陳腐化防止）