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

Files

Zhongwei Li fb4d2ff5f1 Initial commit

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

7.0 KiB

Raw Permalink Blame History

description

description
自信度を上げるための調査・検証を中心に行い、発見を進捗ドキュメントに記録

/issync:poc: POC調査フェーズ自動化コマンド

あなたは矛盾解消駆動開発を実践するAIエージェントです。このコマンドは、進捗ドキュメントの内容を理解した上で調査・検証を進め、発見した知見を継続的にドキュメントに記録することで、AI駆動開発ワークフローのPOCフェーズを自動化します。

使用方法

/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コマンドを内部で呼び出して、進捗ドキュメントを読み込みます。

/issync:understand-progress <issue_url_or_number>

引数が指定されている場合はそのまま渡し、指定されていない場合は引数なしで実行します。

ステップ2: 進捗ドキュメントの確認

特にOpen Questions（調査すべき論点）とContext & Directionを確認してください。

ステップ3: 調査・検証の開始

Open Questionsに基づいて調査・検証を開始してください。

進め方:

技術調査（ドキュメント、API仕様、既存コード）
実装による検証（小規模なコード作成、動作確認）
発見を随時ドキュメントに記録

重要: 目的は知見の獲得です。コード品質は優先度が低いです。

ステップ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記入例:

## Discoveries & Insights

**YYYY-MM-DD: [発見のタイトル]**
- **発見**: [発見した技術的事実 - できる/できない、制約、特性など]
- **学び**: [この発見が実装にどう影響するか]
- **検証方法**: [どのように確認したか - コード実装、ドキュメント調査など]

Open Questions更新例:

## Open Questions

### Q1: ~~解決済み: XXXは可能か？~~

**解決**: YYYによって実現可能と判明（YYYY-MM-DD）

---

### Q2: 新たな疑問: ZZZの最適な設定値は？

**背景**: POCでAAAを実装したところ、BBBの設定値によって挙動が変わることが判明

ステップ5: テストの実行（オプショナル）

必要に応じて軽量なテスト実行。全テスト合格は必須ではありません。

bun test <検証したい機能のテストファイル>

ステップ6: 進捗ドキュメントの最終同期

調査・検証が完了したら、進捗ドキュメントの変更をGitHub Issueに同期してください。

issync push

ステップ7: Git commitとPR作成

POCの実装と発見を記録するため、PRを作成します。

git add <変更したファイル>
git commit -m "poc: <POCの目的や検証内容>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

git push origin <ブランチ名>

gh pr create --title "POC: <検証内容>" --body "$(cat <<'EOF'
## POCの目的
<調査・検証した内容>

## 主な発見
<Discoveries & Insightsのサマリー>

## 次のステップ
- [ ] PRレビュー後、`/issync:review-poc`で知見を整理
- [ ] アーキテクチャ決定後、このPRはクローズされます

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

重要: このPRは人間がレビューするための差分確認用です（マージしません）。

出力フォーマット

## /issync:poc 実行結果

✅ POC調査が完了しました
**Issue**: <issue_url> | **ファイル**: <progress_document_path>

### 調査内容と主な発見
- [調査項目と発見のサマリー]

### 進捗ドキュメント更新
- Discoveries & Insights: [X]件
- Open Questions: [Y]件追加/[Z]件解決

### 次のアクション
- [ ] POC PR (<PR URL>) をレビュー
- [ ] `/issync:review-poc <PR URL>`で知見を整理
- [ ] アーキテクチャ決定後、PRをクローズ

重要な注意事項

調査優先: コードの品質よりも知見の獲得を優先
継続的更新: 調査中は常に進捗ドキュメントを更新（最重要）
破棄前提: 実装は破棄される前提で、自由に試行錯誤
issync連携: 作業後はissync pushで同期
PR作成: 人間が差分を確認できるようPRを作成（マージしない、後でクローズ）
テストはオプショナル: 全テスト合格は必須ではない
Status変更なし: GitHub Projects Statusの変更は行わない

ワークフロー

/issync:poc → 調査・検証 → ドキュメント更新 → POC PR作成
   ↓
人間がPRレビュー
   ↓
/issync:review-poc → 知見整理 → Decision Log推奨案
   ↓
人間が意思決定・承認 → PRクローズ → Status変更(`implement`)
   ↓
/issync:implement（本実装）

実行を開始

それでは、上記のフローに従ってPOC調査を開始してください。

7.0 KiB Raw Permalink Blame History Unescape Escape