harness-sync

Harness Sync

Plans.md と実装状況を照合し、差分を検出・更新する。 旧 sync-status および harness-plan sync サブコマンドの独立版。

Quick Reference

ユーザー入力	動作
harness-sync	進捗同期 + レトロスペクティブ（デフォルト ON）
harness-sync --no-retro	進捗同期のみ（レトロスキップ）
harness-sync --snapshot	スナップショット保存（進捗の時点記録）
harness-sync --plan roadmap	named Plans の roadmap を同期
"今どこ？" / "進捗確認"	同上

オプション

オプション	説明	デフォルト
--snapshot	現在の進捗をスナップショットとして保存	false
--no-retro	レトロスペクティブをスキップ	false（デフォルトで実行）
--plan NAME	plans/manifest.json の named plan を使う	active/default

Step 0: Plans.md 検証

Plans.md の存在とフォーマットを確認する。問題がある場合は即座に案内して停止する。 複数 Plans.md がある repo では、対象 plan を scripts/plan-registry.sh list または --plan NAME で確認してから読む。

状態	案内
Plans.md が存在しない	Plans.md が見つかりません。harness-plan create で作成してください。 → 停止
ヘッダーに DoD / Depends カラムがない（v1 形式）	Plans.md が旧フォーマット（3カラム）です。harness-plan create で v2（5カラム）に再生成してください。既存タスクは自動的に引き継がれます。 → 停止
v2 形式（5カラム）	そのまま Step 1 に進む

Step 1: 現状収集（並列）

# Plans.md の状態
cat Plans.md

# Git 変更状態
git status
git diff --stat HEAD~3

# 直近コミット履歴
git log --oneline -10

# エージェントトレース（直近の編集ファイル）
tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | jq -r '.files[].path' | sort -u

Step 1.5: Agent Trace 分析

Agent Trace から直近の編集履歴を取得し、Plans.md のタスクと照合する:

# 直近の編集ファイル一覧
RECENT_FILES=$(tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | \
  jq -r '.files[].path' | sort -u)

# プロジェクト情報
PROJECT=$(tail -1 .claude/state/agent-trace.jsonl 2>/dev/null | \
  jq -r '.metadata.project')

照合ポイント:

チェック項目	検出方法
Plans.md にないファイル編集	Agent Trace vs タスク記述
タスク記述と異なるファイル	想定ファイル vs 実際の編集
長時間編集がないタスク	Agent Trace 時系列 vs WIP 期間

Step 2: 差分検出

チェック項目	検出方法
完了済みなのに cc:WIP	DoD・必須チェック・必要な review の証拠 vs マーカー
着手済みなのに cc:TODO	変更ファイル vs マーカー
cc:完了 なのに未コミット	git status vs マーカー

Step 3: Plans.md 更新提案

状況確認だけの依頼は読み取りと差分報告で完了する。同期更新を明示依頼されている場合は、証拠に一致するマーカー更新を再確認せず実行する。 対象が曖昧、証拠が不足、または仕様判断が必要な項目だけ提案に残す。コミットや Worker の自己申告だけでは完了にしない。

Plans.md 更新が必要です

| Task | 現在 | 変更後 | 理由 |
|------|------|--------|------|
| XX   | cc:WIP | cc:完了 | DoD・必須チェック・review の証拠を確認済み |
| YY   | cc:TODO | cc:WIP | ファイル編集済み |

Step 4: 進捗サマリー出力

## 進捗サマリー

**プロジェクト**: {{project_name}}

| ステータス | 件数 |
|----------|------|
| 未着手 (cc:TODO) | {{count}} |
| 作業中 (cc:WIP) | {{count}} |
| 完了 (cc:完了) | {{count}} |
| PM確認済 (pm:確認済) | {{count}} |

**進捗率**: {{percent}}%

### 直近の編集ファイル (Agent Trace)
- {{file1}}
- {{file2}}

Step 4.5: スナップショット保存（--snapshot 指定時）

--snapshot が指定された場合、現在の進捗状態を時刻付きスナップショットとして保存する。

保存先

.claude/state/snapshots/ ディレクトリに JSON 形式で保存:

SNAPSHOT_DIR="${PROJECT_ROOT}/.claude/state/snapshots"
mkdir -p "${SNAPSHOT_DIR}"
SNAPSHOT_FILE="${SNAPSHOT_DIR}/progress-$(date -u +%Y%m%dT%H%M%SZ).json"

スナップショット内容

{
  "timestamp": "2026-03-08T10:30:00Z",
  "phase": "Phase 26",
  "progress": {
    "total": 16,
    "todo": 5,
    "wip": 3,
    "done": 6,
    "confirmed": 2
  },
  "progress_rate": 50,
  "recent_commits": ["abc1234 feat: ...", "def5678 fix: ..."],
  "recent_files": ["skills/harness-work/SKILL.md", "..."],
  "notes": ""
}

差分比較

前回スナップショットが存在する場合、差分を表示:

## スナップショット差分

| 指標 | 前回 ({{prev_time}}) | 今回 | 変化 |
|------|---------------------|------|------|
| 進捗率 | {{prev}}% | {{current}}% | +{{diff}}%pt |
| 完了タスク | {{prev_done}} | {{current_done}} | +{{diff_done}} |
| WIP タスク | {{prev_wip}} | {{current_wip}} | {{diff_wip}} |

設計意図: snapshot はユーザーが「今の状態を記録しておきたい」と思った時に手動で使う。 breezing 中の自動的なプログレスフィード（26.2.3）とは別の機能。

Step 5: 次のアクション提案

次にやること

**優先 1**: {{タスク}}
- 理由: {{依頼中 / アンブロック待ち}}

**推奨**: harness-work, harness-review

異常検知

状況	警告
複数の cc:WIP	複数タスクが同時進行中
pm:依頼中 が未処理	PM の依頼を先に処理する
大きな乖離	タスク管理が追いついていない
WIP が 3日以上更新なし	ブロックされていないか確認

Step 6: レトロスペクティブ（デフォルト ON）

cc:完了 タスクが 1 件以上あれば自動的に振り返りを実行する。 --no-retro で明示的にスキップ可能。

Step R1: 完了タスク収集

# Plans.md から cc:完了 / pm:確認済 のタスクを抽出
grep -E 'cc:完了|pm:確認済' Plans.md

# 直近の完了コミット履歴
git log --oneline --since="7 days ago"

# 変更規模
git diff --stat HEAD~10

Step R2: 振り返り 4 項目

項目	分析方法
見積もり精度	Plans.md のタスク記述から想定ファイル数を推論 → git diff --stat の実変更ファイル数と比較
ブロック原因	blocked マーカーが付いたタスクの理由パターンを集計（技術的/外部依存/仕様不明確）
品質マーカー的中率	[feature:security] 等を付けたタスクで実際に関連問題が出たか
スコープ変動	Plans.md の初回コミット時のタスク数 vs 現在のタスク数（追加/削除件数）

Step R3: 振り返りサマリー出力

## 振り返りサマリー

**期間**: {{start_date}} 〜 {{end_date}}

| 指標 | 値 |
|------|-----|
| 完了タスク | {{count}} 件 |
| ブロック発生 | {{blocked_count}} 件 |
| スコープ変動 | +{{added}} / -{{removed}} 件 |
| 見積もり精度 | 想定 {{est}} ファイル → 実際 {{actual}} ファイル |

### 学び
- {{1-2 行の学び}}

### 次に活かすこと
- {{1-2 行の改善アクション}}

Step R4: harness-mem への記録

振り返りは今回確認した証拠と改善案を報告する。永続記録を明示依頼されている場合だけ、対象の harness-mem または .claude/agent-memory/ に出典と判断理由を記録する。 通常の進捗確認や sync を永続記録の依頼として扱わない。

関連スキル

• harness-plan — 計画作成・タスク管理
• harness-work — タスク実装
• harness-review — コードレビュー