zhongwei/gh-mh4gf-issync-claude-plugins-issync

Files

Zhongwei Li fb4d2ff5f1 Initial commit

2025-11-30 08:40:07 +08:00

12 KiB

Raw Permalink Blame History

description

description
planフェーズのプロセスを標準化し、コードベース調査を強制することで高品質な進捗ドキュメント作成を実現

/issync:plan: plan実行ワークフロー

進捗ドキュメント（.issync/docs/plan-{番号}-{slug}.md）を初期作成するコマンドです。以下の8ステップを自動化します：

環境変数確認 & モード決定
前提条件確認 & ファイル名決定 & issync init実行 & Stage設定（In Progress）
GitHub Issue内容の確認
コードベース調査（CRITICAL）
基本セクションの記入
Open Questionsの精査
issync pushで同期 & Stage更新（To Review）
GitHub Projects Status & Stage自動変更（自信度低あり → poc / なし → implement, Stage → To Start）

Note: Template v7では、Tasksセクションが削除されています。タスクは /issync:create-sub-issue コマンドで作成します。

コンテキスト

対象ステート: plan（矛盾解消駆動開発ワークフロー）
ファイル命名: .issync/docs/plan-{番号}-{slug}.md
- 番号: Issue URLから抽出（例: /issues/123 → 123）
- slug: Issueタイトルから生成（小文字・ハイフン区切り・2-4単語、例: watch-daemon）
コードベース調査優先: Open Questionsを真に不明な点のみに絞るため、調査を先に実施

前提条件

GitHub Issueが作成されている
ISSYNC_GITHUB_TOKEN 環境変数が設定されている

実行ステップ

ステップ1: 環境変数確認 & モード決定

GitHub Projects連携とラベル自動付与の有効化状態を確認し、以降のステップで使用するモードフラグを設定。

環境変数:

ISSYNC_GITHUB_PROJECTS_NUMBER         # Projects連携モード (例: "1")
ISSYNC_GITHUB_PROJECTS_OWNER_TYPE     # "user" または "org" (デフォルト: "user")
ISSYNC_LABELS_AUTOMATION               # ラベル自動付与モード ("true" で有効)

モード決定:

GitHub Projects連携: ISSYNC_GITHUB_PROJECTS_NUMBERが設定されていれば有効 (未設定時はステップ2, 7, 8をスキップ)
ラベル自動付与: ISSYNC_LABELS_AUTOMATION="true"で有効 (未設定時はステップ8のラベル付与をスキップ)

出力: 設定状態をユーザーに表示

## Environment Check
**GitHub Projects Integration**: {有効/無効} - Project Number: {番号}, Owner Type: {タイプ}
**Label Automation**: {有効/無効}

ステップ2: 前提条件確認 & ファイル名決定 & issync init & Stage設定

ファイル名決定:

Issue URLを確認（例: https://github.com/owner/repo/issues/123）
番号とslugを抽出・生成

初期化:

ケース A: issync未初期化 → issync init <Issue URL> --file .issync/docs/plan-{番号}-{slug}.md
ケース B: 進捗ドキュメント不存在 → 新規sync追加または issync pull --issue <Issue URL>
ケース C: 準備完了 → 次へ

Stage設定: Projects連携モード有効時のみ、Stage→In Progressに設定。失敗時も処理継続。

issync projects set-stage "$ISSUE_URL" "In Progress"

エラーハンドリング: スクリプトが自動処理。環境変数未設定・認証不足・プロジェクト未発見時は警告表示し処理継続。

ステップ3: GitHub Issue内容の確認

Issue内容を理解し、不明点をユーザーに確認。

ステップ4: コードベース調査（CRITICAL）

⚠️ 最重要: Open Questions記載前に必ず調査してください。

調査項目:

類似機能・既存の実装パターン
使用している技術スタック・ライブラリ
テストコードの存在と構造
- プロジェクトのテスト戦略を理解する:
  - 使用しているテストフレームワーク（単体テスト、統合テスト、E2E）
  - 既存のテストパターン（ファイル配置、命名規則、カバレッジ）
  - UIコンポーネントの検証方法（Storybook等の有無）
関連ファイル・モジュール
ドキュメント（README、CLAUDE.md、進捗ドキュメント等）

調査方法 (状況に応じて選択):

ファイル・コード探索:
  Glob: **/*[関連するキーワード]*
  Grep: "関連する関数名やクラス名"
  Read: README.md, CLAUDE.md, docs/

設定ファイル確認:
  Read: package.json, pyproject.toml, Cargo.toml等

テストファイル確認:
  Glob: **/*.test.*, **/*.spec.*, **/*_test.*, test/**/*

実行による確認(必要に応じて):
  Bash: [テストコマンド/リントコマンド/ビルドコマンド等]
  ※ 実際のコマンドはプロジェクトの設定ファイルやREADMEから判断

記録: 発見内容をDiscoveries & Insightsセクションに記録

ステップ5: 基本セクションの記入

テンプレートに従い記入：

Purpose/Overview
Context & Direction
Validation & Acceptance Criteria (ステップ4で調査したテスト戦略に基づくテスト要件を含める)

planフェーズでは記入しないセクション（テンプレートのサンプルテキストを残す）：

Specification / 仕様
Decision Log
Outcomes & Retrospectives

ステップ6: Open Questionsの精査

記載基準:

記載すべき ✅	記載すべきでない ❌
アーキテクチャ上の選択肢	コードを読めばわかる実装詳細
仕様の曖昧性	ドキュメント記載済みの情報
外部システム連携方法	簡単な調査で解決可能な疑問
パフォーマンス考慮事項

目標: 5-10項目に絞る

推奨案の自信度: 推奨案のみに付与（非推奨案は不要）

🟢 自信度:高 - 既存パターン確認済み、実装実績あり
🟡 自信度:中 - 類似パターンあり、慎重に実装
🔴 自信度:低 - 新アプローチ/外部連携/性能影響不明 → pocフェーズで検証必須

フォーマット例:

**Q1: [質問タイトル]**
- [質問の詳細]

**検討案:**
- **[選択肢A]（推奨 自信度:高🟢）**: [説明 + 推奨理由]
- **[選択肢B]**: [説明]
  - トレードオフ: [制約]

**Q2: [別の質問（自信度低の場合）]**
**検討案:**
- **[選択肢C]（推奨 自信度:低🔴）**: [説明]
  - **⚠️ PoC必須**: [検証項目]

ステップ7: GitHub Issueへの同期 & Stage更新

進捗ドキュメントをGitHub Issueに同期。

issync push

Stage更新: Projects連携モード有効時のみ、Stage→To Reviewに設定。失敗時も処理継続。

issync projects set-stage "$ISSUE_URL" "To Review"

ステップ8: GitHub Projects Status & Stage自動変更 & ラベル付与

Projects連携モード有効時のみ、StatusとStageを自動変更。

Status決定: Open Questionsに自信度低(🔴)あり → poc / なし → implement Stage: 常に To Start

issync projects set-status "$ISSUE_URL" "<poc または implement>"
issync projects set-stage "$ISSUE_URL" "To Start"

ラベル自動付与: ラベル自動付与モード有効時、Statusに応じたラベルを付与。

# Status=poc の場合
gh issue edit $ISSUE_NUMBER --add-label "issync:poc"

# Status=implement の場合
gh issue edit $ISSUE_NUMBER --add-label "issync:implement"

エラー時: ステップ2のエラーハンドリングと同様。

出力フォーマット

全ステップ完了後、以下の形式で作業成果を要約して表示：

## Plan Phase Complete

**Progress Document**: {issue_url}

### Key Discoveries
- {ステップ3で発見した技術スタック、既存パターン、テスト戦略を2-3項目で具体的に要約}
- {参考になる既存実装やアーキテクチャの特徴}
- {プロジェクト固有の重要な制約や慣習}

### Open Questions ({総数N}件{自信度低がある場合: " | 🔴自信度低: {M}件"})
{Open Questionsの主要なテーマや懸念点を1-2文で要約。自信度低の項目がある場合は、POC検証が必要な理由と検証項目を明記}

### Next Steps
1. Review document on GitHub and resolve Open Questions
2. {自信度低の項目がある場合} Start POC to validate {具体的な検証項目（例: "performance impact of polling approach", "feasibility of GraphQL mutation")}
   {ISSYNC_LABELS_AUTOMATION=trueの場合} `issync:poc` label added → Devin will auto-start
3. {自信度低の項目がない場合} Create sub-issues with `/issync:create-sub-issue` and begin implementation
   {ISSYNC_LABELS_AUTOMATION=trueの場合} `issync:implement` label added → Devin will auto-start

**Status**: plan → {自信度低あり: poc / なし: implement} (Stage: To Start)

重要: Key Discoveriesは実際の調査結果を具体的に記載。Open Questionsは優先レビュー論点を明示。Next Stepsは状況に応じて2または3を選択。

重要な注意事項

環境変数確認: ステップ1を必ず実行し、モードフラグに基づいて各ステップの処理を制御する
コードベース調査: ステップ4を省略しない（省略すると不要なOpen Questionsが大量発生）
Open Questions: コードで確認可能な情報は記載しない、5-10項目に絞る

補足: ステートマシンとの統合

ワークフロー（自信度低の項目がある場合）:

GitHub Issue作成（Status: plan, Stage: To Start）
   ↓
/plan実行開始 → ステップ1: 環境変数確認 & モード決定
   ↓
ステップ2: Stage自動変更（To Start → In Progress）※GitHub Projects連携モード有効時のみ
   ↓
ステップ3-6: コードベース調査 → 進捗ドキュメント作成 → 自信度低(🔴)の項目を検出
   ↓
ステップ7: issync push → Stage自動変更（In Progress → To Review）※GitHub Projects連携モード有効時のみ
   ↓
ステップ8: Status & Stage自動変更（Status: plan → poc, Stage: To Review → To Start）※GitHub Projects連携モード有効時のみ
   ↓
ステップ8: issync:pocラベル自動付与 ※ラベル自動付与モード有効時のみ
   ↓
人間レビュー → {ラベルなし} POC開始（Devin起動）
             → {ラベルあり} Devin自動起動

ワークフロー（自信度低の項目がない場合）:

GitHub Issue作成（Status: plan, Stage: To Start）
   ↓
/plan実行開始 → ステップ1: 環境変数確認 & モード決定
   ↓
ステップ2: Stage自動変更（To Start → In Progress）※GitHub Projects連携モード有効時のみ
   ↓
ステップ3-6: コードベース調査 → 進捗ドキュメント作成 → 自信度低の項目なし
   ↓
ステップ7: issync push → Stage自動変更（In Progress → To Review）※GitHub Projects連携モード有効時のみ
   ↓
ステップ8: Status & Stage自動変更（Status: plan → implement, Stage: To Review → To Start）※GitHub Projects連携モード有効時のみ
   ↓
ステップ8: issync:implementラベル自動付与 ※ラベル自動付与モード有効時のみ
   ↓
人間レビュー → {ラベルなし} サブissue作成 → 実装開始（Devin起動）
             → {ラベルあり} Devin自動起動

重要:

ステップ1で2つのモード（Projects連携、ラベル自動付与）の有効/無効を決定
Projects連携モード有効時のみ、StatusとStageを自動変更（人間の手動変更不要）
Status変更で次フェーズを明示（poc = PoC検証、implement = サブissue作成・実装）
ラベル自動付与モード有効時、Statusに応じたラベルを自動付与（issync:poc または issync:implement）→ Devinが自動起動

12 KiB Raw Permalink Blame History Unescape Escape