git

name	git
description	Git 操作ルール

コミット作成

• 「コミット」を求められた場合:
  • 重要: 必ず git status で現在の状態を確認すること
  • 重要: 以前の状態やメモリを信用しない — 必ずステージングエリアの現状を確認
  1. ファイルが既にステージングされている場合:
     • 重要: ステージング済みファイルがある場合、git add や git restore を絶対に使わない
     • 重要: ステージングエリアを一切変更しない
     • git diff --staged でステージング済みファイルを確認し、そのファイルのみに基づくコミットメッセージを作成
     • メッセージ付きで git commit を直接実行（ユーザーが適宜承認する）
     • ユーザーが既にステージングエリアを準備済み — その判断を完全に尊重すること
  2. ステージングされたファイルがない場合:
     • git status で差分を確認
     • 以下のコミット粒度に基づいてファイルを順次ステージングしてからコミット:
       • パッケージ単位でコミットを分割
       • 依存元を先にコミット（依存順序が不明な場合は npx lerna list --graph で確認）
• 各コミット後:
  • 重要: 自動的に次のコミットに進まない
  • 重要: 次に何をすべきか推測しない
  • 重要: 以前の状態のメモリを信用しない
  • git status と git diff で現在の状態を確認
  • この判定プロセスの最初に戻る（ファイルがステージングされているかどうかの確認）
  • 続行する前にユーザーの確認または新しい指示を待つ
• OS、アプリケーション設定、またはコンテキストから英語以外の言語が使用されていると判断される場合、コミットコマンド実行の直前に、コミットメッセージの翻訳と説明をその言語で提供すること。

コミット前コンテンツチェック

git commit を実行する前に、必ず git diff --staged をスキャンして以下の 2 点を確認する。dogfooding として実データ・実コーパスで実験やデバッグを行うリポジトリなので、実データ断片の混入には特に厳重に注意する。

1. 機密・案件情報の検出

プロジェクト固有の名称、企業名、顧客情報、API キー・トークンなど、リポジトリに含めるべきでない情報がないか確認する。

2. サンプル値の慣例チェック

サンプル値が「無いこと」ではなく「予約済み慣例に従っていること」を確認する。

許可される値（予約済み慣例）:

• ドメイン: example.com / example.org / example.net、*.example / *.test / *.invalid / *.localhost（RFC 2606 / RFC 6761）
• IP: 127.0.0.1、TEST-NET（192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24）、2001:db8::/32
• メール: [e-mail] 系
• E2E の localhost:8010 / 127.0.0.1 は正当（test-server / 外部リンクシミュレーション）

検出対象（混入してはいけない値）:

• 実在する無関係ドメイン・URL・パス
• 未取得の創作ドメイン（もっともらしい造語ドメインは将来第三者が取得しうる — supply-chain / SEO リスク）
• 案件キーワード・顧客識別子・実データ由来の識別子
• dogfooding で使った実データ・実コーパスの断片（実 URL、実ページタイトル、実クエリ値など）

検出時の対処:

• ステージングから除外するのではなく、汎用値（example.com 等）へ書き換える（fixture 内の実ドメインは除外しても解決しない）。書き換え後にテストが通ることを確認してからコミットする
• 判断が難しい場合（実データが検証に不可欠に見える等）はユーザーに確認する

パッケージのコミット順序（依存元優先）

複数パッケージにまたがる変更をコミットする場合、必ずリーフからルートへ（依存元を依存先より先に）コミットする。

@d-zero/beholder（外部）
      ↑
      └── crawler ── @nitpicker/cli ← @d-zero/roar（外部）
           ↑              ↑      ↑
           │             core   report-google-sheets
           │              ↑
           │         analyze-* プラグイン
           └── @d-zero/dealer（外部）

ティア	パッケージ
0	types
1	crawler, core
2	analyze-axe, analyze-lighthouse, analyze-main-contents, analyze-markuplint, analyze-search, analyze-textlint, report-google-sheets
3	cli（統合 CLI）
—	test-server（E2E テスト専用、プロダクションコードには非依存）

• 同一ティア内では順序不問
• ルート設定の変更（tsconfig.json, CI 等）はパッケージの変更より先にコミット
• 単一パッケージの変更は順序付け不要 — そのパッケージだけをコミット
• 不明な場合は npx lerna list --graph で確認

コミットメッセージの形式

• 英語で記述すること
• 命令法を使用すること
• Conventional Commits を使用すること
  • 使用するタイプ: feat, fix, docs, refactor, test, chore
  • 使用するスコープ:
    • 各パッケージ名（ネームスペースなし）: crawler, core, types, analyze-axe, analyze-lighthouse, analyze-main-contents, analyze-markuplint, analyze-search, analyze-textlint, report-google-sheets, cli
    • repo, deps, github
• メッセージ本文の各行は100文字以下
• 件名は sentence-case, start-case, pascal-case, upper-case にしない

コミットメッセージの安全ガイドライン

• 破壊的変更や複雑なコミットメッセージには、必ず heredoc 形式を使用（下記参照）
• シンプルな1行コミットにはシングルクォート (') を使用
• 破壊的変更で複数の -m フラグを絶対に使わない（commitlint のパースエラーの原因になる）

Heredoc 形式（破壊的変更では必須）

heredoc とコマンド置換を使って複数行のコミットメッセージを渡す。これにより:

• 特殊文字（感嘆符など）が正しく保持される
• 複数行メッセージが適切にフォーマットされる
• commitlint がメッセージを正しくパースできる

形式:

git commit -m "$(cat <<'EOF'
type(scope)!: subject line

BREAKING CHANGE: 説明

詳細:
- 変更点1
- 変更点2
EOF
)"

重要な注意点:

• <<'EOF'（クォート付き）で変数展開を防ぐ
• EOF の後に ) で閉じてコマンド置換を完了
• 破壊的変更で複数の -m フラグを使用しない
• メッセージ全体を "$(cat <<'EOF' ... EOF)" で囲む

シンプルなコミット（非破壊的変更）

破壊的変更のないシンプルな1行コミット:

git commit -m 'type(scope): subject line'

複数行の非破壊的コミットにも、適切なフォーマットを確保するため heredoc 形式を使用すること