github-agile

GitHub アジャイル：コンテキストネットワークを活用したフィーチャーブランチ開発

GitHub を活用したアジャイルワークフローの問題を診断します。開発者が GitHub Issues、Pull Requests、フィーチャーブランチを使用して、健全なワークフローを確立し、維持できるよう支援する一方、コンテキストネットワーク内の理解も保全します。

基本原則

作業の場は GitHub、理解の場はコンテキストネットワークです。 Issues は何をする必要があるかを追跡し、コンテキストネットワークは判断の理由を保全します。どちらも情報を永続的に保持しますが、役割は異なります。GitHub はコラボレーションと実行に、コンテキストネットワークは判断と継続性に使用します。

状態

セットアップトラック

---

状態 GH0：GitHub CLI がない

症状：

• gh コマンドが見つからない
• コマンドラインから GitHub の操作を実行できない
• GitHub CLI をインストールしていないとユーザーが報告している
• GitHub の操作がウェブ上での手動操作に限られている

主な質問：

• 新しいマシンですか、それとも既存の開発環境ですか？
• Homebrew（macOS）、apt（Linux）、winget/scoop（Windows）のいずれかを使用していますか？
• これまでに GitHub の認証を行ったことがありますか？
• GitHub アカウントを持っていますか？

対応策：

• scripts/gh-verify.ts を実行して環境を診断します
• プラットフォーム別のインストール方法：
  • macOS：brew install gh
  • Linux：sudo apt install gh または https://github.com/cli/cli/blob/trunk/docs/install_linux.md を参照してください
  • Windows：winget install --id GitHub.cli または scoop install gh
• インストール後、認証します：gh auth login
• gh auth status で確認します

---

状態 GH1：リポジトリが初期化されていない

症状：

• ディレクトリは存在するが、git リポジトリではない
• Git リポジトリは存在するが、GitHub リモートがない
• GitHub リモートは存在するが、gh repo view が失敗する
• バージョン管理なしでローカル作業をしている

主な質問：

• 新しいプロジェクトですか、それとも GitHub を使っていない既存のコードですか？
• パブリックリポジトリとプライベートリポジトリのどちらを希望しますか？
• このプロジェクト用のコンテキストネットワークはすでにありますか？
• 初回コミットが必要な既存ファイルはありますか？

対応策：

• 必要に応じて git を初期化します：git init
• GitHub リポジトリを作成してリンクします：gh repo create <name> --source=. --push
• または、既存のリモートをリンクします：git remote add origin <url>
• コンテキストネットワークがない場合は初期化します（context/ ディレクトリを作成）
• 標準的な構成で初回コミットを作成します
• gh repo view で確認します

---

状態 GH2：ワークフローが確立されていない

症状：

• GitHub リポジトリは存在するが、ラベル、マイルストーン、Issue テンプレートがない
• main にブランチ保護が設定されていない
• テンプレートを含む .github/ ディレクトリがない
• コンテキストネットワークが GitHub ワークフローに接続されていない
• 規約が文書化されていない

主な質問：

• 個人プロジェクトですか、それともチームプロジェクトですか？
• 作業スタイルに合うラベル体系はどれですか？（標準／シンプル／カスタム）
• 作業を期間で区切るためにマイルストーンを使いますか？
• main ブランチへの直接コミットを防ぐため、ブランチを保護しますか？

対応策：

• scripts/gh-init-project.ts を実行してプロジェクト構成を設定します
• feature、bug、task のテンプレートを含む .github/ISSUE_TEMPLATE/ を作成します
• .github/pull_request_template.md を作成します
• ブランチ保護を有効にします：gh api repos/{owner}/{repo}/branches/main/protection -X PUT -f ...
• ワークフローを context/architecture.md に記録します
• セットアップに関する判断を context/decisions.md に記録します

---

ワークフロートラック

---

状態 GH3：バックログの混乱

症状：

• ラベルがない、または一貫性のないラベルが付いた課題が多数ある
• マイルストーンが割り当てられていない
• 重複または重複する内容の課題がある
• 次に何に取り組むべきか判断できない
• 課題に問題ではなく解決策が記載されている
• 古い課題と現在の優先事項が混在している

主な質問：

• オープンな課題はいくつありますか？
• 優先度は何によって決まりますか？（期限、価値、依存関係、工数）
• クローズまたは統合すべき課題はありますか？
• 最後にバックログを整理したのはいつですか？
• 課題は要件に紐付いていますか、それとも場当たり的なアイデアにすぎませんか？

対応策：

• scripts/gh-audit.ts を実行して、バックログの健全性を評価します
• 課題を監査します：gh issue list --state open --json number,title,labels,createdAt
• MoSCoW 優先順位付け（Must／Should／Could／Won't）を適用します
• 削除するほどではない保留項目用に「icebox」ラベルを作成します
• 重複する課題を、正規の課題への参照を付けてクローズします
• requirements-analysis を使用した場合は、課題を要件に紐付けます
• 現在の重点期間用のマイルストーンを作成します
• 現在のスプリント／マイルストーンの重点項目で context/status.md を更新します

---

状態 GH4：フィーチャーブランチの違反

症状：

• main ブランチに直接コミットしている
• ブランチの命名規則がない
• フィーチャー作業が複数のブランチに分散している
• 長期間存続するブランチが原因で、マージの競合が頻発する
• どのブランチがどの課題に関連するのか判断できない
• main から main への PR が作成されている（可能な場合）

主な質問：

• main でブランチ保護は有効になっていますか？
• どのような命名規則が適していますか？（feature/、fix/、issue-{number}/）
• 貢献者はあなただけですか、それとも他の人も参加する予定ですか？
• フィーチャーブランチは通常どのくらいの期間存続しますか？

対応策：

• GitHub の設定または API を使ってブランチ保護を有効にします
• context/architecture.md にブランチの命名規則を定めます：
  • feature/{issue-number}-short-description
  • fix/{issue-number}-short-description
  • 課題に紐付かないメンテナンスには chore/{description}
• 課題からブランチを作成します：gh issue develop {number} --base main
• または手動で作成します：git checkout -b feature/{number}-description main
• ブランチは短期間（数日単位で、数週間ではなく）に保ちます
• ブランチのワークフローを context/decisions.md に記録します

---

状態 GH5：コンテキストのない PR

症状：

• 説明が最小限の PR（「バグを修正」「コードを更新」など）
• PR に紐付いた課題がない
• 決定事項、要件、アーキテクチャへの参照がない
• コードレビューに変更理由のコンテキストがない
• コードを要件や決定事項まで追跡できない
• 将来、経緯を調査することが不可能

主な質問：

• PR テンプレートはありますか？
• PR はどのように課題に紐付けるべきですか？（Fixes #、Closes #、Related to #）
• PR から ADR や要件ドキュメントを参照すべきですか？
• レビュアー（または将来のあなた）にはどのような情報が必要ですか？

対応策：

• .github/pull_request_template.md を作成または更新し、必須セクションを設けます：
  • 概要（変更内容）
  • 関連する課題（クローズキーワードを含む）
  • 理由（動機、コンテキスト）
  • テスト方法
  • コンテキストの参照先（関連する場合は、決定事項や ADR へのリンク）
• チェックリストを追加します：課題へのリンク、テスト計画、コンテキストの参照先
• gh pr create --template を使ってテンプレートを適用します
• アーキテクチャに関わる変更では、context/decisions.md を相互参照します

---

状態 GH6：放置された Issue／PR

症状：

• 数か月間活動のないオープン Issue がある
• マージされることのないドラフト PR がある
• 放置された作業に「WIP」ラベルが付いている
• Issue の数が増え続け、減らない
• 進行中の作業と放置された作業を見分けられない
• ゾンビ Issue による心理的な負担がある

主な質問：

• Issue が「放置」と見なされる基準は何ですか？（30 日？90 日？）
• 放置された項目には、自動でラベルを付けるべきですか、それとも自動でクローズするべきですか？
• 実際には「いつか／できれば」と考えている Issue があり、別の扱いが必要ですか？
• 放置された項目をオープンのままにしておくコストは何ですか？

対策：

• scripts/gh-audit.ts --stale を実行して古い項目を特定します
• 放置された項目を監査します：gh issue list --state open --json number,title,updatedAt | jq '.[] | select(...)'
• 判断が必要な項目に「stale」または「needs-review」ラベルを作成します
• 放置された項目ごとに判断します：
  • まだ関連がありますか？更新して優先順位を見直します
  • いつか／できれば取り組みますか？再開の明確な条件を設定してアイスボックスに移します
  • 実現しませんか？理由を説明してクローズします
• context/architecture.md に放置ポリシーを記録します
• 自動化のために GitHub Actions の stale bot を検討します

---

状態 GH7：コンテキストネットワークの不足

症状：

• GitHub では作業が進行中ですが、コンテキストネットワークが空、または古い状態です
• 過去の決定の理由を説明できません
• 新しいセッションでは、プロジェクトの理解が一から必要です
• ADR（アーキテクチャ決定記録）が記録されていません
• status.md に現在の作業が反映されていません
• ナレッジがクローズ済みの Issue／PR にしかなく、見つけにくい状態です

主な質問：

• このプロジェクト用のコンテキストネットワークがありますか？
• status.md が最後に更新されたのはいつですか？
• GitHub のディスカッションや Issue にある決定のうち、decisions.md に記録すべきものはありますか？
• コンテキストだけで、プロジェクトについて他の人（将来の自分も含む）が理解できますか？

対策：

• コンテキストネットワークがない場合は初期化します：

  context/
  ├── discovery.md      # Navigation and overview
  ├── status.md         # Current work, recent changes
  ├── decisions.md      # Key decisions with rationale
  ├── architecture.md   # System design, workflows
  └── glossary.md       # Project-specific terms
  

• scripts/gh-sync-context.ts を実行してステータスの更新を生成します
• 現在のスプリント／マイルストーンを反映するよう status.md を更新します
• クローズ済みの Issue／PR から決定事項を抽出し、decisions.md に記録します
• GitHub ワークフローを記録するセクションを architecture.md に作成します
• GitHub のマイルストーンをコンテキストネットワークのフェーズにリンクします

---

状態 GH8：健全なワークフロー

症状：

• Issue にラベルが付けられ、優先順位が設定され、マイルストーンが割り当てられています
• すべての作業は、PR を介してフィーチャーブランチで行われます
• PR は Issue にリンクされ、内容を適切に説明しています
• コンテキストネットワークに現在の状態と決定が反映されています
• 「何に取り組んでいるのか」「その理由は何か」に答えられます
• 新しいセッションでも、再調査せずに作業を再開できます

指標：

• gh issue list に、関連性のある現在の作業だけが表示されます
• gh pr status に、目的が明確な進行中の作業が表示されます
• context/status.md が GitHub の実際の状態と一致しています
• 最近のコミットは main ではなく、フィーチャーブランチにあります
• しきい値を超えて古い Issue に、説明がないものはありません

メンテナンス：

• 毎週の同期：GitHub の状態を context/status.md に反映します
• スプリント／マイルストーンの区切り：振り返りで得た知見を decisions.md に記録します
• アーキテクチャの変更：コンテキストネットワークに ADR を作成します
• scripts/gh-audit.ts で定期的に監査します

---

GitHub とコンテキストネットワークの境界

GitHub に置くもの

成果物	GitHub に置く理由
Issue	コラボレーション、状態の追跡、通知、リンク
Pull Request	コードレビュー、CI 連携、マージの追跡
Discussions	チーム／コミュニティでの会話、Q&A、RFC
Actions／Workflows	CI/CD、自動化、適用
Labels／Milestones	整理、フィルタリング、進捗の追跡
Project Boards	視覚的なワークフロー（任意）

Context Network に保存するもの

成果物	Context Network に保存する理由
ADR（アーキテクチャ決定記録）	構造化された推論、検索可能性、フレームワークとの統合
decisions.md	複数の領域にまたがる決定、ポリシー、根拠
status.md	現在の注力事項、最近の変更、セッションの継続性
architecture.md	システム設計、ワークフローのドキュメント
discovery.md	プロジェクトの理解、ナビゲーション
glossary.md	用語、共通認識
振り返りで得た知見	今後の作業を改善するための学び

ブリッジ成果物（相互参照）

成果物	主な保存場所	相互参照
要件ドキュメント	context/ または docs/	issue からリンク
システム設計	context/architecture.md	PR で参照
スプリント／マイルストーンの目標	status.md	GitHub のマイルストーンと照合
重要な決定	decisions.md	issue／PR のコメントで参照

---

モード別ワークフロー

個人開発者モード

目的： 自己規律、未来の自分のための履歴、構造化された思考

適用内容：

• ブランチ保護も引き続き有用です（事故を防ぎます）
• PR のセルフレビュー：単なるマージの関門ではなく、思考を整理するチェックポイントとして PR を活用します
• 記憶としての issue：将来のセッションのために issue を作成します
• 簡略化したラベル：type:feature、type:bug、type:task、priority:high/low
• 相談できるチームがいないため、Context Network は特に重要です

ワークフロー：

1. セッション開始時：context/status.md と gh issue list を確認します
2. issue を選ぶか、新しい作業用に作成します
3. 機能ブランチを作成します：gh issue develop {number}
4. 定期的にコミットしながら作業します（メッセージで issue を参照します）
5. PR を作成します：gh pr create --fill
6. セルフレビューします：他の人が書いたかのように差分を読みます
7. マージします：gh pr merge --squash
8. 重要な変更があれば context/status.md を更新します

チームモード（2～5人）

目的： コラボレーション、コードレビュー、共通認識

適用内容：

• マージ前のコードレビューを必須にします
• 担当者の規約を定めます（誰が何を担当するか）
• 定例会を実施します（スタンドアップ、計画、振り返り）
• 担当者関連を含む、より体系的なラベルを使用します
• 非同期での決定には Discussions を使用します

ワークフロー：

1. 計画：issue を作成／調整し、マイルストーンに割り当てます
2. 割り当て：issue を割り当て、コメントで連絡します
3. 開発：機能ブランチを作成し、定期的にコミットします
4. PR 作成：詳しい説明を記載し、レビュアーを依頼します
5. レビュー：承認、変更依頼、またはコメントを行います
6. マージ：承認後、スカッシュマージします
7. 同期：週次で Context Network を更新し、マイルストーンの振り返りを行います

チームラベル（追加分）：

• status:needs-review - コードレビュー待ち
• status:changes-requested - レビュアーが変更を依頼
• needs:discussion - 先に進む前にチームの意見が必要

---

主要なワークフロー

1. プロジェクト初期化の手順

開始条件： 新しいプロジェクト、または初めての GitHub 連携

手順：

1. GH CLI がインストールされ、認証済みであることを確認します（GH0）：scripts/gh-verify.ts
2. リポジトリを作成またはリンクします（GH1）：gh repo create または git remote add
3. 初期化を実行します：scripts/gh-init-project.ts --labels standard --templates --protection
4. 存在しない場合は Context Network を初期化します
5. ワークフローを context/architecture.md に記録します
6. 決定事項を context/decisions.md に記録します
7. 初期作業フェーズ用の最初のマイルストーンを作成します

2. 機能開発ワークフロー

開始条件： 新しい作業項目の開始

手順：

1. issue が存在することを確認します（なければ作成します）：gh issue create
2. issue から機能ブランチを作成します：

   gh issue develop {number} --base main
   # Or manually:
   git checkout -b feature/{number}-short-description main
   

3. 規約に沿ったメッセージでコミットします：

   feat(scope): description (#123)
   fix(scope): description (#123)
   chore: description
   

4. 定期的にプッシュします：git push -u origin HEAD
5. 準備ができたら PR を作成します：

   gh pr create --fill
   # Or with explicit template:
   gh pr create --title "feat: description" --body-file .github/pull_request_template.md
   

6. PR が次の条件を満たしていることを確認します：
   • issue にリンクしている（Closes #123）
   • 意味のある説明がある
   • アーキテクチャに関わる場合は Context Network を参照している
7. レビューを行います（自分またはチーム）
8. gh pr merge --squash でマージします（スカッシュすると履歴が整理されます）
9. PR のキーワードによって issue が自動的にクローズされます
10. ブランチを削除します：git branch -d feature/{number}-description

3. スプリント／マイルストーンの同期

トリガー： マイルストーンの開始時または終了時

開始時：

1. マイルストーンを作成します：gh api repos/{owner}/{repo}/milestones -f title="Sprint X" -f due_on="YYYY-MM-DD"
2. イシューをマイルストーンに割り当てます
3. マイルストーンの重点項目と目標を context/status.md に更新します
4. 優先順位を共有します（個人の場合は書き留め、チームの場合は計画ミーティングを実施します）

終了時：

1. マイルストーンを確認します：gh issue list --milestone "Sprint X"
2. 完了したマイルストーンをクローズします
3. 未完了のイシューを次のマイルストーンまたはアイスボックスに移します
4. 振り返りを context/decisions.md に記録します：
   • うまくいったことは何ですか？
   • うまくいかなかったことは何ですか？
   • 何を変更しますか？
5. 概要を context/status.md に更新します

4. コンテキスト同期の定例作業

トリガー： 毎週、または重要な作業の後

手順：

1. 監査を実行します：scripts/gh-audit.ts
2. 同期を実行します：scripts/gh-sync-context.ts --dry-run（まず内容を確認します）
3. context/status.md を更新します：
   • 現在のマイルストーン／スプリント
   • 対応中のイシュー／PR
   • 最近の完了事項
   • ブロッカー、または必要な決定
4. クローズしたイシュー／PRから決定事項を抽出し、decisions.md に記録します
5. ワークフローが進化した場合は、architecture.md を更新します
6. 確認します：コンテキストだけで、他の人が作業を再開できますか？

---

アンチパターン

GitHub を Wiki として使う

問題： コンテキストネットワークに置くべき長文ドキュメント、決定事項、コンテキストに GitHub のイシューを使っています。重要な情報がコメントに埋もれ、後から見つけるのが困難になります。 症状： イシューの説明が膨大になる、コメントでアーキテクチャについて議論する、決定事項がクローズ済みイシューに散在する。 対処： GitHub では作業項目を追跡し、コンテキストネットワークでは理解を記録します。イシューのライフサイクルを超えて残す必要がある情報は、context/ に移します。

イシューの墓場

問題： 作成されたイシューがクローズされず、バックログの意味がなくなっています。新しいイシューが古いイシューの上に積み重なります。 症状： 200 件以上のオープンイシュー、そのほとんどが何か月も手つかず、「いずれ対応する」という考え方、何に取り組むか決められずに停滞する。 対処： 定期的に整理します。90 日以内に対応しないものは、アイスボックスに移すかクローズします。古くなった大きなバックログより、小さく最新のバックログが優れています。積極的に削除します。

コンテキストのない PR

問題： 変更内容は説明されていても理由が記載されていない PR では、後から経緯をたどることができません。 症状： コンテキストなしに「バグを修正」「スタイルを更新」「コードをリファクタリング」とだけ記載されています。半年後には、誰も理由がわかりません。 対処： 必須セクション（内容、理由、テスト方法、関連イシュー）を含む PR テンプレートを使います。アーキテクチャに関わる変更の場合は、ADR を参照します。

重複イシュー製造機

問題： 既存のイシューを確認せずに新しいイシューを作成すると、議論が分散し、労力が無駄になります。 症状： 同じ内容のイシューが複数存在する、重複イシュー間で作業が分散する、解決方法が食い違う。 対処： 作成前に検索します：gh issue list --search "keyword"。重複するイシューは、正となるイシューを参照してクローズします。

永遠に終わらないドラフト PR

問題： ドラフトとして開かれた PR が完了しないまま放置され、心理的な負担となり、PR の一覧が散らかります。 症状： 30 日以上経過したドラフト PR、恒久化した WIP ラベル、スコープの拡大でマージできなくなった PR。 対処： ドラフトに期限を設けます。2 週間以内に準備が整わない場合は、クローズしてスコープを見直します。マージできない大きな PR より、マージ可能な小さな PR が優れています。

ブランチ保護の回避

問題： 「今回だけ」とブランチ保護を無効にし、main に直接コミットします。これが前例となり、今後も回避するようになります。 症状： PR なしで main にコミットする、main のビルドが壊れる、「次のコミットで修正する」。 対処： ブランチ保護には理由があります。個人開発者でも、履歴の記録、レビューのチェックポイント、ロールバック機能を得られる PR のワークフローが役立ちます。

分断されたコンテキスト

問題： コンテキストネットワークは存在しますが、更新されず、ドキュメントではなくフィクションになっています。誤解を招くため、コンテキストがないよりも悪い状態です。 症状： status.md には数か月前に完了した作業が記載され、decisions.md には最近のアーキテクチャ変更が反映されておらず、新しいセッションではコンテキストを信頼できません。 解決策： コンテキストの同期を後回しにせず、ワークフローの一部にします。セッション終了時の確認事項：status.md は現状を反映していますか？

---

利用可能なツール

gh-verify.ts

GitHub CLI のインストールと認証状況を確認します。

deno run --allow-run scripts/gh-verify.ts
deno run --allow-run scripts/gh-verify.ts --json

出力：

• CLI のインストール状況とバージョン
• 認証状況と現在のユーザー
• デフォルトのリポジトリ（リポジトリのディレクトリにいる場合）
• 不足しているものがある場合の推奨事項

終了コード： 0（問題なし）、1（gh がありません）、2（ログインしていません）、3（リポジトリのコンテキストがありません）

gh-init-project.ts

ラベル、テンプレート、ブランチ保護を設定して GitHub プロジェクトを初期化します。

deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts --labels standard --templates --protection
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts --mode team --labels standard

オプション：

• --labels [standard|simple|minimal] - 作成するラベルの構成
• --templates - Issue と PR のテンプレートを作成
• --protection - main のブランチ保護を有効にする
• --mode [solo|team] - 作業スタイルに合わせてデフォルト設定を調整
• --dry-run - 作成せずに、作成される内容を表示

作成されるもの：

• gh label create によるラベル
• feature、bug、task のテンプレートを含む .github/ISSUE_TEMPLATE/
• .github/pull_request_template.md
• ブランチ保護ルール（--protection を指定した場合）

gh-audit.ts

現在の GitHub の状態を、健全なワークフローの指標と照らし合わせて監査します。

deno run --allow-run scripts/gh-audit.ts
deno run --allow-run scripts/gh-audit.ts --json
deno run --allow-run scripts/gh-audit.ts --stale 30

オプション：

• --json - スクリプトで使えるよう JSON 形式で出力
• --stale [days] - N 日間アクティビティのない項目にフラグを付ける（デフォルト：30）
• --verbose - 項目ごとの詳細な分析を表示

確認項目：

• オープンな Issue の数とラベルの網羅状況
• オープンな PR の状況（ドラフト、関連付けられた Issue、経過日数）
• 最近のコミット（どのブランチか、main への直接コミットか）
• マイルストーンの利用状況と進捗
• 滞留項目の特定

出力： 具体的な推奨事項を含む健全性スコア（0～100）

gh-sync-context.ts

GitHub の状態からコンテキストネットワークの更新内容を生成します。

deno run --allow-run --allow-write scripts/gh-sync-context.ts
deno run --allow-run scripts/gh-sync-context.ts --dry-run
deno run --allow-run --allow-write scripts/gh-sync-context.ts --status --decisions

オプション：

• --dry-run - 書き込みをせず、書き込まれる内容を出力
• --status - status.md の更新セクションを生成
• --decisions - 「decision」ラベルが付いたクローズ済み Issue から決定事項を抽出
• --output [dir] - 書き込み先のディレクトリ（デフォルト：context/）

生成されるもの：

• status.md 用のステータス更新内容
• クローズ済み Issue から抽出した決定事項の候補
• マイルストーンの概要

---

やり取りの例

個人開発者：新規プロジェクトの開始

開発者：「ローカルのプロジェクトを GitHub に登録して、適切なワークフローを使い始めたいです。」

診断： 状態 GH1（リポジトリ未初期化）

進め方：

1. scripts/gh-verify.ts を実行し、CLI の準備ができていることを確認する
2. 「リポジトリは公開にしますか、それとも非公開にしますか？」と尋ねる
3. リポジトリを作成する：gh repo create my-project --source=. --private --push
4. scripts/gh-init-project.ts --mode solo --labels simple --templates を実行する
5. コンテキストネットワークを初期化する：status.md と decisions.md を含む context/ を作成する
6. context/architecture.md に記録する：「追跡には GitHub Issues を使い、すべての変更にフィーチャーブランチを使い、マージと履歴管理には PR を使う。」
7. 現在の作業について最初の Issue を作成する
8. ブランチのワークフローを実演する：gh issue develop 1

チーム：バックログの整理

開発者：「オープンな Issue が 150 件ありますが、何が重要なのか誰もわかっていません。」

診断： 状態 GH3（バックログの混乱）

進め方：

1. scripts/gh-audit.ts --stale 60 を実行し、対象範囲を特定する
2. 「現在の優先事項は何ですか？ 近いうちにリリースすべきものは何ですか？」と尋ねる
3. 直近の重点事項に向けてマイルストーンを作成する
4. Issue をトリアージする：
   • マイルストーンに不可欠 → マイルストーンに割り当て、優先度ラベルを追加
   • 有効だが今すぐではない → icebox ラベルを追加
   • 古く、今後の進め方がない → 説明を添えてクローズ
   • 重複 → 正規の Issue を参照してクローズ
5. 重点事項を context/status.md に反映する
6. 整理の頻度を決める：毎週 15 分のレビュー

個人開発者：コンテキストの劣化

開発者：「1 か月ぶりにこのプロジェクトに戻ってきたら、何をしていたのかまったく分かりません。」

診断： 状態 GH7（コンテキストネットワークの欠落）

アプローチ：

1. GitHub の状態を確認します：gh issue list、gh pr status
2. scripts/gh-sync-context.ts --dry-run を実行して、現在の状態を確認します
3. コンテキストネットワークを初期化または更新します：
   • status.md：現在のマイルストーンは何か？進行中の Issue はあるか？
   • decisions.md：クローズ済みの PR でアーキテクチャ上の決定があったか？
4. 直近のセッション以降にクローズされた Issue／PR を確認し、状況を把握します
5. 「前回のセッション」の概要を status.md に追加します
6. 各セッションの終了時に status.md を更新する習慣をつけます

---

出力の保存

出力先の確認

ほかの作業を始める前に：

1. プロジェクト内に context/output-config.md があるか確認します
2. 見つかった場合、このスキルの項目を探します
3. 見つからない場合は、次のように尋ねます：「GitHub ワークフローの出力はどこに保存すればよいですか？」
   • 推奨先：コンテキストネットワークのファイルには context/、GitHub の設定には .github/
4. 設定を context/output-config.md に保存します

主な出力

出力	保存先
Issue テンプレート	.github/ISSUE_TEMPLATE/
PR テンプレート	.github/pull_request_template.md
ワークフローのドキュメント	context/architecture.md（GitHub ワークフローのセクション）
セットアップに関する決定	context/decisions.md
ステータスの更新	context/status.md
監査レポート	context/github-audit-{date}.md（保存する場合）

会話とファイルの使い分け

ファイルに保存する内容	会話にとどめる内容
テンプレート（.github/）	診断に関する議論
ワークフローのドキュメント	ラベル体系の検討
コンテキストネットワークの更新	トリアージの決定
監査レポート（依頼があった場合）	簡単なステータス確認

---

行わないこと

• ユーザーの確認なしに Issue を作成しません
• PR を自動的にマージしません
• 明示的な依頼なしに Issue、PR、ブランチを削除しません
• 明示的な依頼なしにブランチ保護を変更しません
• gh が利用可能かどうかの確認を省略しません（必ず最初に GH0 を確認します）
• gh auth status で確認せずに GitHub へアクセスできると想定しません
• コンテキストネットワークを GitHub のみのストレージに置き換えません
• main ブランチにコミットしません（フィーチャーブランチのワークフローを徹底します）
• ユーザーに知らせずにリモートへプッシュしません
• 診断し、推奨し、確認を得て実行します。判断するのは開発者です

---

他のスキルとの連携

requirements-analysis からの連携

requirements-analysis の出力	github-agile での利用
問題の説明	問題を説明する初期 Issue を作成します
ニーズの階層	Issue の優先度ラベルに反映します
制約の一覧	context/ に記録し、Issue から参照します
検証済みの要件	フィーチャー Issue を作成し、要件ドキュメントとリンクします

system-design からの連携

system-design の出力	github-agile での利用
ADR	context/adr/ または docs/adr/ に保存し、PR から参照します
コンポーネントマップ	コンポーネント別の Issue 分割に活用します
ウォーキングスケルトン	関連する Issue をリンクした最初のマイルストーンにします
統合ポイント	context/architecture.md に記録します

requirements-analysis への連携

GitHub の状態から要件の問題が判明した場合：

github-agile の状態	トリガー	requirements-analysis の状態
GH3（バックログの混乱）	Issue が問題ではなく解決策を説明している	RA0-RA1
GH3（バックログの混乱）	優先順位をつけられない（すべてが重要）	RA4

system-design への連携

GitHub の状態から設計上の問題が判明した場合：

github-agile の状態	トリガー	system-design の状態
GH5（コンテキストのない PR）	PR に未文書化のアーキテクチャ上の決定が含まれる	SD4
GH4（ブランチ違反）	マージの競合が頻発する	SD3（統合ポイントの欠落）

参考資料

このスキルは、以下を実践します。

• GitHub CLI のドキュメント：https://cli.github.com/manual/
• Context Networks フレームワーク：references/context-networks/
• フィーチャーブランチのワークフローに関するベストプラクティス
• Conventional Commits：https://www.conventionalcommits.org/