issue-dev-rules

issue を 1 件こなすときに守るルールだけを並べたもの。順番に処理する流れ（ループ）は持たない。どの作業の途中でも、該当する節だけ読めばよい。

設定（使う前に書き換える）

項目	値（例）
base ブランチ	main
worktree の親フォルダ	~/develop/<リポジトリ名>-worktree/
チェックコマンド（push 前に通す）	npm run check
レビュアー	<GitHub の login>

1. issue を読む

• 本文・コメント・添付画像・リンク先を全部読んでから着手する。 本文は薄く、画像やリンク先（Slack スレッドなど）に本当の情報があるのが普通。
• 画像やリンク先が開けなかったら「見れていない」と言う。 想像で埋めない。
• 推測で事実を足さない。 画像に無いこと、起票者が言っていない動機を書き足さない。
• 本文の言い換えで終わらせず、本当にやりたいことまで掘り下げる。 「見せ方」の指示で書かれていても、その裏にある問いに戻す。
• 判断がつかない点は、issue コメントで聞いてから進める。 自分のたたき台を 1 つ出して「〜で良さそう？」と聞く。A か B かを丸投げしない。
• 他人が assignee の issue には手を出さない。 着手したら gh issue edit <N> --add-assignee @me で自分を付ける。

2. 作業フォルダ（worktree）

• worktree は 1 つの親フォルダにまとめる。

• 新しく作る前に、親フォルダの中から使い終わった worktree を探して、その中で作業する。 使い終わったとは、次の 2 つを両方満たすもの。

  • 未コミットの変更も未追跡のファイルも 0 件。
  • ブランチが base にマージ済み。または、コミットが全部 push 済みで、その issue が閉じている。

  git fetch -q origin
  for p in <worktree の親フォルダ>/*/; do
    b=$(git -C "$p" branch --show-current)
    n=$(git -C "$p" status --porcelain | wc -l | tr -d ' ')
    git -C "$p" merge-base --is-ancestor HEAD origin/<base> && merged=yes || merged=no
    echo "$p | [${b:-detached}] | 未コミット ${n} | base に含まれる: ${merged}"
  done
  

  squash マージだと「base に含まれる」が no のままになる。そのときは gh pr list --head <ブランチ名> --state merged でマージ済みか確かめる。

• 見つからなければ、親フォルダの中に新しく作る。 .env など git に入っていないファイルはメインのフォルダからコピーし、依存を入れ直す。

• 開発サーバーを使うときは、そのポートを配信しているのが自分のフォルダか確かめる。 別の worktree のサーバーだったら止めずに、自分は別のポートで起動する。

  lsof -p "$(lsof -nP -iTCP:<ポート> -sTCP:LISTEN -t | head -1)" | awk '$4=="cwd"{print $NF}'
  

3. ブランチ

• 着手するときは、base（main）を必ず pull して、最新の main から切る。

  git -C <worktree> fetch origin main
  git -C <worktree> switch -c <ブランチ名> origin/main
  

• ブランチ名には issue 番号とその名前を入れる。 形は <type>/<issue番号>-<issue名を短い英語にしたもの>（小文字・ハイフンつなぎ）。type は feat / fix / chore / docs / refactor / test / ci / build。例: fix/123-login-redirect

• 1 issue = 1 ブランチ。 切る前に、同じ issue のブランチが無いか探す。あればそれを使う。

  git branch -a | grep <issue番号>
  git ls-remote --heads origin "*<issue番号>*"
  git worktree list | grep <issue番号>
  

• push は行き先を明示する。 git push -u origin HEAD:<ブランチ名>。追跡先が main のままだと、素の git push が main に飛ぶことがある。

4. 作業中

• 頼まれたことだけやる。 「ついでにこれも直しました」と範囲を広げない。
• ユーザーが選んだ機能を、別物に切り縮めない。 小さく分けてよいのは、その機能の範囲・条件・順序。欲しい本体を後回しにしない。
• 「試作して」と言われても、本物の画面に小さく実装する。 使い捨てのページや別ルートを新しく作らない。
• 新しい UI は、既存の似たコンポーネントの決まりに合わせる。 色・体裁・単位を独自に決めない。
• グラフや表を作る前に、「この図で答える問い」「どこを見て答えを読むか」「他の形にしない理由」を 1 行ずつ書く。 書けなければ起票者に問いを確かめる。
• plan や手元のメモはコミットしない。 ステージ前に git status を見て、混じっていたら外す。
• うまくいかないときは黙らない。 3 回直しても目的を満たせなければ、PR を出さずに相談する。

5. 証拠（Before / After）

• Before は、自分の環境で現状を再現して撮る。 お客さんが貼った画像は「報告」であって、Before の代わりにしない。

• After は、実装が組み込まれた本物の画面を撮る。 確認用の一時ページやプレビュー用の画面を作って、それを撮らない。

• 本物の画面が出せないときは、データをでっち上げずに止まって聞く。 サンプルで代用してよいのは、ユーザーが「サンプルでいい」と言ったときだけ。

• データ系の変更は、変更前と変更後の実データを並べる。（入力 → 旧出力、入力 → 新出力を 5〜10 行ずつ）

• Before と After の切り替えに git stash を使わない。 無関係な古い stash を戻して作業ツリーを壊すことがある。git checkout origin/main -- <file> と git checkout HEAD -- <file> で切り替える。

• 画像は gh attach で issue / PR に貼る。

  gh attach upload before.png after.png \
    --target <owner>/<repo>#<N> --strategy release-asset --format markdown
  

6. コミット・push・PR

• コミットメッセージは英語。 形は <type>: <subject> (#<issue番号>)。1 行目は 50 文字以内。
• push の前にチェックコマンドを通す。 落ちたら push しない。
• PR の向き先は base（main）。
• PR のタイトルは短い日本語。 issue 番号は入れない。
• PR 本文の 1 行目は Closes #<issue番号>。 マージで issue が閉じる。ただし自動で閉じるのは、向き先がリポジトリのデフォルトブランチのときだけ。
• レビュアーを付ける。 自分ではマージしない（頼まれたときだけ）。
• レビュー指摘は [must] / [imo] / [nits] 全部対応する。 自分の判断で取捨選択しない。対応しないものは、黙って落とさず理由を添えて確認する。
• ゴールを満たしていないのに PR を出さない。

7. issue / PR へのコメント

コメントはお客さんや非エンジニアも読む。読んで困らないことを第一にする。

• 平易な日本語で、短く、結論だけ。 調べた過程や試したことの羅列は載せない。
• 書かないもの：スキル名、技術用語、ファイルパス・関数名・行番号、コードの構造の説明、言い訳。
• 見出しを盛らない。 # ご相談 のような見出しは付けない。
• 見立てや提案は打診調にする。 「〜なのかなと」「〜ありそうな感じですね」のように、相手が決める余地を残す。事実や結論は言い切ってよい。
• 「すでに」「まず」「丸ごと」のような強調語を落とす。 来そうな反論を先回りして潰す説明も入れない。
• 直ったことを報告するときは、直った証拠を見せる。 実データが入った表や画面を出し、出典ページと突き合わせて一致していることを示す。「取得不可 0 件」のような、無かった数だけで終えない。
• 画面の話は絵で見せる。 今の画面と変更後のイメージを並べた画像を貼り、文章は補足に留める。
• 質問・相談は 1〜2 行、本文だけ。 たたき台を 1 つ出して「〜で良さそう？」と聞く。
• 主語と目的語を省かない。 「確認しました」ではなく「出典ページの件数を確認しました」のように、誰が何をしたかを書く。
• 比喩を使わない。 「〜の穴」「〜の壁」「パズルのピース」のような言い方をせず、何が起きているかをそのまま書く。例:「検索に穴があります」ではなく「検索で、カタカナの商品名が見つかりません」。
• AI っぽい書き癖をやめる。
  • 「〜について見ていきます」のような前置きを書かず、いきなり本題を書く
  • 「第一に」「第二に」「最後に」で区切らない
  • 確かめた事実を「〜と言えるでしょう」「〜と考えられます」でぼかさない（打診調にするのは見立てと提案だけ）
  • 「お気持ちよく分かります」のような気遣いや共感を盛らない
  • 短いコメントに見出し・太字・箇条書きを詰め込まず、普通の文で書く
  • 頼まれていない注意書きを足さない
  • 最後に「まとめ」「結論として」で同じことを言い直さない
  • 「より良いものにしていきましょう」「いかがでしたか」のような前向きで大きな締めを書かない

8. gh を使って issue に

……（未記入。元のメモが途中で切れていたため、続きを書き足す）