Project Management Skill

GitHub Projects + Issues + Milestones で Milestone → Issue → Sub-issue の階層管理を行う。

プロジェクトの発見

gh repo view で owner/repo を取得する
gh project list --owner {owner} でプロジェクト一覧を取得する
対象プロジェクトが不明な場合はユーザーに確認する

管理構造

Milestone（期間単位: 月など）
  ├── Issue（テーマ・機能単位）
  │     ├── Sub-issue
  │     │     ├── Sub-issue（さらに分割可）
  │     │     └── Sub-issue
  │     └── Sub-issue
  └── Issue
        └── Sub-issue

階層の深さは固定しない。タスクの複雑さに応じて適切な深さまで分割する。

最重要ルール: 提案→承認→実行

Milestone、Issue、Sub-issueの作成・変更は、必ずユーザーに提案して承認を得てから実行する。 勝手に作成してはいけない。調査・分析は自由に行ってよいが、GitHubへの書き込みは承認後のみ。

手順:

調査・分析する（コードベース探索、既存Issue確認など）
提案をテーブルや箇条書きでユーザーに提示する
ユーザーの承認・修正指示を待つ
承認を得てから実行する

ワークフロー

1. マイルストーン作成

期間単位で1つ作成する（例: 「2026年4月」）
テーマごとに分けない。テーマはIssueで表現する
due_on に期間の終了日を設定する
作成前にユーザーに名前・期間を提案して承認を得る

2. 親Issue作成

ユーザーが達成したい目標をヒアリングする
コードベースを分析してから提案する: 粒度や内容は、現在のアーキテクチャ・既存コードを踏まえて決める
各Issueについて実装方針を検討してから提案する（後述「Issue本文の構成」を参照）
- Issue候補が複数ある場合、Plan agentをIssue毎に並列起動して実装方針を同時に調査する
提案内容（タイトル・概要・実装方針の一覧）をユーザーに提示する
承認を得てからIssueを作成し、マイルストーンに紐付け、Projectに追加する

Issue本文の構成

親Issue・Sub-issueともに、作成時は以下の構成で本文を書く。 「概要」だけの薄いIssueを作らない。 実装方針を考えてからIssueを作る。

## 概要
このIssueで達成したいこと（1-2文）

## 実装方針
具体的にどう実装するかの設計。以下を含める:
- **変更対象ファイル・モジュール**: どのファイルを変更・新規作成するか
- **実装アプローチ**: どのような方法で実装するか（使うライブラリ、パターン、アルゴリズムなど）
- **データの流れ / 処理フロー**: 入力→処理→出力、またはユーザー操作→API→DB等の流れ
- **インターフェース設計**: 新規・変更するAPI、型定義、コンポーネントのpropsなど（該当する場合）

## 受け入れ基準
- [ ] 完了条件を具体的にチェックリストで記載

実装方針を検討するために:

Plan agentを使って実装計画を立てる — コードベースを調査し、変更対象ファイル、実装アプローチ、影響範囲を特定する
複数Issueの実装方針は並列で調査する — Issue毎にPlan agentを1つ起動し、同時に実行する（Agent toolの並列呼び出し）
既存の実装パターンに合わせる — プロジェクトで使われている技術スタック・設計パターンを踏襲する
具体的なファイル名・関数名に言及する — 抽象的な記述ではなく、実際のコードに即した方針を書く

3. Sub-issue作成

3.1 コードベース分析と分割

Explore agentを使ってアーキテクチャを把握する
コードベースを探索して具体的な実装タスクに分解する
分割の粒度は、1つのSub-issueが1つのPRで完結する程度を目安にする
各Sub-issueについても「Issue本文の構成」に従い、実装方針を記載する

3.2 依存関係の分析

分割したタスクについて、以下の観点で依存関係を特定する:

データ依存: DBスキーマ変更 → それを使うAPI → それを呼ぶUI
インターフェース依存: 型定義・API契約 → 実装 → テスト
インフラ依存: 環境構築・設定 → アプリケーションコード
共通基盤依存: ユーティリティ・共通コンポーネント → それを使う機能

依存関係は有向グラフとして整理し、循環依存がないことを確認する。

3.3 期日の算出

Milestoneの due_on から逆算して各Sub-issueの期日を決める:

依存グラフからクリティカルパス（最長の依存チェーン）を特定する
Milestoneの期限を最終タスクの期日とする
クリティカルパス上のタスクを末尾から順に、各タスクの想定工数分を逆算して期日を割り当てる
クリティカルパス外のタスクは、それに依存するタスクの期日を基準に逆算する
並行実施可能なタスクは同じ期間に配置する

想定工数の目安:

小（型定義、設定変更など）: 1日
中（API実装、コンポーネント作成など）: 2-3日
大（複雑なロジック、大規模リファクタなど）: 4-5日

3.4 提案フォーマット

依存関係と期日を含めた提案をユーザーに提示する:

## Sub-issue提案

### 依存グラフ
Task A（基盤）
├── Task B（API）  ← Aに依存
│   └── Task D（UI）← Bに依存
└── Task C（バッチ）← Aに依存

### タスク一覧
| # | タイトル | 概要 | 実装方針（要約） | 依存先 | 想定工数 | 期日 |
|---|---------|------|-----------------|--------|---------|------|
| 1 | Task A  | ...  | `src/db/schema.ts`にテーブル追加、Drizzle migrate | なし    | 2日     | 4/10 |
| 2 | Task B  | ...  | `src/api/`に新エンドポイント、既存のauth middlewareを流用 | Task A | 3日     | 4/15 |
| 3 | Task C  | ...  | 既存の`BatchProcessor`クラスを拡張 | Task A | 2日     | 4/14 |
| 4 | Task D  | ...  | `src/components/`にReactコンポーネント、SWRでデータ取得 | Task B | 2日     | 4/18 |

クリティカルパス: A → B → D（7日間）
Milestone期日: 4/20（バッファ2日）

3.5 作成と設定

承認を得てからSub-issueを作成する
各Sub-issueにマイルストーンを紐付ける
GraphQL APIの addSubIssue mutationで親子関係を設定する
GitHub Projectに追加する
必要に応じてSub-issueをさらにSub-issueに分割する（その際も依存関係を分析する）

4. 運用ルール

マイルストーン進捗 = closed / (open + closed) で自動計算される
Sub-issueをクローズすると進捗に反映される
親Issueは全Sub-issue完了後にクローズする

開発者の活動状況確認

特定の開発者や、チーム全体の状況を把握するためのワークフロー。

確認手順

予定（何をすることになっているか）
- Project itemsをAssigneeでフィルタし、Status別に集計する
- gh project item-list → assigneesとstatusで分類
進行中（今何をしているか）
- StatusがIn progressのIssueを確認
- gh pr list --author {user} でオープンPRを確認
- git log --author={user} --since="1 week ago" --oneline で直近のcommitを確認
完了（何を終わらせたか）
- StatusがDoneのIssueを確認
- gh pr list --author {user} --state merged でマージ済みPRを確認

レポート形式

## {ユーザー名} の状況

### In Progress
- #XX Issue名（PR: #YY）

### Ready / Backlog
- #XX Issue名

### 直近の活動
- マージ済みPR: #YY, #ZZ
- 直近コミット: N件（過去1週間）

### Done（今期）
- #XX Issue名

gh CLIコマンド詳細

コマンドの具体的な構文は references/gh-commands.md を参照。

重要な注意点

非インタラクティブ環境では --owner, --repo フラグが必須
Sub-issueの紐付けは gh issue edit --add-sub-issue ではなく GraphQL API を使う
マイルストーンは期間単位で1つ。複数作らない
Issueの分割はコードベースの理解に基づいて行う（闇雲に分けない）

project-management