From fb4d2ff5f168e508c25a62edd52c17f724c76fa6 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:40:07 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 11 + README.md | 3 + commands/compact-progress-document.md | 212 ++++++++ commands/complete-sub-issue.md | 193 ++++++++ commands/create-sub-issue.md | 217 ++++++++ commands/implement.md | 163 ++++++ commands/plan.md | 281 +++++++++++ commands/poc.md | 193 ++++++++ commands/resolve-questions.md | 110 ++++ commands/review-poc.md | 689 ++++++++++++++++++++++++++ commands/understand-progress.md | 100 ++++ plugin.lock.json | 77 +++ 12 files changed, 2249 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/compact-progress-document.md create mode 100644 commands/complete-sub-issue.md create mode 100644 commands/create-sub-issue.md create mode 100644 commands/implement.md create mode 100644 commands/plan.md create mode 100644 commands/poc.md create mode 100644 commands/resolve-questions.md create mode 100644 commands/review-poc.md create mode 100644 commands/understand-progress.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..78f8e03 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "issync", + "description": "矛盾解消駆動開発のためのツール群: plan実行(/plan)、POC調査(/poc)、POCレビュー(/review-poc)、進捗ドキュメント圧縮(/compact-progress-document)、Open Questions解消(/resolve-questions)、実装フェーズ(/implement)、タスクのサブissue化と順序管理(/create-sub-issue)、サブissue完了(/complete-sub-issue)、進捗ドキュメント読み込み(/understand-progress)", + "version": "0.10.0", + "author": { + "name": "MH4GF" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..861d8e8 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# issync + +矛盾解消駆動開発のためのツール群: plan実行(/plan)、POC調査(/poc)、POCレビュー(/review-poc)、進捗ドキュメント圧縮(/compact-progress-document)、Open Questions解消(/resolve-questions)、実装フェーズ(/implement)、タスクのサブissue化と順序管理(/create-sub-issue)、サブissue完了(/complete-sub-issue)、進捗ドキュメント読み込み(/understand-progress) diff --git a/commands/compact-progress-document.md b/commands/compact-progress-document.md new file mode 100644 index 0000000..1415d36 --- /dev/null +++ b/commands/compact-progress-document.md @@ -0,0 +1,212 @@ +# /compact-progress-document: 進捗ドキュメント圧縮コマンド + +あなたは矛盾解消駆動開発を実践するAIエージェントです。このコマンドは、進捗ドキュメントファイルが大きくなりすぎた際に、情報量を保持したまま文量を削減する圧縮を行います。 + +## 使用方法 + +```bash +/compact-progress-document # state.ymlから選択 +/compact-progress-document https://github.com/owner/repo/issues/123 # Issue URL指定 +/compact-progress-document 123 # Issue番号指定 +``` + +## 実行フロー + +### 1. 進捗ドキュメントの理解 + +まず、`/issync:understand-progress`コマンドを内部で呼び出して、進捗ドキュメントを読み込みます。 + +```bash +/issync:understand-progress +``` + +引数が指定されている場合はそのまま渡し、指定されていない場合は引数なしで実行します。 + +### 2. 進捗ドキュメントの読み込みと分析 + +指定された進捗ドキュメントファイルを読み込み、以下を分析してください： +- 総行数 +- 各セクションの行数 +- 重複している内容 +- 完了済みのPhaseとタスク +- 解決済みのOpen Questions +- 矛盾する記述 + +### 3. バージョン比較とprogress-document-template.mdとの比較 + +#### a) バージョンヘッダーの確認 + +進捗ドキュメントの先頭行から、バージョンヘッダーを確認してください： +```markdown + +``` + +**バージョンヘッダーが存在しない場合**: +``` +⚠️ 進捗ドキュメントにバージョンヘッダーがありません。 +Version 1 (2025-10-15) 以前のテンプレートを使用している可能性があります。 + +バージョンヘッダーを追加しますか？ (y/n) +``` + +承認された場合、以下を追加： +```markdown + +``` + +#### b) progress-document-template.mdのバージョン取得 + +公式テンプレート（`https://raw.githubusercontent.com/MH4GF/issync/refs/heads/main/docs/progress-document-template.md`）を取得し、バージョンヘッダーを確認してください。 + +#### c) バージョン比較 + +進捗ドキュメントのバージョンと、progress-document-template.mdのバージョンを比較してください： + +**バージョンが同じ場合**: 通常の圧縮処理を続行 + +**バージョンが古い場合**: マイグレーション提案を表示 +``` +⚠️ 進捗ドキュメントのバージョンが古い可能性があります +現在のバージョン: Version [X] ([YYYY-MM-DD]) +最新のバージョン: Version [Y] ([YYYY-MM-DD]) + +マイグレーションが必要です。 +詳細: docs/MIGRATION_GUIDE.md または https://raw.githubusercontent.com/MH4GF/issync/refs/heads/main/docs/MIGRATION_GUIDE.md + +マイグレーションを実行しますか？ (y/n) +``` + +**マイグレーション実行時**: +1. MIGRATION_GUIDE.mdを参照（ローカルに存在すればローカル、なければGitHubから取得） +2. 該当するバージョン間のマイグレーション手順を確認 +3. 自動マイグレーション可能な変更を適用 +4. 手動確認が必要な変更をユーザーに通知 + +#### d) テンプレート準拠性の確認 + +以下を確認・修正してください： +- セクション順序がテンプレートと一致しているか → 不一致の場合は並び替え +- 各セクションの「📝 記入タイミング」「✍️ 記入内容」ガイダンスがテンプレートと完全一致しているか → 不一致の場合はテンプレートの文言に更新 +- 不要なカスタムセクションがないか → **テンプレートに存在しないセクションは削除**（内容が重要な場合は適切なセクションに統合） + +**テンプレート準拠の価値**: +ガイダンスをテンプレートと完全一致させることで、AIエージェントが「今何を書くべきか」を迷わず判断できるようになり、作業効率が大幅に向上します。カスタムセクションの削除により、情報の一元化とメンテナンス性が改善されます。 + +### 4. 圧縮処理 + +以下の観点で圧縮を実行してください： + +#### a) テンプレート準拠性の修正（最優先） +- **セクション順序をテンプレートに合わせる**: 並び順が異なる場合は、テンプレート通りの順序に並び替え +- **ガイダンス文言をテンプレートと完全一致させる**: 「📝 記入タイミング」「✍️ 記入内容」の文言をテンプレートからコピーして上書き（内容の微妙な差異も統一） +- **不要なカスタムセクションを削除**: テンプレートに存在しないセクションは削除し、重要な内容は適切なセクションに統合 +- **ガイダンスに沿わない記述を適切なセクションに移動**: 例えば「Specification」に書くべき内容が「Purpose」に書かれている場合は移動 + +#### b) 重複情報の削減 +- 同じ内容が複数セクションで繰り返されている場合、参照形式に変換 +- 例: 「詳細はSpecificationセクション参照」 + +#### c) 解決済みOpen Questionsの整理 +- ✅ 解決済みマークのついたOpen Questionsを「解決済み（アーカイブ）」セクションに移動 +- または、Decision Logへの参照のみ残して削除 + +#### d) 完了済みPhaseの簡潔化 +- 完了したPhaseのタスク詳細をOutcomes & Retrospectivesに統合 +- Work Planでは要約のみ残す + +例: +```markdown +### Phase 1: ✅ 完了 (2025-10-14) +**ゴール**: [簡潔な説明] +**成果**: Outcomes & Retrospectives 参照 +``` + +#### e) 冗長な説明の簡潔化 +- 長文を箇条書きに変換 +- 過剰に詳細な説明を要約 +- 大きな図表や詳細仕様は外部ファイル化を提案（実行はしない） + +#### f) 完了済みタスクの整理 +- Tasksセクションから✅完了済みタスクを削除 +- 完了内容はOutcomes & Retrospectivesに統合されているか確認 + +### 5. 矛盾検出と報告 + +以下のような矛盾を検出し、ユーザーに報告してください： +- Decision Logで矛盾する決定（例: 「A採用」→後で「Bに変更」だが撤回理由が不明確） +- Work PlanとTasksセクションで内容が一致しない +- Acceptance CriteriaとValidation & Acceptance Criteriaで基準が異なる +- Open QuestionsとDecision Logで同じ質問が両方に存在 + +矛盾を発見した場合、Open Questionsに追加する提案をしてください。 + +### 6. 圧縮後の進捗ドキュメントを保存して同期 + +圧縮処理を適用した進捗ドキュメントを保存し、GitHub Issueに同期してください。 + +```bash +issync push +``` + +## 出力形式 + +圧縮完了後、以下の形式でレポートを出力してください： + +```markdown +## /issync:compact-progress-document 実行結果 + +### バージョン情報 +- 進捗ドキュメント: Version [X] ([YYYY-MM-DD]) +- progress-document-template.md: Version [Y] ([YYYY-MM-DD]) +- マイグレーション: [実施した/不要/スキップ] + +### 圧縮サマリー +- 文量: [元の行数]行 → [圧縮後の行数]行（[削減率]%削減） +- 削除した重複: [件数]箇所 +- 整理したOpen Questions: [件数]件（解決済み） +- 簡潔化したPhase: Phase [X]（[行数]行 → [行数]行） +- 完了タスク削除: [件数]件 + +### 適用した圧縮処理 +- ✅ バージョン比較・マイグレーション + - バージョンヘッダー追加: [実施/不要] + - テンプレートバージョンアップ: [実施/不要] + - マイグレーション手順適用: [件数]項目 +- ✅ テンプレート準拠性の修正 + - セクション順序の並び替え: [変更有無] + - ガイダンス文言の完全一致: [更新したセクション数]箇所 + - カスタムセクション削除: [削除したセクション名]（[件数]件） +- ✅ 重複情報の削減（[件数]箇所） +- ✅ 解決済みOpen Questions整理（[件数]件） +- ✅ 完了Phase簡潔化（Phase [X]） +- ✅ 冗長な説明の簡潔化（[件数]箇所） +- ✅ 完了タスク削除（[件数]件） + +### ⚠️ 矛盾検出 +[矛盾が検出された場合のみ表示] +- 矛盾1: [詳細な説明] + - 場所: [セクション名] + - 推奨対応: [対処方法] +- 矛盾2: [詳細な説明] + - 場所: [セクション名] + - 推奨対応: [対処方法] + +### 次のアクション +- [ ] 圧縮結果をレビュー +- [ ] 矛盾が検出された場合は解消してください +- [ ] マイグレーションで手動確認が必要な変更を確認してください（該当する場合） +``` + +## 重要な注意事項 + +1. **バージョン比較を最初に実施**: 進捗ドキュメントのバージョンを必ず確認し、古い場合はマイグレーションを提案すること +2. **テンプレート準拠が最優先**: セクション順序とガイダンス文言は必ずテンプレートと完全一致させること。これによりAIエージェントの作業効率が大幅に向上する +3. **カスタムセクションは削除**: テンプレートに存在しないセクションは削除し、重要な内容は適切なセクションに統合すること +4. **情報量は変えない**: 削減するのは文量のみで、情報は失わないこと +5. **矛盾は報告のみ**: 矛盾を勝手に解消せず、ユーザーに報告して判断を仰ぐこと +6. **外部ファイル化は提案のみ**: 大きな図表や詳細仕様の外部ファイル化は実行せず、提案のみ行うこと +7. **issync同期**: 圧縮完了後は必ず`issync push`を実行してGitHub Issueに同期すること + +## 実行を開始 + +それでは、上記のフローに従って進捗ドキュメントの圧縮を開始してください。 diff --git a/commands/complete-sub-issue.md b/commands/complete-sub-issue.md new file mode 100644 index 0000000..2da55f9 --- /dev/null +++ b/commands/complete-sub-issue.md @@ -0,0 +1,193 @@ +--- +description: サブissue完了時に親issueの進捗ドキュメントを自動更新。PRから学びを抽出し振り返りを生成・加筆、Open Questionsを解決、Follow-up Issuesを4分類処理、矛盾を検出・解消。完了後はissync removeで同期設定を自動削除 +--- + +# /complete-sub-issue: サブissue完了オペレーション + +サブissue完了時に親issueの進捗ドキュメントを自動更新。詳細は「実行ステップ」参照。 + +## 使用方法 + +```bash +/complete-sub-issue <サブissue URL> +# 例: /complete-sub-issue https://github.com/MH4GF/issync/issues/456 +``` + +**引数**: +- `サブissue URL` (必須): 完了したサブissueのGitHub URL + +## 前提条件 + +- `ISSYNC_GITHUB_TOKEN`環境変数が設定されている +- `gh` CLIがインストール済み +- 未初期化issueは自動初期化（詳細は「エラーハンドリング」参照） + +**運用フロー**: `create-sub-issue` → 開発 → `complete-sub-issue` → Critical着手 → 次のサブissue作成 + +## 実行ステップ + +### ステップ1: サブissue情報をフェッチと親issue番号の取得 + +GitHub Sub-issues API (`gh api /repos/{owner}/{repo}/issues/{issue_number}/parent`) で親issue番号を取得。API失敗時はissue bodyから抽出。無効URL/親issue不在時はエラー表示。 + +### ステップ2: サブissueの進捗ドキュメントを読み込み + +`issync status <サブissue URL>`で登録状況を確認。以下を抽出（エラーハンドリングは「エラーハンドリング」セクション参照）: +- **Outcomes & Retrospectives**: 実装内容、発見や学び +- **Open Questions**: 未解決の論点 +- **Follow-up Issues**: 将来対応事項 + +### ステップ3: コード変更の取得と深い分析 + +**情報源優先順位**: PR情報 → コミット情報 → ユーザーに確認 + +#### 3.1 関連PRまたはコミットを特定 + +```bash +# PRの自動取得（Timeline Events APIから） +gh api repos/{owner}/{repo}/issues/{issue_number}/timeline \ + --jq '.[] | select(.event == "cross-referenced" and .source.issue.pull_request)' +``` +複数ある場合は最新のマージ済みPRを優先。PRが見つからない場合はコミットSHAを使用。 + +#### 3.2 コード変更の分析 + +```bash +# PRがある場合 +gh pr view --json title,body,commits,reviews,comments +gh pr diff + +# コミットのみの場合 +git show +``` + +#### 3.3 学びの抽出 + +修正コミット、CI失敗、レビュー指摘から改善機会を推論（型エラー→型定義強化、Lint違反→ルール明文化、テスト失敗→カバレッジ拡充など） + +#### 3.4 振り返り本文の処理 + +以下の構造で生成または加筆: +- 実装内容（事実ベース） +- 改善の機会と気づき +- 5 Whys分析 +- 改善策（Lint/型/テスト/ドキュメント） +- 技術的な発見や学び + +#### 3.5 Follow-up Issuesの抽出 + +PR/コミットから未対応事項を抽出し、優先度を自動分類（詳細はステップ7参照）。 + +### ステップ4: サブissueのOpen Questions処理 + +既存情報（Decision Log、PR実装、振り返り）から可能な限り解決。`/issync:resolve-questions`で自動解決し、未解決はFollow-up Issuesへ移行。 + +**処理原則**: 保守的に推論（False positive回避）、部分的な解決も記録 + +### ステップ5: 親issueの進捗ドキュメントを特定 + +`issync status <親issue URL>`で進捗ドキュメント情報を取得。未登録時は自動初期化。初期化失敗時は処理中断。 + +### ステップ6: 親issueのOutcomes & Retrospectivesを更新 + +```markdown +**サブタスク完了 (YYYY-MM-DD): [サブissueタイトル] (#[番号])** +- [実装内容サマリー] +- [主な発見や学び（あれば）] +``` + +### ステップ6.5: 親issueのOpen Questions解決チェック + +サブissueの情報から親issueのOpen Questionsを解決できるか推論し、`/issync:resolve-questions`で自動解決。回答には出典を明記（例: `サブissue #[番号]で解決`）。 + +**処理原則**: 保守的に推論（False positive回避）、部分的な解決も記録 + +### ステップ7: Follow-up Issuesの4分類処理 + +| 分類 | 処理 | キーワード例 | +|------|------|-------------| +| **Critical Improvements** | 即座に`/issync:create-sub-issue`実行 | lint追加、型定義強化、CI改善 | +| **Project Improvements** | 提案（完了サマリーで提示） | CLAUDE.md、テンプレート | +| **Open Questions** | 親issueのOpen Questionsに追加 | 検討、調査、トレードオフ | +| **Feature Enhancements** | 提案（自動作成なし） | 機能追加、スコープ外 | + +**重要**: Critical Improvementsは自動作成。親issueのFollow-up Issuesへの転記は禁止。 + +### ステップ8: サブissueをclose + +openの場合のみ実行。コメントにPR/コミット情報を含める。 + +### ステップ9: issync remove実行 + +`issync remove --issue <サブissue URL>`で同期設定を削除。失敗時も処理継続。 + +### ステップ10: GitHub Projects Status変更 + +`ISSYNC_GITHUB_PROJECTS_NUMBER`環境変数が設定されている場合のみ実行: + +```bash +issync projects set-status "$SUB_ISSUE_URL" "Done" +``` + +認証エラー時は`gh auth refresh -s project`を案内。 + +### ステップ11: 親issue進捗ドキュメントの矛盾検出と解消 + +**検出対象**: Decision Logの矛盾、Work PlanとTasksの不一致、Open QuestionsとDecision Logの重複、サブissue追加による新たな矛盾 + +**処理**: +- 自動解消: Open Questions重複→削除、完了Phaseタスク→削除 +- 手動確認: Open Questionsに追加 + +**処理原則**: 保守的に実行、矛盾解消履歴をDecision Logに記録 + +### ステップ12: GitHub Issueへの同期 + +`issync push`で親issueの変更を同期。 + +### ステップ13-14: 完了通知と親issueコメント + +出力フォーマットに従いサマリーを出力し、同内容を親issueにコメント投稿。コメント投稿失敗時は警告のみ（処理継続）。 + +## 出力フォーマット + +```markdown +## /issync:complete-sub-issue 実行結果 + +### 完了したサブissue +- #[サブissue番号]: [サブissueタイトル] / 親: #[親issue番号] + +### 更新内容 +- ✅ コード変更: [PR/コミット]分析、改善機会[X]件検出 +- ✅ 振り返り: 5 Whys分析完了、Follow-up Issues[Y]件抽出 +- ✅ Open Questions: サブissue[X]件解決/[Y]件移行、親issue[Z]件解決/[W]件追加 +- ✅ 親issue更新: Outcomes & Retrospectives追加 +- ✅ 後処理: close[✅/⚠️]、remove[✅/⚠️]、Projects[✅/⚠️] +- ✅ 矛盾検出: [自動解消X件/要確認Y件/なし] +- ✅ 同期: issync push完了 + +### 🎯 Critical (自動作成済み) +- #[番号]: [Critical] [タスク名] + +### 💡 Recommended / 📋 Feature Enhancements +- [タスク名] → `/issync:create-sub-issue "[タスク名]"` + +### 次のアクション +1. 🎯 Critical着手 → 2. 💡 Recommended検討 → 3. 親issue確認 → 4. Feature検討 +``` + +## エラーハンドリング + +| 状況 | 処理 | +|------|------| +| 未登録issue | `issync init`で自動初期化 | +| 親issue初期化失敗 | 処理中断 | +| サブissue初期化失敗 | 「記載なし」として続行 | +| 無効URL/親issue不在 | エラー表示 | +| すでにclosed | close処理スキップ | + +## 実行例 + +```bash +/issync:complete-sub-issue https://github.com/MH4GF/issync/issues/124 +``` diff --git a/commands/create-sub-issue.md b/commands/create-sub-issue.md new file mode 100644 index 0000000..637d516 --- /dev/null +++ b/commands/create-sub-issue.md @@ -0,0 +1,217 @@ +--- +description: 新規タスクをGitHub Issueとして作成し、親issueとのリンクを自動管理。進捗ドキュメントのTasksセクションは不使用 +--- + +# /issync:create-sub-issue: サブissue作成オペレーション + +新規タスクをGitHub Issueとして作成し、以下を自動化： +1. タスク概要入力（インタラクティブ: 1つ / 引数: 複数可） +2. 親issue情報取得（`.issync/state.yml`） +3. LLMによるタイトル・本文生成 +4. Issue作成（`ISSYNC_LABELS_AUTOMATION=true`の場合、`issync:plan`ラベル自動付与） +5. Sub-issues API連携（親issue紐づけ + 順序維持） + +## コンテキスト + +**横断的オペレーション** - どのステートでも実行可能（plan、poc、architecture-decision、implement） + +**設計原則**: +- GitHub Sub-issuesを完全なSSOTとする（進捗ドキュメントのTasksセクション不使用） +- ユーザー入力は簡潔な概要のみ（LLMが適切なタイトル・本文を自動生成） +- Sub-issues APIで親issueと自動リンク、順序維持 + +## 使用方法 + +```bash +/issync:create-sub-issue # インタラクティブモード（1つ） +/issync:create-sub-issue "概要1" "概要2" # 引数モード（複数可） +``` + +**入力例**: "Status変更時の自動アクション" "コマンド実装" など簡潔でOK + +**推奨ワークフロー**: +- 基本: 1つずつ作成 → `/issync:plan`で詳細化 → 必要に応じて孫issue作成 +- 複数の独立タスクが明確な場合のみ引数モードで一括作成 + +## 前提条件 + +- `.issync/state.yml`存在（`issync init`完了済み） +- `ISSYNC_GITHUB_TOKEN`環境変数設定 +- `gh` CLIインストール済み +- `ISSYNC_LABELS_AUTOMATION=true`設定時: リポジトリに`issync:plan`ラベルが存在すること + +## 実行ステップ + +### ステップ1: 環境変数確認 & モード決定 + +ラベル自動付与の有効化状態を確認し、以降のステップで使用するモードフラグを設定。 + +**環境変数**: +```bash +ISSYNC_LABELS_AUTOMATION # ラベル自動付与モード ("true" で有効) +``` + +**モード決定**: +- **ラベル自動付与**: `ISSYNC_LABELS_AUTOMATION="true"`で有効 (未設定時はステップ6のラベル付与をスキップ) + +**出力**: 設定状態をユーザーに表示 +```markdown +## Environment Check +**Label Automation**: {有効/無効} +``` + +### ステップ2: タスク概要の入力 + +- **インタラクティブモード**: プロンプトでタスク概要を1つ入力 +- **引数モード**: コマンドライン引数から複数取得 + +### ステップ3: 親issue情報を取得 + +`issync status <親issue URL>`を実行し、以下を取得: +- `issue_url`: 親issueのURL +- `local_file`: 進捗ドキュメントのパス + +### ステップ4: 親issueコンテキスト抽出 + +進捗ドキュメント全体を読み込み、LLMが以下を理解: +- Purpose/Overview: 目的、コアバリュー +- Context & Direction: 背景、設計哲学 +- Specification: 仕様、アーキテクチャ（存在時） + +### ステップ5: タイトル・本文生成 + +**タイトル**: 「{動詞} + {対象}」形式、10-30文字、親issueのスタイルに合わせる + +**本文テンプレート**: +```markdown +Part of #{親issue番号} + +## 目的 +{タスクの具体的な目的（1-2文）} + +## 背景 +{親issueから関連情報を抽出・要約} + +## 完了条件 +- [ ] {完了条件（3-5項目）} +- [ ] コードレビュー完了 +- [ ] ドキュメント更新完了 + +## 関連 +- 親issue: #{親issue番号} +- 詳細: [親issueを見る]({親issueのURL}) +``` + +### ステップ5.5: 既存issueの重複チェック + +類似タスクが既に存在しないか検索し、重複作成を防ぐ。 + +**検索実行**: +```bash +gh search issues --repo {owner}/{repo} "{キーワード1} {キーワード2}" \ + --json number,title,url,state,labels --limit 5 +``` +- LLMがタイトルから主要キーワード抽出（動詞・名詞中心、2-3語） +- 検索対象: リポジトリ内全issue（open/closed）、親issueのsub-issues優先 + +**類似issue検出時の確認**: +``` +⚠️ 類似する既存issueが見つかりました: +#123 [open]: Status変更時の自動通知機能を実装 + +このまま新規issue作成を続けますか？ (y/n) +``` +- `y`: ステップ6へ進む +- `n`: キャンセル、既存issue利用を推奨 + +**エラー時**: 警告表示後、検索スキップして続行 + +### ステップ6: ユーザー確認 + +生成したタイトル・本文プレビューを提示し、承認後に作成（`y`/`n`） + +### ステップ7: Issue作成とSub-issues連携 + +**ラベル付与**: +ステップ1で確認したラベル自動付与モードが有効な場合、`--label "issync:plan"`を付与してissue作成。 +未設定の場合はラベルなしで作成。 + +**処理フロー**: +```bash +PREV_SUB_ISSUE_ID="" +for i in "${!GENERATED_TITLES[@]}"; do + TITLE="${GENERATED_TITLES[$i]}" + BODY="${GENERATED_BODIES[$i]}" + + # ISSYNC_LABELS_AUTOMATIONに応じてラベル付与 + ISSUE_URL=$(gh issue create --repo {owner}/{repo} --title "$TITLE" --body "$BODY") + ISSUE_NUMBER=$(echo $ISSUE_URL | grep -o '[0-9]*$') + SUB_ISSUE_ID=$(gh api /repos/{owner}/{repo}/issues/$ISSUE_NUMBER --jq .id) + + # Sub-issueとして紐づけ + gh api --method POST /repos/{owner}/{repo}/issues/{親issue番号}/sub_issues \ + -F "sub_issue_id=$SUB_ISSUE_ID" + + # 2つ目以降は順序設定 + if [ -n "$PREV_SUB_ISSUE_ID" ]; then + gh api --method PATCH /repos/{owner}/{repo}/issues/{親issue番号}/sub_issues/priority \ + --input - << EOF +{ + "sub_issue_id": $SUB_ISSUE_ID, + "after_id": $PREV_SUB_ISSUE_ID +} +EOF + fi + + PREV_SUB_ISSUE_ID=$SUB_ISSUE_ID +done +``` + +### ステップ8: GitHub Projects Status設定（オプション） + +`gh issue edit`でStatus=planを設定（利用不可時は手動設定を案内） + +## 出力フォーマット + +完了後、以下を表示: +- 作成されたサブissueリスト（URL、タイトル） +- Sub-issues紐づけ結果 +- `ISSYNC_LABELS_AUTOMATION=true`の場合: + - `issync:plan`ラベル付与確認 + - **auto-planワークフロー自動実行**のため、手動`/issync:plan`実行不要 + - GitHub Actionsタブで実行状況確認可能 +- 未設定の場合: + - 手動で`/issync:plan`実行が必要 + +## 重要な注意事項 + +**必須要件**: +- ステップ1で環境変数を確認し、モードフラグを設定（以降のステップで参照） +- 親issueの進捗ドキュメント全体読み込み（`.issync/state.yml`のlocal_fileパス使用） +- タイトル・本文はLLM生成、ユーザー確認必須 +- gh CLI使用、内部ID使用（`gh api .../issues/{番号} --jq .id`） +- `ISSYNC_LABELS_AUTOMATION=true`の場合、`issync:plan`ラベル自動付与 + - auto-planワークフローが自動トリガーされ、進捗ドキュメントが自動作成される + +**Sub-issues API**: +- 処理順: Issue作成 → 内部ID取得 → Sub-issues紐づけ → 順序設定（`after_id`） +- JSON payload使用、エラー時は処理継続して報告 + +**その他**: +- 進捗ドキュメント非変更（Tasksセクション削除済み、タスク管理はGitHub Sub-issuesに完全移行） +- エラーハンドリング: `state.yml`/`gh` CLI不在時は終了、Issue作成失敗時は部分成功も記録 + +## 実行例 + +**インタラクティブモード**: `/issync:create-sub-issue` +1. タスク概要入力: "Status変更時の自動アクション" +2. LLMがタイトル生成（例: "Status変更時の自動アクション機能を設計"） +3. ユーザー確認 → Issue作成 +4. `ISSYNC_LABELS_AUTOMATION=true`の場合: + - `issync:plan`ラベル付き → auto-planワークフロー自動実行 → 進捗ドキュメント作成 + +**引数モード**: `/issync:create-sub-issue "自動アクション設計" "/issync:create-sub-issue実装"` +1. 複数タスクを一括作成 +2. Sub-issues順序設定で作成順序維持 +3. `ISSYNC_LABELS_AUTOMATION=true`の場合: + - 各サブissueに対しauto-planワークフロー順次実行 diff --git a/commands/implement.md b/commands/implement.md new file mode 100644 index 0000000..e1e7395 --- /dev/null +++ b/commands/implement.md @@ -0,0 +1,163 @@ +--- +description: 進捗ドキュメントに基づいた実装を進め、作業中は継続的にドキュメントを更新 +--- + +# /issync:implement: 実装フェーズ自動化コマンド + +あなたは矛盾解消駆動開発を実践するAIエージェントです。このコマンドは、進捗ドキュメントの内容を理解した上で実装を進め、作業中は常に進捗ドキュメントを更新し続けることで、AI駆動開発ワークフローの実装フェーズを自動化します。 + +## 使用方法 + +```bash +/issync:implement https://github.com/owner/repo/issues/123 # Issue URL指定 +/issync:implement 123 # Issue番号指定 +``` + +## コンテキスト + +このコマンドは「矛盾解消駆動開発」ワークフローの**implementフェーズ**で使用します： +- **実行タイミング**: `implement`ステート（アーキテクチャ決定後、本実装フェーズ） +- 進捗ドキュメントの`Specification / 仕様`セクションに基づいて実装を進める +- 実装中の意思決定や進捗を常に進捗ドキュメントに記録（Single Source of Truth維持） +- GitHub Actions（Claude Code Action）からの実行を想定 + +## 前提条件 + +プロジェクト全体の前提条件は`README.md`を参照。このコマンド固有の前提条件: +- 進捗ドキュメントが既に作成されている（`/issync:plan`実行済み） +- アーキテクチャ決定が完了している（`Specification / 仕様`セクションが記入済み） + +## 実行フロー + +### ステップ1: 進捗ドキュメントの理解 + +**既に進捗ドキュメントを理解している場合は、このステップをスキップして直接ステップ2に進んでください。** + +進捗ドキュメントをまだ読み込んでいない場合は、`/issync:understand-progress`コマンドを内部で呼び出して、進捗ドキュメントを読み込みます。 + +```bash +/issync:understand-progress +``` + +このコマンドに指定された引数（Issue URLまたはIssue番号）をそのまま渡してください。 + +### ステップ2: リグレッション確認（実装前の必須チェック） + +新しい実装を始める前に、既存のテストが通ることを確認してください。プロジェクト固有のテストコマンドは`CLAUDE.md`を参照。 + +**テスト失敗時**: 新機能の実装より既存機能の修復を優先。進捗ドキュメントの`Open Questions`に問題を記録し、修正してから次に進みます。 + +### ステップ3: 実装の開始 + +進捗ドキュメントの`Specification / 仕様`セクションに従って、実装を開始してください。 + +**実装の進め方:** +1. 必要なファイルをReadツールで読み込む +2. コードの変更をEditツールまたはWriteツールで行う +3. テストコードの追加・更新（`Validation & Acceptance Criteria`に基づく） +4. 実装が完了したら、テストを実行して動作確認 + +### ステップ4: 進捗ドキュメントの継続的更新（**最重要**） + +実装を進める中で、**必ず進捗ドキュメントを継続的に更新してください**。 + +**更新タイミング:** +- 機能実装完了時 → `Discoveries & Insights`に発見を記録 +- 新しい疑問発生時 → `Open Questions`に追加 +- Follow-up事項発生時 → `Follow-up Issues`に追加 +- 仕様明確化時 → `Specification / 仕様`を更新 + +**更新方法:** Editツールでセクション単位で更新し、`issync push`で同期。 + +### ステップ5: テストの実行 + +実装が完了したら、プロジェクトのテストやチェックを実行してください： +- 単体テストの実行 +- 型チェックの実行 +- リンター・フォーマッターの実行 + +プロジェクト固有のコマンドは`CLAUDE.md`や`package.json`を参照。テスト失敗時はエラーを修正して再実行。 + +### ステップ6: 変更のコミット + +機能の実装が完了し、全てのテストが通ったら、変更をコミットしてください。 + +**Git Safety Protocol**: +- **NEVER update the git config** +- **NEVER run destructive/irreversible git commands** (like push --force, hard reset, etc) unless the user explicitly requests them +- **NEVER skip hooks** (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it +- **Avoid git commit --amend** unless user explicitly requested or adding edits from pre-commit hook +- Before amending: ALWAYS check authorship (`git log -1 --format='%an %ae'`) + +**コミット手順**: + +1. 事前確認と変更のステージング（並列実行）: +```bash +git status # 変更ファイルを確認 +git diff # 変更内容の詳細を確認 +git log --oneline -10 # 既存のコミットメッセージスタイルを確認 +git add <変更したファイル> # 変更をステージング +``` + +2. 詳細なコミットメッセージでコミット（**HEREDOC形式必須**）: +```bash +git commit -m "$(cat <<'EOF' +<1行目: 変更の性質と要約（例: feat: 〜実装, fix: 〜修正）> + +- <変更内容1（何を・なぜを含める）> +- <変更内容2> +- テスト: <実行したテストの内容> +- 進捗ドキュメント: <更新したセクション> + +🤖 Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude +EOF +)" +``` + +3. コミット後の確認: +```bash +git status # "nothing to commit"を確認 +``` + +**注意事項**: +- 実行していないテストや未完了の実装を記載しない +- 秘密情報（.env、credentials.jsonなど）をコミットしない + +### ステップ7: セッション終了（クリーンな状態の維持） + +コンテキストが不足してきた場合や作業が一区切りついた場合、**作業途中であっても**必ず以下を実行してクリーンな状態で終了してください。 + +**終了手順**: + +1. **進捗ドキュメントを更新して同期**: + - 未解決事項を`Open Questions`に記録 + - 次のセッションへの引き継ぎ事項を`Discoveries & Insights`に記録 + - 今セッションで実装した内容を`Specification / 仕様`または`Discoveries & Insights`に記録 + - `issync push`で同期 + +2. **ステップ5のテストを再実行**してパスを確認 + +3. **ステップ6の手順で変更をコミット**（作業途中でもWIPコミット可） + +4. **リモートにプッシュ**: `git push` + +**必須要件**（全て満たすこと）: +- ✅ 全ての変更がコミット済み（`git status`が"nothing to commit"） +- ✅ 進捗ドキュメントがリモートと同期済み（`issync push`完了） +- ✅ テストが全て通っている（壊れた状態で終了しない） +- ✅ 変更がリモートにプッシュ済み +- ✅ 引き継ぎ事項が進捗ドキュメントに記録済み + +## 重要な注意事項 + +1. **進捗ドキュメント駆動**: `Specification / 仕様`に基づいて実装 +2. **継続的更新**: 実装中は常に進捗ドキュメントを更新（最重要） +3. **テスト駆動**: `Validation & Acceptance Criteria`に基づいてテスト追加・実行 +4. **issync連携**: 作業後は`issync push`で同期 +5. **Status変更なし**: GitHub Projects Statusの変更は行わない（PRマージ時に自動変更） + +## 実行を開始 + +それでは、上記のフローに従って実装を開始してください。 diff --git a/commands/plan.md b/commands/plan.md new file mode 100644 index 0000000..a62a2a6 --- /dev/null +++ b/commands/plan.md @@ -0,0 +1,281 @@ +--- +description: planフェーズのプロセスを標準化し、コードベース調査を強制することで高品質な進捗ドキュメント作成を実現 +--- + +# /issync:plan: plan実行ワークフロー + +進捗ドキュメント（`.issync/docs/plan-{番号}-{slug}.md`）を初期作成するコマンドです。以下の8ステップを自動化します： + +1. 環境変数確認 & モード決定 +2. 前提条件確認 & ファイル名決定 & issync init実行 & Stage設定（In Progress） +3. GitHub Issue内容の確認 +4. コードベース調査（CRITICAL） +5. 基本セクションの記入 +6. Open Questionsの精査 +7. issync pushで同期 & Stage更新（To Review） +8. 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連携とラベル自動付与の有効化状態を確認し、以降のステップで使用するモードフラグを設定。 + +**環境変数**: +```bash +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のラベル付与をスキップ) + +**出力**: 設定状態をユーザーに表示 +```markdown +## Environment Check +**GitHub Projects Integration**: {有効/無効} - Project Number: {番号}, Owner Type: {タイプ} +**Label Automation**: {有効/無効} +``` + +### ステップ2: 前提条件確認 & ファイル名決定 & issync init & Stage設定 + +**ファイル名決定**: +1. Issue URLを確認（例: `https://github.com/owner/repo/issues/123`） +2. 番号とslugを抽出・生成 + +**初期化**: +- **ケース A**: issync未初期化 → `issync init --file .issync/docs/plan-{番号}-{slug}.md` +- **ケース B**: 進捗ドキュメント不存在 → 新規sync追加または `issync pull --issue ` +- **ケース C**: 準備完了 → 次へ + +**Stage設定**: Projects連携モード有効時のみ、Stage→`In Progress`に設定。失敗時も処理継続。 + +```bash +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フェーズで検証必須** + +**フォーマット例**: +```markdown +**Q1: [質問タイトル]** +- [質問の詳細] + +**検討案:** +- **[選択肢A]（推奨 自信度:高🟢）**: [説明 + 推奨理由] +- **[選択肢B]**: [説明] + - トレードオフ: [制約] + +**Q2: [別の質問（自信度低の場合）]** +**検討案:** +- **[選択肢C]（推奨 自信度:低🔴）**: [説明] + - **⚠️ PoC必須**: [検証項目] +``` + +### ステップ7: GitHub Issueへの同期 & Stage更新 + +進捗ドキュメントをGitHub Issueに同期。 + +```bash +issync push +``` + +**Stage更新**: Projects連携モード有効時のみ、Stage→`To Review`に設定。失敗時も処理継続。 + +```bash +issync projects set-stage "$ISSUE_URL" "To Review" +``` + +### ステップ8: GitHub Projects Status & Stage自動変更 & ラベル付与 + +Projects連携モード有効時のみ、StatusとStageを自動変更。 + +**Status決定**: Open Questionsに自信度低(🔴)あり → `poc` / なし → `implement` +**Stage**: 常に `To Start` + +```bash +issync projects set-status "$ISSUE_URL" "" +issync projects set-stage "$ISSUE_URL" "To Start" +``` + +**ラベル自動付与**: ラベル自動付与モード有効時、Statusに応じたラベルを付与。 + +```bash +# Status=poc の場合 +gh issue edit $ISSUE_NUMBER --add-label "issync:poc" + +# Status=implement の場合 +gh issue edit $ISSUE_NUMBER --add-label "issync:implement" +``` + +**エラー時**: ステップ2のエラーハンドリングと同様。 + +## 出力フォーマット + +全ステップ完了後、以下の形式で作業成果を要約して表示： + +```markdown +## 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が自動起動 diff --git a/commands/poc.md b/commands/poc.md new file mode 100644 index 0000000..799c5fb --- /dev/null +++ b/commands/poc.md @@ -0,0 +1,193 @@ +--- +description: 自信度を上げるための調査・検証を中心に行い、発見を進捗ドキュメントに記録 +--- + +# /issync:poc: POC調査フェーズ自動化コマンド + +あなたは矛盾解消駆動開発を実践するAIエージェントです。このコマンドは、進捗ドキュメントの内容を理解した上で調査・検証を進め、発見した知見を継続的にドキュメントに記録することで、AI駆動開発ワークフローのPOCフェーズを自動化します。 + +## 使用方法 + +```bash +/issync:poc # state.ymlから選択 +/issync:poc https://github.com/owner/repo/issues/123 # Issue URL指定 +/issync:poc 123 # Issue番号指定 +``` + +## コンテキスト + +このコマンドは「矛盾解消駆動開発」ワークフローの**pocステート**で使用します： +- **実行タイミング**: `poc`ステート（自信度が低く、技術的検証が必要なフェーズ） +- 進捗ドキュメントの`Open Questions`や`Context & Direction`に基づいて調査・検証を進める +- **実装は破棄される前提** - コードよりも知見の獲得が目的 +- 調査中の発見や疑問を常に進捗ドキュメントに記録（Single Source of Truth維持） +- 最終的にPOC PRを作成し、人間がレビュー後に`/issync:review-poc`で知見を整理 + +## 前提条件 + +プロジェクト全体の前提条件は`README.md`を参照。このコマンド固有の前提条件: +- 進捗ドキュメントが既に作成されている（`/issync:plan`実行済み） +- `Open Questions`に調査すべき論点が記載されている +- または、技術的な不確実性がある状態 + +## 実行フロー + +### ステップ1: 進捗ドキュメントの理解 + +まず、`/issync:understand-progress`コマンドを内部で呼び出して、進捗ドキュメントを読み込みます。 + +```bash +/issync:understand-progress +``` + +引数が指定されている場合はそのまま渡し、指定されていない場合は引数なしで実行します。 + +### ステップ2: 進捗ドキュメントの確認 + +特に`Open Questions`（調査すべき論点）と`Context & Direction`を確認してください。 + +### ステップ3: 調査・検証の開始 + +`Open Questions`に基づいて調査・検証を開始してください。 + +**進め方:** +1. 技術調査（ドキュメント、API仕様、既存コード） +2. 実装による検証（小規模なコード作成、動作確認） +3. 発見を随時ドキュメントに記録 + +**重要**: 目的は知見の獲得です。コード品質は優先度が低いです。 + +### ステップ4: 進捗ドキュメントの継続的更新（**最重要**） + +調査を進める中で、**必ず進捗ドキュメントを継続的に更新してください**。 + +**更新タイミング:** +- 技術的事実を発見 → `Discoveries & Insights`に記録 +- 新しい疑問が発生 → `Open Questions`に追加 +- 既存の質問が解決 → `Open Questions`から削除し、`Decision Log`に記録 +- Follow-up事項発生 → `Follow-up Issues`に追加 +- Acceptance Criteriaの達成/未達成が判明 → `Discoveries & Insights`に根拠を記録 + +**更新方法:** Editツールでセクション単位で更新し、`issync push`で同期。進捗ドキュメントはSingle Source of Truthであり、POCの知見を共有するための唯一の情報源です。 + +**Discoveries & Insights記入例:** +```markdown +## Discoveries & Insights + +**YYYY-MM-DD: [発見のタイトル]** +- **発見**: [発見した技術的事実 - できる/できない、制約、特性など] +- **学び**: [この発見が実装にどう影響するか] +- **検証方法**: [どのように確認したか - コード実装、ドキュメント調査など] +``` + +**Open Questions更新例:** +```markdown +## Open Questions + +### Q1: ~~解決済み: XXXは可能か？~~ + +**解決**: YYYによって実現可能と判明（YYYY-MM-DD） + +--- + +### Q2: 新たな疑問: ZZZの最適な設定値は？ + +**背景**: POCでAAAを実装したところ、BBBの設定値によって挙動が変わることが判明 +``` + +### ステップ5: テストの実行（オプショナル） + +必要に応じて軽量なテスト実行。全テスト合格は必須ではありません。 + +```bash +bun test <検証したい機能のテストファイル> +``` + +### ステップ6: 進捗ドキュメントの最終同期 + +調査・検証が完了したら、進捗ドキュメントの変更をGitHub Issueに同期してください。 + +```bash +issync push +``` + +### ステップ7: Git commitとPR作成 + +POCの実装と発見を記録するため、PRを作成します。 + +```bash +git add <変更したファイル> +git commit -m "poc: + +🤖 Generated with [Claude Code](https://claude.com/claude-code) + +Co-Authored-By: Claude " + +git push origin <ブランチ名> + +gh pr create --title "POC: <検証内容>" --body "$(cat <<'EOF' +## POCの目的 +<調査・検証した内容> + +## 主な発見 + + +## 次のステップ +- [ ] PRレビュー後、`/issync:review-poc`で知見を整理 +- [ ] アーキテクチャ決定後、このPRはクローズされます + +🤖 Generated with [Claude Code](https://claude.com/claude-code) +EOF +)" +``` + +**重要**: このPRは人間がレビューするための差分確認用です（マージしません）。 + +## 出力フォーマット + +```markdown +## /issync:poc 実行結果 + +✅ POC調査が完了しました +**Issue**: | **ファイル**: + +### 調査内容と主な発見 +- [調査項目と発見のサマリー] + +### 進捗ドキュメント更新 +- Discoveries & Insights: [X]件 +- Open Questions: [Y]件追加/[Z]件解決 + +### 次のアクション +- [ ] POC PR () をレビュー +- [ ] `/issync:review-poc `で知見を整理 +- [ ] アーキテクチャ決定後、PRをクローズ +``` + +## 重要な注意事項 + +1. **調査優先**: コードの品質よりも知見の獲得を優先 +2. **継続的更新**: 調査中は常に進捗ドキュメントを更新（最重要） +3. **破棄前提**: 実装は破棄される前提で、自由に試行錯誤 +4. **issync連携**: 作業後は`issync push`で同期 +5. **PR作成**: 人間が差分を確認できるようPRを作成（マージしない、後でクローズ） +6. **テストはオプショナル**: 全テスト合格は必須ではない +7. **Status変更なし**: GitHub Projects Statusの変更は行わない + +## ワークフロー + +``` +/issync:poc → 調査・検証 → ドキュメント更新 → POC PR作成 + ↓ +人間がPRレビュー + ↓ +/issync:review-poc → 知見整理 → Decision Log推奨案 + ↓ +人間が意思決定・承認 → PRクローズ → Status変更(`implement`) + ↓ +/issync:implement（本実装） +``` + +## 実行を開始 + +それでは、上記のフローに従ってPOC調査を開始してください。 diff --git a/commands/resolve-questions.md b/commands/resolve-questions.md new file mode 100644 index 0000000..8914fad --- /dev/null +++ b/commands/resolve-questions.md @@ -0,0 +1,110 @@ +--- +description: 進捗ドキュメント内のOpen Questionsを解消し、Decision LogやSpecificationセクションを自動更新。ユーザーがARGUMENTS形式で各質問への意思決定を入力し、LLMがそれを進捗ドキュメントに反映 +--- + +# /issync:resolve-questions: Open Questions解消コマンド + +進捗ドキュメントのOpen Questionsを解消し、Decision LogとSpecificationを自動更新します。詳細な実行ステップは後述の「実行ステップ」セクションを参照してください。 + +## 使用方法 + +```bash +/issync:resolve-questions +Q1-2: 推奨案 +Q3: <ユーザーの意思決定を自然文で記載> +Q4: 推奨案 +Q5-6: 推奨案 +``` + +**引数形式**: +- 各行に `Q[番号または範囲]: [意思決定内容]` を記載 +- 範囲指定可能: `Q1-3: 推奨案` で Q1, Q2, Q3 すべてに適用 +- 意思決定内容: + - `推奨案` または `推奨` と記載した場合、Open Questionsの検討案から推奨マーク付きの案を採用 + - それ以外の場合、記載内容をそのまま決定内容として使用 + +## 前提条件 + +- 進捗ドキュメントが作成済み（`/issync:plan`実行済み） +- Open Questionsセクションに未解決の質問が存在 +- `ISSYNC_GITHUB_TOKEN`環境変数が設定済み + +## 実行ステップ + +### ステップ1-3: 準備 + +1. `/understand-progress`で進捗ドキュメントを読み込む +2. Open Questionsセクションから未解決の質問を抽出（取り消し線がないもの） +3. ユーザー入力を解析： + - 各行から質問番号と意思決定内容を抽出 + - 範囲指定（`Q1-3`）は範囲内すべてに適用 + - `推奨案`/`推奨`の場合、検討案から推奨マーク付き案を自動抽出 + - その他の場合、入力内容をそのまま使用 + +### ステップ4: Open Questionsセクションの更新 + +各質問を以下の形式で更新： +- 質問タイトルを取り消し線（`~テキスト~`）でマーク +- 直後に` ✅ 解決済み (YYYY-MM-DD)`を追加 +- 質問文と検討案は保持 +- 末尾に`**決定**: <内容>`を追記 + +### ステップ5: Decision Logセクションへの記録 + +関連する質問をグループ化し、以下のフォーマットでDecision Logに追加： +- **YYYY-MM-DD: <決定タイトル>** +- **採用**: <採用案> +- **理由**: 箇条書き +- **比較検討した候補**: 候補と却下理由 +- **トレードオフ**: 採用案の制約 + +Open Questionsの検討案から情報を抽出し、不足分はユーザー入力から推論してください。 + +### ステップ6: Specificationセクションの更新 + +解決内容から仕様を推論し、Specificationセクションを更新： +- コマンドインターフェース、データフォーマット、アーキテクチャ、動作フローなど +- 既存仕様に追記（矛盾がある場合は既存を更新） +- 見出し（###）で構造化 +- 仕様が推論できない場合はスキップ + +### ステップ7-8: 更新と同期 + +1. Editツールで進捗ドキュメントを更新（Open Questions、Decision Log、Specification） + - Editツールは1回1箇所のみ更新可能（複数回呼び出す） + - `old_string`に十分なコンテキストを含める +2. `issync push`でGitHub Issueに同期 + +## 出力フォーマット + +完了後、以下を出力： +- 解消した質問リスト（Q番号、タイトル、決定内容） +- 更新内容（Open Questions、Decision Log、Specificationの件数） +- 次のアクション（確認事項、残タスク） + +## 重要な注意事項 + +- ユーザーがARGUMENTSで意思決定を明示（自動推論しない） +- `推奨案`指定時は検討案から推奨マーク付き案を自動抽出 +- 一貫フォーマット：取り消し線 + "✅ 解決済み (YYYY-MM-DD)" +- Decision Logに「採用」「理由」「比較検討した候補」「トレードオフ」を含める +- Specification更新は自律的に仕様を推論 +- 作業後は`issync push`で同期 + +## エラーハンドリング + +- **Open Questions不在**: メッセージ表示して終了 +- **質問番号不在**: 警告表示してスキップ（他の処理は継続） +- **推奨案不在**: 検討案の最初の項目を採用（検討案もない場合はユーザー入力を使用） +- **issync push失敗**: エラー表示、ローカル更新済みを通知、手動実行を案内 + +## 実行例・運用フロー + +```bash +/issync:resolve-questions +Q1-2: 推奨案 +Q3: コマンドのARGUMENTSとしてユーザーが意思決定を各Qごとに行う +Q4-6: 推奨案 +``` + +**運用フロー**: `/issync:plan`で進捗ドキュメント作成 → 開発を進める → 回答が明確になったら`/issync:resolve-questions`で解消 → すべて解消したら次フェーズへ diff --git a/commands/review-poc.md b/commands/review-poc.md new file mode 100644 index 0000000..fa066b6 --- /dev/null +++ b/commands/review-poc.md @@ -0,0 +1,689 @@ +--- +description: POC実装の結果をレビューし、人間の意思決定のための材料を整理する +--- + +# /issync:review-poc: POCレビューワークフロー + +あなたはユーザーの `.issync/docs/plan-*.md` ファイルのPOCレビューフェーズをサポートしています。このコマンドは以下の11ステップのワークフローを自動化します： + +1. Stage設定（In Progress） +2. POC PR URLを受け取り、PR情報を取得 +3. Discoveries & Insightsを参照 +4. **Acceptance Criteriaの検証（達成/未達成を明確化）** +5. **Discoveries & Insightsへの追記** +6. **Open Questionsへの論点追加（強化）** +7. **Decision Log推奨案の記入（人間の最終決定を前提）** +8. Specification / 仕様の記入（オプショナル） +9. POC PRをクローズ +10. issync pushで同期（必要な場合） +11. Stage更新（To Review） + +**重要**: このコマンドは**人間の意思決定のための材料を提供する**ことが目的です。最終的なアーキテクチャ決定は人間が行います。 + +## コンテキスト + +このコマンドは「矛盾解消駆動開発」ワークフローの**architecture-decisionステート**で使用されます： +- POC実装が完了し、PRが作成されている状態から開始 +- POCで得た技術的知見（実現可能性、複雑性、制約）を分析 +- Acceptance Criteriaの達成状況を確認 +- 未達成項目の理由を分析し、Open Questionsに論点を追加 +- Decision Log推奨案を記入（最終決定は人間が行う） +- 人間がレビュー・承認後、手動でStatusを`implement`に変更 + +## 前提条件 + +実行前に必要なものは以下です： +- [ ] **現在のGitHub Issue Statusが `architecture-decision` であることを確認**（手動確認） +- [ ] POC実装が完了し、PRが作成されている +- [ ] `ISSYNC_GITHUB_TOKEN` 環境変数が設定されている +- [ ] 進捗ドキュメントファイルがローカルに存在する + +**重要**: このコマンドは`architecture-decision`ステートで実行されることを前提としています。適切なタイミングで実行する責任はユーザーにあります。 + +## 実行ステップ + +### ステップ1: Stage設定（AI作業開始） + +`!env ISSYNC_GITHUB_PROJECTS_NUMBER`が設定されている場合のみ、`gh project item-edit`でStage→`In Progress`に設定。失敗時も作業継続（警告のみ）。 + +環境変数: +- `ISSYNC_GITHUB_PROJECTS_NUMBER`: プロジェクト番号（例: `1`） +- `ISSYNC_GITHUB_PROJECTS_OWNER_TYPE`: `user` または `org`（デフォルト: `user`） + +**Stage 設定コマンド**: + +```bash +issync projects set-stage "$ISSUE_URL" "In Progress" +``` + +--- + +### ステップ2: POC PR URLの受け取りとPR情報取得 + +#### 2.1 POC PR URLの受け取り + +ユーザーにPOC PR URLを確認してください： + +``` +POC PR URLを教えてください（例: https://github.com/owner/repo/pull/123） +``` + +#### 2.2 PR情報の取得 + +POC PRから以下の情報を取得します： + +```bash +# PR詳細を取得 +gh pr view --json title,body,state,commits,comments + +# PR diffを取得 +gh pr diff +``` + +**収集する情報**: +- PR title +- PR description（body） +- State（open/closed） +- Commits（コミット一覧） +- Comments（レビューコメント、議論） +- Diff（変更内容） + +**PRが既にクローズ済みの場合**: +- ⚠️ 警告を表示：「このPRは既にクローズされています。レビュー情報の記入のみを実行します。」 +- ステップ8（PRクローズ）をスキップして続行 + +#### 2.3 PRに対応するissueの特定 + +1. **PR本文の解析** + - 本文中のissue言及を理解（"Resolves:", "Fixes #123", "Part of #456" など、自然言語として柔軟に解釈） + - 完全URL形式（`https://github.com/.../issues/番号`）を優先、`#番号`はPRと同一リポジトリと判断 + +2. **複数/未検出時の処理** + - 複数issue: ユーザーに選択させる + - 未検出: issue URLまたは番号の入力を促す + +3. **使用** + - 進捗ドキュメント検索: `.issync/docs/plan-{issue番号}-*.md` + - GitHub Projects操作（Stage更新） + +--- + +### ステップ3: Discoveries & Insightsの参照 + +進捗ドキュメントの`Discoveries & Insights`セクションを読み、POC実装中に発見された技術的制約・複雑性を確認： + +```markdown +## Discoveries & Insights + +**YYYY-MM-DD: [発見のタイトル]** +- **発見**: [発見した技術的事実] +- **学び**: [この発見が実装にどう影響するか] +``` + +これらの発見事項とPR情報を統合し、Acceptance Criteria検証の根拠とします。 + +--- + +### ステップ4: Acceptance Criteriaの検証（大幅強化） + +**目的**: POCがAcceptance Criteriaを満たしているかを詳細に検証し、未達成項目の理由を明確化する。 + +#### 検証プロセス + +1. 現在のAcceptance Criteriaを読む +2. POC PR diffとコミット、Discoveries & Insightsを参照 +3. 各項目について達成/未達成を判定 +4. 未達成の場合、その理由を分析（技術的制約? 優先度? スコープ外?） + +#### 検証結果の記入フォーマット + +進捗ドキュメントに新しいセクション「POC検証結果」を追加します： + +```markdown +## POC検証結果 + +### Acceptance Criteria達成状況 + +**達成した項目:** +- ✅ [受け入れ基準1] + - 検証方法: [どのように確認したか] + - PR参照: [関連するコミットやdiff] + +- ✅ [受け入れ基準2] + - 検証方法: [どのように確認したか] + - PR参照: [関連するコミットやdiff] + +**未達成の項目:** +- ❌ [受け入れ基準3] + - 理由: [なぜ達成できなかったか - 技術的制約、実現不可能性、優先度など] + - 影響: [この未達成が本実装にどう影響するか] + - 対応方針: [Open Questionに追加 / Acceptance Criteria調整 / Phase 2に延期 など] + +**スコープ外と判断した項目:** +- ⚠️ [受け入れ基準4] + - 理由: [なぜスコープ外と判断したか] + - 将来の対応: [Phase 2で検討 / 別Issueで対応 など] +``` + +#### 例 + +```markdown +## POC検証結果 + +### Acceptance Criteria達成状況 + +**達成した項目:** +- ✅ watch daemonがファイル変更を検知できる + - 検証方法: chokidarによるファイル監視を実装、ローカルファイル変更時に自動pushを確認 + - PR参照: コミット abc123 "Add chokidar file watcher" + +- ✅ リモートポーリングが動作する + - 検証方法: setIntervalで30秒間隔のポーリングを実装、remote変更時に自動pullを確認 + - PR参照: コミット def456 "Add remote polling with setInterval" + +**未達成の項目:** +- ❌ 1秒以内の同期を実現する + - 理由: GitHub API rate limit制約（5000 req/hour = 最短7.2秒間隔）により、1秒間隔のポーリングは不可能 + - 影響: 同期遅延が発生する（現在のPOCでは30秒間隔） + - 対応方針: Open Questionに「最適なポーリング間隔」を追加し、人間が判断 + +**スコープ外と判断した項目:** +- ⚠️ Webhook対応 + - 理由: GitHub Webhook設定の複雑さ（ngrok等の外部ツール必要）、Phase 1では優先度低 + - 将来の対応: Phase 2で検討（より迅速な同期が必要と判明した場合） +``` + +#### 未達成項目への対応 + +未達成項目が簡単に解消できない場合、**必ずOpen Questionsに論点を追加**してください（ステップ5）。 + +--- + +### ステップ5: Discoveries & Insightsへの追記 + +POC実装で新たに発見した技術的事実を追記します。 + +**追記内容（状況に応じて必要なものを記載）**: +- 技術的制約（API rate limit、パフォーマンス特性など） +- 実現可能性の確認（「できる」「できない」の明確化） +- エッジケース、想定外の動作 +- ライブラリ・ツールの特性 +- 複雑性の見積もり + +#### 追記フォーマット + +```markdown +## Discoveries & Insights + +**YYYY-MM-DD: [発見のタイトル]** +- **発見**: [発見した技術的事実] +- **学び**: [この発見が実装にどう影響するか] +- **POC参照**: [関連するコミットやPR] +``` + +#### 例 + +```markdown +## Discoveries & Insights + +**2025-10-15: GitHub API rate limitの実測値** +- **発見**: GitHub API rate limitは5000 req/hourであり、1秒間隔のポーリングは不可能（最短7.2秒間隔） +- **学び**: Acceptance Criteriaの「1秒以内の同期」は技術的に実現不可能。ポーリング間隔を調整する必要がある +- **POC参照**: コミット abc123 "Test rate limit with 1s polling" + +**2025-10-15: chokidarの安定性** +- **発見**: chokidarはクロスプラットフォームで安定動作し、ファイル変更を確実に検知できる +- **学び**: ローカルファイル監視にはchokidarが適している +- **POC参照**: コミット def456 "Add chokidar file watcher" + +**2025-10-15: Pull→Pushループのリスク** +- **発見**: Remote pullでファイル更新→chokidarが検知→pushが発生する無限ループが発生 +- **学び**: Grace period（猶予期間）を設けることで回避可能。pullから10秒間はpushを抑制する実装が必要 +- **POC参照**: コミット ghi789 "Add grace period to prevent pull→push loop" +``` + +--- + +### ステップ6: Open Questionsへの論点追加（大幅強化） + +**目的**: 未達成のAcceptance Criteriaや技術的な選択肢について、人間が意思決定するための論点を明確化する。 + +#### 論点追加のガイドライン + +以下のような場合に論点を追加します： +- ❌ Acceptance Criteriaが未達成（簡単に解消できない） +- 🤔 技術的な選択肢が複数ある（Option A vs B） +- ⚖️ トレードオフがある（パフォーマンス vs 複雑さ） +- 🔍 不確実性がある（スケーラビリティ、ユーザー体験など） + +#### 論点記入フォーマット + +```markdown +## Open Questions + +### Q[番号]: [質問のタイトル] + +**背景**: [なぜこの質問が生まれたか - POCで判明した事実] + +**選択肢:** +- Option A: [選択肢1] + - メリット: [利点] + - デメリット: [欠点] + - 実装難易度: [高/中/低] + +- Option B: [選択肢2] + - メリット: [利点] + - デメリット: [欠点] + - 実装難易度: [高/中/低] + +**推奨**: [AIの推奨案（あれば）と根拠] + +**決定者**: [人間が決定] / **決定期限**: [必要であれば] +``` + +#### 例 + +```markdown +## Open Questions + +### Q1: GitHub API rate limitを考慮した最適なポーリング間隔は？ + +**背景**: POCで1秒間隔のポーリングは不可能と判明（rate limit: 5000 req/hour = 最短7.2秒間隔） + +**選択肢:** +- Option A: 30秒間隔（120 req/hour） + - メリット: 安全マージン大（rate limitの2.4%のみ使用）、複数プロジェクト同時watchでも余裕あり + - デメリット: 同期遅延が最大30秒発生、ユーザー体験がやや悪い + - 実装難易度: 低（POCで既に実装済み） + +- Option B: 10秒間隔（360 req/hour） + - メリット: より迅速な同期（最大10秒遅延）、ユーザー体験向上 + - デメリット: rate limitの7.2%使用、複数プロジェクトで制約あり + - 実装難易度: 低（setIntervalの値変更のみ） + +- Option C: 設定可能にする（デフォルト30秒） + - メリット: ユーザーが自分の環境に合わせて調整可能 + - デメリット: 設定の複雑さ増加、rate limit超過のリスク + - 実装難易度: 中（state.ymlにpoll_interval追加） + +**推奨**: Option C（設定可能、デフォルト30秒） +- 理由: ユーザーによって同時watch数が異なるため、柔軟性が重要 +- rate limit超過時のエラーハンドリングを実装すれば安全 + +**決定者**: [人間が決定] + +--- + +### Q2: Pull→Pushループ防止のgrace periodは何秒が適切か？ + +**背景**: POCでgrace period 10秒を実装したが、最適値は未検証 + +**選択肢:** +- Option A: 5秒 + - メリット: ローカル変更への反応が早い + - デメリット: pullが遅い場合にループのリスク + +- Option B: 10秒（POC実装値） + - メリット: 安全性高い + - デメリット: ローカル変更後の同期が最大10秒遅延 + +- Option C: ポーリング間隔 × 1.5倍（動的調整） + - メリット: ポーリング間隔に応じて最適化 + - デメリット: 実装がやや複雑 + +**推奨**: Option B（10秒固定） +- 理由: シンプルで安全、Phase 1では十分 + +**決定者**: [人間が決定] +``` + +--- + +### ステップ7: Decision Log推奨案の記入 + +**重要**: このステップで記入するのは**推奨案**であり、**最終決定ではありません**。人間がレビュー・承認してから確定します。 + +POCの知見を基に、以下の形式でDecision Log推奨案を記入します。 + +#### Decision Log推奨案フォーマット + +```markdown +## Decision Log + +> **注**: 以下は `/review-poc` による推奨案です。最終決定は人間が行ってください。 +> +> **承認プロセス**: 各推奨案をレビューし、承認/修正/却下を決定してください。 + +### 推奨案 YYYY-MM-DD: [決定事項のタイトル] + +- **推奨技術/アプローチ**: [推奨する技術・アーキテクチャ・アプローチ] +- **根拠**: [POCの結果に基づく理由、技術的制約、実現可能性] +- **トレードオフ**: [採用しなかった選択肢とその理由]（オプション） +- **最終決定**: [ ] 承認待ち / [ ] 承認済み / [ ] 却下 + +--- + +### 推奨案 YYYY-MM-DD: [決定事項のタイトル2] + +... +``` + +#### 記入内容（状況に応じて必要なものを記載） + +- **技術選定**: ライブラリ、フレームワーク、ツール +- **アーキテクチャパターン**: デザインパターン、システム構成 +- **データモデル**: スキーマ、データ構造 +- **API設計**: エンドポイント、インターフェース +- **テスト戦略**: テストレベル（単体/統合/E2E）、テストツール + +#### 例 + +```markdown +## Decision Log + +> **注**: 以下は `/review-poc` による推奨案です。最終決定は人間が行ってください。 +> +> **承認プロセス**: 各推奨案をレビューし、承認/修正/却下を決定してください。 + +### 推奨案 2025-10-15: Watch daemonの実装方針 + +- **推奨技術**: `chokidar`ライブラリによるファイル監視 + `setInterval`によるリモートポーリング +- **根拠**: POCで検証した結果、chokidarは安定性が高く、クロスプラットフォーム対応が容易。setIntervalによるポーリングはシンプルで理解しやすい +- **トレードオフ**: Webhookベースのアプローチは設定の複雑さ（ngrok等の外部ツール必要）から初期実装では見送りを推奨。Phase 2で検討 +- **最終決定**: [ ] 承認待ち + +--- + +### 推奨案 2025-10-15: ポーリング間隔 + +- **推奨設定**: 設定可能にする（デフォルト30秒） +- **根拠**: GitHub API rate limit制約から、30秒間隔が安全。ユーザーによって同時watch数が異なるため、柔軟性が重要 +- **トレードオフ**: 固定値（30秒）の方がシンプルだが、ユーザーのニーズに対応できない +- **最終決定**: [ ] 承認待ち（Open Question Q1で議論中） + +--- + +### 推奨案 2025-10-15: Pull→Pushループ防止策 + +- **推奨実装**: Grace period 10秒（pullから10秒間はpushを抑制） +- **根拠**: POCで動作確認済み、シンプルで安全 +- **トレードオフ**: 動的調整（ポーリング間隔 × 1.5倍）の方が柔軟だが、実装が複雑 +- **最終決定**: [ ] 承認待ち +``` + +--- + +### ステップ8: Specification / 仕様の記入（オプショナル） + +**重要**: このステップは**POCで明確になった部分のみ**記入してください。不確実な部分は記入しません。 + +POCで検証したアーキテクチャを基に、以下の形式でSpecification / 仕様セクションを記入します。 + +#### 記入内容（状況に応じて必要なものを記載） + +- **システム仕様**: 機能仕様、動作仕様（POCで確認済みのもののみ） +- **アーキテクチャ図**: mermaid図などで視覚化（オプション） +- **API設計**: インターフェース、エンドポイント +- **データモデル**: スキーマ、データ構造 +- **設計方針**: 実装上の重要な考慮事項 + +#### Specification記入フォーマット + +```markdown +## Specification / 仕様 + +> **注**: 以下はPOCで確認された仕様です。不確実な部分は記載していません。 + +### [サブシステム名・機能名] + +**概要**: [機能の概要] + +**仕様**: +- [仕様項目1]（POCで確認済み） +- [仕様項目2]（POCで確認済み） + +**実装方針**: +- [実装上の考慮事項1] +- [実装上の考慮事項2] +``` + +#### 例（mermaid図を含む場合） + +```markdown +## Specification / 仕様 + +> **注**: 以下はPOCで確認された仕様です。不確実な部分は記載していません。 + +### Watch Daemon アーキテクチャ + +**概要**: ファイル変更の監視とGitHub Issue commentへの自動同期（POCで実装確認済み） + +**アーキテクチャ図**: +```mermaid +graph TD + A[Watch Daemon] --> B[File Watcher - chokidar] + A --> C[Remote Poller - setInterval] + B --> D[Push on Change] + C --> E[Pull on Remote Update] + D --> F[Grace Period Check] + F -->|10秒経過| G[GitHub API Push] +``` + +**仕様**: +- ファイル変更検知: chokidarによるリアルタイム監視（POCで動作確認） +- リモート変更検知: 30秒間隔でGitHub API polling（設定可能、デフォルト30秒） +- 同期方向: 双方向（local → remote, remote → local） +- Grace period: pullから10秒間はpushを抑制（ループ防止） + +**実装方針**: +- Daemon processとして実行、PIDを.issync/state.ymlに記録 +- Graceful shutdown（SIGTERM/SIGINT）に対応 +- エラーリトライ: 3回まで、指数バックオフ（POCでは未実装、本実装で追加） +``` + +**記入しない例**: +- POCで検証していない機能（エラーリトライの詳細など） +- 不確実な仕様（「将来的にWebhook対応する可能性」など） + +--- + +### ステップ9: POC PRのクローズ + +POC PRをクローズします： + +```bash +gh pr close --comment "POC完了。レビュー結果を進捗ドキュメントに記録しました。人間がレビュー・承認後、implementフェーズに進みます。" +``` + +**PRが既にクローズ済みの場合**: +- このステップをスキップ（ステップ1で検知済み） + +--- + +### ステップ10: GitHub Issueへの同期 + +進捗ドキュメントの変更をGitHub Issueに同期します。 + +```bash +issync push +``` + +--- + +### ステップ11: Stage更新（レビュー待ち） + +`!env ISSYNC_GITHUB_PROJECTS_NUMBER`が設定されている場合のみ、`gh project item-edit`でStage→`To Review`に設定。失敗時も作業継続（警告のみ）。 + +**Stage 設定コマンド**: + +```bash +issync projects set-stage "$ISSUE_URL" "To Review" +``` + +**重要**: 人間承認後、Status→`implement`、Stage→`To Start`を手動で変更。 + +--- + +## 出力フォーマット + +全ステップ完了後、以下の形式でサマリーを提供： + +```markdown +## /issync:review-poc 実行結果 + +### 完了したステップ +- ✅ ステップ1: POC PR情報取得（PR #123: [PR Title]） +- ✅ ステップ2: Discoveries & Insights参照（[X]項目を確認） +- ✅ ステップ3: Acceptance Criteria検証（達成: [Y]項目、未達成: [Z]項目） +- ✅ ステップ4: Discoveries & Insights追記（[W]個の発見を追加） +- ✅ ステップ5: Open Questions追加（[V]個の論点を追加） +- ✅ ステップ6: Decision Log推奨案記入（[U]個の推奨案を記録） +- ✅ ステップ7: Specification / 仕様記入（オプショナル） +- ✅ ステップ8: POC PRクローズ（PR #123） +- ✅ ステップ9: GitHub Issueへの同期完了（issync push） + +### Acceptance Criteria検証結果 +- ✅ 達成: [達成した項目のリスト] +- ❌ 未達成: [未達成の項目のリスト] +- ⚠️ スコープ外: [スコープ外と判断した項目のリスト] + +### 追加されたOpen Questions +1. Q[番号]: [質問のタイトル] +2. Q[番号]: [質問のタイトル] +... + +### Decision Log推奨案 +1. [推奨案1のタイトル] - [ ] 承認待ち +2. [推奨案2のタイトル] - [ ] 承認待ち +... + +### 次のアクション（重要） +- [ ] **進捗ドキュメントの内容（POC検証結果、Open Questions、Decision Log推奨案）をレビューしてください** +- [ ] **Open Questionsを検討し、意思決定を行ってください** +- [ ] **Decision Log推奨案を承認/修正/却下してください** +- [ ] **承認後、GitHub Projects Statusを手動で`implement`に変更してください** +- [ ] **implementのチェックリストを確認し、本実装を開始してください** +``` + +--- + +## 重要な注意事項 + +### Acceptance Criteria検証について + +- **全ての項目を明確に分類**してください: 達成/未達成/スコープ外 +- **未達成の理由を具体的に記述**してください: 「実現できなかった」ではなく、「GitHub API rate limit制約により1秒間隔は不可能」のように +- **簡単に解消できない未達成項目は必ずOpen Questionに追加**してください + +### Discoveries & Insights追記について + +- **POCで新たに発見した事実のみ記述**してください +- **「できる」「できない」を明確化**してください: 曖昧な表現を避ける +- **POC参照（コミットハッシュ、PR diff）を必ず記載**してください + +### Open Questions追加について + +- **選択肢を具体的に記述**してください: メリット・デメリット・実装難易度を明示 +- **AIの推奨案は提示するが、最終決定は人間に委ねる**ことを明記 +- **複数の論点がある場合、優先度を示す**ことも有用（オプション） + +### Decision Log推奨案について + +- **「推奨案」であることを明記**してください: 「最終決定は人間が行う」を必ず記載 +- **承認チェックボックス `[ ] 承認待ち` を必ず含める** +- **POCの結果を具体的に記述**してください: 「検証した結果、実現可能と判明」ではなく、「chokidarでファイル監視を実装し、30秒間隔のポーリングで安定動作を確認」のように + +### Specification / 仕様について + +- **POCで確認された部分のみ記載**してください: 不確実な部分は記載しない +- **mermaid図を活用**してください: アーキテクチャは視覚化すると理解しやすい +- **このステップはオプショナル**です: 仕様が明確でない場合はスキップしても構いません + +### PRクローズについて + +- **PRが既にクローズされている場合でも続行**してください（レビュー情報の記入は実行） +- **PRクローズ時のコメント**は、次のステップ（人間のレビュー）を明記してください + +### 人間のレビュープロセス + +このコマンド完了後、**必ず人間が以下をレビュー・承認してください**： + +1. **POC検証結果**: Acceptance Criteria達成状況は正確か？ +2. **Open Questions**: 論点は明確か？選択肢は網羅されているか？ +3. **Decision Log推奨案**: 推奨案は合理的か？承認/修正/却下を決定 +4. **承認後**: GitHub Projects Statusを手動で`implement`に変更 + +**重要**: このコマンドは**Status自動変更を行いません**。人間の承認後、手動で変更してください。 + +### エラーハンドリング + +| ケース | 対応 | +|--------|------| +| POC PR URLが無効 | ❌ エラー終了（"無効なPR URLです"） | +| POC PRが既にクローズ済み | ⚠️ 警告を出して続行（レビュー情報記入のみ実行） | +| POCの知見が不足（Discoveries & Insightsが空） | ⚠️ 警告を出して続行（最小限の記入を実施） | +| Acceptance Criteriaが全て未達成 | ⚠️ 警告を出して続行（全てのOpen Questionsに追加） | + +**注意**: +- このコマンドに渡されたPRは全てPoC PRとして扱います（PoC PR判定ロジックは不要） +- このコマンドは`architecture-decision`ステートで実行されることを前提としています（Status検証は不要、ユーザーの責任で適切なタイミングで実行） + +--- + +## 出力サマリー形式 + +```markdown +## /issync:review-poc 実行結果 + +### 完了したステップ +- ✅ ステップ1-11: 全ステップ完了 + +### POC検証結果 +- ✅ 達成: [達成項目数]項目 +- ❌ 未達成: [未達成項目数]項目 +- ⚠️ スコープ外: [スコープ外項目数]項目 + +### 次のアクション（重要） +- [ ] 進捗ドキュメントの内容（POC検証結果、Open Questions、Decision Log推奨案）をレビュー +- [ ] Open Questionsを検討し、意思決定を行う +- [ ] Decision Log推奨案を承認/修正/却下 +- [ ] **承認後、GitHub Projects Statusを手動で`implement`に変更してください** +- [ ] **implementのチェックリストを確認し、本実装を開始してください** + +--- + +## 補足: ステートマシンとの統合 + +このコマンド実行後の流れ： + +``` +pocステート完了 + ↓ +POC実装 & PR作成 + ↓ +Statusを architecture-decision に変更 + ↓ +/issync:review-poc コマンド実行 (このコマンド) + ├─ POC PR情報取得 + ├─ Discoveries & Insights参照 + ├─ Acceptance Criteria検証 + ├─ Discoveries & Insights追記 + ├─ Open Questions追加 + ├─ Decision Log推奨案記入 + ├─ Specification記入（オプショナル） + ├─ POC PRクローズ + └─ issync push（自動同期） + ↓ +POCレビュー完了 + ↓ +**人間が進捗ドキュメントをレビュー** + ├─ POC検証結果の確認 + ├─ Open Questionsの検討・意思決定 + └─ Decision Log推奨案の承認/修正/却下 + ↓ +**人間が承認後、手動でStatusを`implement`に変更** + ↓ +本実装開始 +``` + +**重要**: このコマンドは**Status自動変更を行いません**。人間が進捗ドキュメントの内容（POC検証結果、Open Questions、Decision Log推奨案）をレビューし、承認してから、手動でStatusを`implement`に変更してください。 diff --git a/commands/understand-progress.md b/commands/understand-progress.md new file mode 100644 index 0000000..a9b10f5 --- /dev/null +++ b/commands/understand-progress.md @@ -0,0 +1,100 @@ +--- +description: 進捗ドキュメントを選択してコンテキストを理解 +--- + +# /issync:understand-progress: 進捗ドキュメントコンテキスト読み込みコマンド + +あなたは矛盾解消駆動開発を実践するAIエージェントです。このコマンドは、セッション開始時に同期中の進捗ドキュメントを選択し、Claude CodeのReadツールで効率的に読み込むサポートをします。 + +## 使用方法 + +```bash +/issync:understand-progress https://github.com/owner/repo/issues/123 # Issue URL指定（必須） +``` + +**引数**: `issue_url` (必須) - GitHub Issue URL + +## 実行フロー + +### 1. Issue URLの処理 + +`issync status `で設定を取得。未同期の場合は`issync init `で同期を開始します。 + +### 2. 進捗ドキュメントの読み込み + +選択されたファイルをReadツールで読み込む。 + +### 3. Sub-issuesの取得と分析（AIエージェントのコンテキスト理解） + +**目的**: AIエージェントがプロジェクトの全体像を把握するため、親issueに紐づくsub-issuesを取得・分析します。 + +#### Sub-issuesの取得 + +GitHub REST APIの専用エンドポイントを使用: + +```bash +gh api "/repos/{owner}/{repo}/issues/{issue_number}/sub_issues" \ + --jq '.[] | {number, title, state, url}' +``` + +**注**: `{owner}`, `{repo}`, `{issue_number}`は進捗ドキュメントに紐づくissue URLから抽出してください。 + +#### AIエージェントによる内部分析 + +sub-issuesを分析してプロジェクトコンテキストを把握: +- CLOSED issues: 実装済み機能、解決済み問題（`Outcomes & Retrospectives`と照合） +- OPEN issues: 残タスク、優先度、次のアクション候補 +- 完了度: 進捗状況とフェーズ（plan/poc/implement等） + +**重要**: 詳細はAI内部で保持し、ユーザーには簡潔なサマリーのみを返す + +### 4. 作業中の進捗ドキュメント更新（重要） + +作業開始時は**進捗ドキュメントを継続的に更新**してください。 + +**更新タイミング:** +- 主要な決定時: `Decision Log`を更新 +- 実装進捗/発見時: `Discoveries & Insights`を更新(技術的制約、複雑性、新たなタスクの発見、失敗・エラー含む) +- Open Questions解消/新規疑問時: 該当項目を更新/追加 +- フェーズ完了時: `Outcomes & Retrospectives`を更新 +- フェーズ移行時: `Current Status`セクションを更新 + +**更新方法:** +- Edit/Write/Updateツールでセクション単位更新（ファイル全体の書き換えは避ける） +- 更新後は`issync push`で同期 +- **ユーザーへの確認は不要**: 更新判断はAIエージェントが自律的に行う +- **高頻度更新を推奨**: 小さな進捗でもこまめに記録する方が評価される + +**Single Source of Truth**: 進捗ドキュメントはプロジェクトの現在の状態を表す唯一の真実の情報源 + +## 出力フォーマット + +```markdown +## /issync:understand-progress 実行結果 + +✅ コンテキストを理解しました + +**ファイル**: +**Issue**: +**最終同期**: +**Sub-issues**: 件（OPEN: , CLOSED: ） +**プロジェクト状態**: + +次のアクション: +- Open Questionsを確認し、必要に応じて解消 +- **作業を進める際は、進捗ドキュメントを継続的に更新**（詳細はステップ4参照） +- 次のステップ（POC/実装等）を開始 +``` + +**注**: 詳細なsub-issuesリストはAI内部で保持。必要時にユーザーの質問に回答可 + +## 重要な注意事項 + +1. **自動初期化**: 指定されたIssue URLが未同期の場合は`issync init`で同期開始 +2. **シンプルな責務**: Issue URLからファイルを特定、読み込み、sub-issues分析に特化 +3. **Readツール使用**: セクション抽出や整形はReadツールに任せる +4. **エラーハンドリング**: 同期設定が存在しない場合やissync init失敗時は明確なエラーメッセージを表示 + +## 実行を開始 + +それでは、上記のフローに従って進捗ドキュメントの選択と読み込みを開始してください。 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..4cdcc22 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,77 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:MH4GF/issync:.claude-plugins/issync", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "3be98d68d4e619d251bcb3ef5e9a3da7d0447b9f", + "treeHash": "24c93ca0eb8ce9424fa1d8eef8ba421df185d62421236879b2de42ab448ba297", + "generatedAt": "2025-11-28T10:12:03.301247Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "issync", + "description": "矛盾解消駆動開発のためのツール群: plan実行(/plan)、POC調査(/poc)、POCレビュー(/review-poc)、進捗ドキュメント圧縮(/compact-progress-document)、Open Questions解消(/resolve-questions)、実装フェーズ(/implement)、タスクのサブissue化と順序管理(/create-sub-issue)、サブissue完了(/complete-sub-issue)、進捗ドキュメント読み込み(/understand-progress)", + "version": "0.10.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "773c4905c517771e7d1f11d5d2300ac3cb6bc371e1cedfbc3eff40a53ba86219" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "b2c0fa3726296176ad0c2e0f85e7ec29167f418ebb6b35dcb74b0c7df5611005" + }, + { + "path": "commands/create-sub-issue.md", + "sha256": "32e22f6572b9ed7d2c5d8bd78b94ac646115d13d1a237e0f87d223caf1b5e526" + }, + { + "path": "commands/implement.md", + "sha256": "ba725e5c2960473e5ffc9c99f67a3d39465d866071b59d58e5dd7c6267dd4989" + }, + { + "path": "commands/poc.md", + "sha256": "3fec083c33cd0453d3fd309f26ff29beb9bccdce03761a9da49b100698a8474e" + }, + { + "path": "commands/review-poc.md", + "sha256": "65a9b5482913a049de6f6cbd27fd234b7fc978c9bf3ee3b84796deb8210eb40f" + }, + { + "path": "commands/understand-progress.md", + "sha256": "11886ff2ba5737b59ba643fcac8ba620e75be36fd41b2aed72b03277ecfcf1be" + }, + { + "path": "commands/complete-sub-issue.md", + "sha256": "7e477cb5cb23406d9c4c55e1bd86b6dad44d09b302af00c620572325d0a1d0f9" + }, + { + "path": "commands/compact-progress-document.md", + "sha256": "eb153bea274521a663b5d437b1cb05c34183bd68edaf9eb4e3fde3236a5b60c3" + }, + { + "path": "commands/resolve-questions.md", + "sha256": "6b70edbfba60f18ddde27737cc745bd2459bfd0f1d345e5053234c31d3115d19" + }, + { + "path": "commands/plan.md", + "sha256": "0c10aacb9392476170a50af4ed6b8fbbf46f952c06b82ea7ee8def44d4d6f6c9" + } + ], + "dirSha256": "24c93ca0eb8ce9424fa1d8eef8ba421df185d62421236879b2de42ab448ba297" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file