workflow.md

開発の進め方

SeeFT で、課題に気づいてから本番に反映するまでの仕事の進め方と、その途中の決まりをまとめた文書です。

ほかの文書との分担は次のとおりです。

文書	書いてあること
onboarding.md	使っている技術と、その学び方
AGENTS.md	コードの書き方の規約
この文書	仕事の進め方（issue・ブランチ・PR・レビュー・マージ・割り振り）
docs/operations/	技大祭の運用と本番の手順
docs/decisions/	なぜそう決めたか（ADR）

この文書の決まりは、チームの約束事です。システムの作りには関わらず、すぐに変えられるので、ADR にはせず、決まりの横に理由を短く書いています。変えたいときは、この文書を直す PR を出し、なぜ変えるかを本文に書いてください。

---

1. 全体の流れ

課題に気づく → issue を立てる → 割り振る → ブランチを切る → 実装する
  → 自分で点検する → PR を出す → レビュー → マージ → 本番に反映する
                                  （設計や運用の方針を選んだら ADR を書く）

どの変更も、この流れで進めます。

2. issue

• どんな変更も issue から始めます。 コードだけでなく、AGENTS.md・README・設定ファイルのような文書の変更も同じです。目的が issue に、議論と確認が PR に残り、CodeRabbit のレビューも受けられるためです。とくに AGENTS.md は規約そのものなので、変えた理由が残らないと、後から変えてよいかを判断できません。

• テンプレートは .github/ISSUE_TEMPLATE/issue-template.md です。目的（なぜやるか）を必ず書きます。

• コードを引用するときは、言語を指定したコードブロックに入れます。「L123: コード」のような箇条書きだと、行番号とコードと説明の境目が見えにくくなるためです。ファイル名と行番号を1つだけ示すなら、インラインのバッククォートで構いません。

  **ファイル**: `api/lib/usecase/shift_usecase.go`
  
  ```go
  // 準々備日は45th(yearID=45)のみ対応
  ```

• 公開リポジトリなので、書かないものがあります。書いたものは、消しても履歴に残ります。個人名は役職で書きます。スプレッドシートや Drive の ID、サーバーの IP、委員会の中だけで通じる言葉の意味も書きません。これらは、引き継ぎに要る人だけが読める非公開の資料で渡します。

• セキュリティの問題は、公開の issue にしません。 公開の issue に書くと、手口がそのまま公開されます。

  • admin 権限がある人（PM など）は、リポジトリの Security タブ → Advisories から、非公開のセキュリティアドバイザリ（下書き）として記録します。
  • admin 権限がない人は、Security タブからは報告できません（外部からの非公開の報告機能は無効にしてあります）。見つけたことを、PM に Slack の DM で知らせてください。タスクの割り振りはチャンネルで行いますが（12節）、セキュリティの問題だけは例外です。
  • 直すための issue と PR も、問題の中身に触れない書き方で出します。「使われていない処理を消す」「入力の検査を足す」のように、変更そのものだけを書きます。差分は公開されるので変更の中身は隠せませんが、どこを狙えばよいかを説明する文章は書かずに済むためです。中身はアドバイザリにだけ書きます。
  • 秘密の値（トークンや Web アプリの URL など）がすでにコミットされていたときは、コードから消しても git の履歴に残ります。消しただけで片付いたとはせず、どう扱うかをアドバイザリの中で決めます。

3. ブランチ

• develop から切ります。 develop に直接コミットしません。
• 名前は 種類/名前/issue番号/内容 です。種類は feat（機能）・fix（修正）・docs（文書）です。例：feat/{名前}/123/show-break-card。
• main は使っていません。 2025 年 8 月から更新されておらず、本番は develop を動かしています（deploy.md）。
• PoC（作ってみないと分からないもの）は、試作用のブランチで自由に試します。形が見えないうちに develop 向けのブランチで書くと、本番と同じ品質を早い段階から求められすぎて、試作が進まないためです。完成形が見えたら、develop から新しいブランチを切り、要るファイルだけを git checkout <試作用のブランチ> -- <パス> で持ち込んで PR にします。試行錯誤のコミットは develop の履歴に入れません。持ち込む時期の目安は、本番に入れると確信できたとき、または試作用のブランチが2か月を超えたときです。
• git の追跡から外したいファイルは、ほかの人も同じものを作るかで置き場所を決めます。 誰が作業しても出る生成物（マニュアルの変換の出力など）は、理由のコメントを付けて .gitignore に書きます。自分だけの作業ファイルは、手元の .git/info/exclude に書きます。.git/info/exclude はリポジトリに入らないので、みんなが作る生成物をここに書くと、ほかの人の手元では追跡されていないファイルとして溜まり続けます（PR #491 で .gitignore に移しました）。前は「特定のブランチでしか作らない生成物は .git/info/exclude に書く」という決まりでしたが、これは1人で開発している間しか成り立ちませんでした。ほかの人が同じブランチで作業すると、その人の手元の exclude には何も書かれていないためです。

4. コミット

• メッセージは日本語で、先頭に feat:・fix:・docs: を付けます。何をなぜ変えたかが1行で分かるように書きます。
• Wiki にある [fix] 形式のラベルは、2024 年までの書き方です。

5. PR を出す前に：自分で点検する

• 点検は PR の差分全体を対象にします。主に作ったファイルだけでなく、ついでに直したファイルも見ます。点検の範囲を絞ると、その外で入った誤りは、レビューで指摘されるまで残ります（#564 では、点検しなかったファイルに誤りが3件残っていました）。

• 1か所を直したら、同じ誤りがほかにもないかを git grep で探し、全部直します。

• 数字（件数など）は、重複しない方法で数え直し、元のデータと突き合わせます。 例：git ls-files 'api/**/*_test.go' | wc -l。

• resolve #N や Close #N を書くときは、番号の issue の題名を確かめます。マージすると、中身に関係なくその番号の issue が閉じます。#352 では、ブランチ名の番号の並びに引きずられて、直していない #308 と #309 を閉じてしまいました。

  gh issue view 308 --json title

6. PR

• テンプレート（.github/pull_request_template.md）に沿って書きます。「テスト項目」には、自分で確かめたことと、確かめていないことを分けて書くと、レビューする人が見る場所を決めやすくなります。
• PR を出すと CI が走ります。何が走るかは onboarding.md の11節 を見てください。ADR の前提の点検（docs-refcheck）は、すべての PR で走ります。
• 新しい lint のルールを入れるときは、ルールを入れる変更と、既存の違反を直す変更を分けます。 設定が妥当かの確認と、大量の修正の確認を1つの PR でやると、レビューが追いつかないためです。違反を直す変更はルールごとに issue に分けます。自動で直せるものと手で直すものも、危なさと要る知識が違うので混ぜません。
  • api（Go）は、CI の go-lint が PR で新しく増えた違反だけを見るので、設定だけの PR を先に出せます。
  • mobile は、CI の flutter-lint が既存の違反も含めて、info の指摘1件で落ちます。設定だけの PR は通らないので、先にルールごとの PR で違反を直し、最後にルールを有効にする PR を出します。
  • 45th で mobile に flutter_lints を入れたときは、まだ flutter-lint が無かったので、設定の PR（#280）を先に入れました。242 件の違反はルールごとの子 issue（#286 の下）で直し、違反がなくなってから CI を足しました（#386）。

7. レビュー

人が見る前に、機械で拾えるものは機械で拾います。フォーマッタ → linter（CI の go-lint・flutter-lint）→ AI のレビュー（CodeRabbit。AGENTS.md の規約も読む）→ 人、の順に重ねています。45th は、書く人とレビューする人がほぼ同じ1人で、人のレビューだけに頼れなかったためです。フォーマッタは方針にはありますが、CI にはまだ入っていません。

人のレビュー

develop には、承認1件と、PR 上の会話がすべて解決していることがマージの条件になっています。

44th（2024 年）は、PR を出した人以外が手元で動作確認し、Approve してから、PM がマージしていました（Wiki の「GitとGitHubの使い方（SeeFT）」）。

45th（2026 年）は、ほぼ PM が1人で開発しました。PM は admin 権限で、承認が0件のまま自分の PR をマージしていました。2026 年（9 月末まで）にマージした PR 127 本のうち、作った人以外がレビューしたのは 19 本です。PM 以外のメンバーの PR には、保護ルールがそのまま適用されていました。

複数人で開発するなら、人のレビューを受けることを勧めます。 どちらで進めるかは、その年のチームで決めて、ADR に書いてください。45th の進め方とその理由は ADR 0004 にあります。develop のブランチ保護の設定に関わるので、チームの約束事ではなく運用の方針として扱います。

CodeRabbit

PR には AI のレビュー（CodeRabbit）が付きます。

• 指摘は参考です。スコープ外のものは、理由を書いて見送って構いません。
• 指摘は「その PR が持ち込んだか」と「実害があるか」の2つで振り分けます。 CodeRabbit は PR で触った行を見るので、元からあった問題も、その PR が作ったように見えます。実害は、動かしたときの不具合・ビルドが壊れること・情報が漏れることのどれかです。たとえば、Flutter や依存ライブラリを上げると使えなくなる非推奨の API（deprecated_member_use。PR #343 で直した）は、今は動いていても実害があるものとして扱います。
  • その PR が持ち込んだもの：その PR で直す
  • 元からあって、実害があるもの：PR のスコープ外として、別の issue に切る。範囲が広いときは、親の issue を1つ立て、直す単位ごとに子の issue に分ける（例：mobile の lint の違反は、親の #286 の下にルールごとの子の issue を立てた）
  • 元からあって、見た目や書き方の揃え方だけのもの：スコープ外だと返信して、スレッドを閉じる
• 無料枠のため、レビューは1時間に1回までです。枠を超えると自動では走らず、PR の要約コメントに「Review limit reached」と出ます。枠が戻ってから、PR に @coderabbitai review とコメントすると頼めます。
• 指摘を直したあとの再レビューは、必要なときだけ頼みます。直し方が提案どおりで、境目のケースをテストで確かめてあるなら、頼みません。1時間に1回の枠は、まだ誰も見ていない PR のために取っておきます。直し方が提案から大きく外れたとき、ほかの場所にも手を入れたとき、テストで確かめられていないときに頼みます。
• CodeRabbit は、自分の指摘が直ったと判断すると、スレッドを自分で「Resolve」します。手で閉じる前に、もう閉じられていないかを見てください。CodeRabbit のスレッドに返信すると CodeRabbit が自動で返信してくるので、見送る理由の返信は1回にまとめます。PR の要約コメントの「Merge Risk」は、最後にレビューできたコミットの時点の評価です（「up to xxxxx」の部分）。

8. マージ

• スカッシュマージ（PR のコミットを1つにまとめる）で develop に入れます。
• マージするのは PM です。

9. ほかの人の PR を引き継ぐ

作った人が続けられなくなった PR を引き継ぐときは、元の PR のブランチにコミットを積んで、同じ PR で作業を続けます。新しいブランチと新しい PR を作って、元の PR を閉じることはしません。最初の議論から引き継いだ後の変更までと、元の作者のコミットが、1つの PR に残るためです（例：#546）。

• 元のブランチが develop より古いときは、git fetch origin で最新を取ってから、git merge origin/develop で取り込みます。rebase して force push はしません。force push すると、元の作者の手元のブランチと食い違うためです。develop へはスカッシュマージなので、merge で取り込んでも develop の履歴は汚れません。
• PR の本文の冒頭に、引き継いだことと、方針を変えたならその理由を書きます。作った人にもひと言コメントします。

10. 本番に反映する

docs/operations/deploy.md の手順に従います。本番で打つコマンドを人に案内するときの書き方は、docs/operations/README.md の「書き方」にあります。

11. 判断を残す

機能を足す・見送る、設計や運用の方針を選ぶ、といった判断をしたら、docs/decisions/ に ADR を書きます。決めたことだけでなく、理由と、選ばなかった候補を書きます。

• 候補を比べて決めるときは、決める前に ADR を「提案」の状態で PR に出し、PR の上で議論します。AGENTS.md の「Ask First」に当たる変更は、実装の前にこの流れで進めます。
• この文書にあるようなチームの約束事は、ADR にしません。この文書に理由と一緒に書きます。

何を ADR にするかと書き方は、docs/decisions/README.md にあります。

---

12. PM の仕事

タスクを割り振る

• 割り振りは DM ではなく、チームのチャンネルに投稿します。記録が残り、同じ種類のタスクを持つほかのメンバーも、その説明を参考にできるためです。相手へのメンションと issue のリンクに、お手本や設計のリンクを添えます。最後に「質問があれば対面か通話の時間を取ります。なければ次の MT か作業会で」と書き添えます。
• 対面や通話は、相手が望んだときに取ります。先に日程を押さえると、相手の負担だけが増えます。
• 同じ種類のタスクを何人かに振るときは、1つずつ issue に分け、先にお手本の PR と設計の文書を用意します。 各自が同じ形で書けるので、レビューも揃えやすくなります。45th のテストでは、親の issue（#404）の下に1関数ずつ子の issue を切り、お手本の PR（#419）と 設計の文書 を先に出してから割り振りました。

作業を並べる

• 作業は価値の高い順に並べます。「これしかできないなら、どれを残すか」を考えて、残すものを先頭にします。軽い作業から始めて弾みを付ける、という並べ方はしません。人も時間も限られているので、途中で時間が尽きても価値の高いものが残る順にします。価値は、すぐ役に立つか、後の作業にどれだけ役に立つか、本来の目的にどれだけ直結するか、で見ます。
• 新しく入った人の最初のタスクは例外です。小さく終わるものから始めて、全体の流れに慣れてもらいます。

タスクを管理する

44th は、タスクを GitHub の Project で管理していました（Wiki の「SeeFTのタスク管理のルール」）。

• 全てのタスクに期日を決める
• 毎週、進捗と、各自がこなせる量を共有する（MT に出られない人は Slack で報告する）
• 詰まったらステータスを「Help」にし、余裕のある人が引き取る。いなければ期日を変える
• 優先度は0（最低限）〜3（余裕があれば）の4段階

45th でこの Project をどこまで使っていたかは、この文書では確かめていません。どう管理するかは、その年のチームで決めてください。

執行部に説明する

執行部など、開発をしていない人に向けた資料は、技術の前提知識が全く無い人が読んでも分かるように組みます。説明するのは判断してもらうため（予算を出すか、運用を変えるか）で、分からない言葉が入ると、判断に要る情報まで伝わらなくなります。

• 流れは「課題 → やりたいこと → しくみ → メリット → コスト → 日程 → 確かめたいこと」です。
• 技術用語（API、SDK、コマンド名など）は、本当に要るかを考えてから使います。「AI」「Google ドキュメント」「Web ページ」くらいの言葉までにします。
• 内部の比較や技術の詳細は、説明の資料から外し、別の文書にします。