Persistent Mode

Persistent Mode v5.0 (強制持続モード)

核心コンセプト: Stop Hook + State ファイル基盤の 技術的強制

ralph パターンを Web プロジェクトに合わせてポーティング。 ドキュメントで「繰り返せ」と書くだけではなく、実際にAIを強制します。

強制メカニズム (How It Works)

アーキテクチャ

AIが応答を完了しようとする
         ↓
Stop Hook 発動
         ↓
stop-handler.mjs 実行
         ↓
.claude/state/persistent-state.json チェック
         ↓
┌─────────────────────────────────────┐
│ active=true?                        │
│   ├─ Yes → { decision: 'block' }    │
│   │         AIが強制的に継続        │
│   │                                 │
│   └─ No  → { continue: true }       │
│            正常終了を許可           │
└─────────────────────────────────────┘

核心ファイル

使用法

1. モード有効化 (State ファイル生成)

自然言語での呼び出し (推奨):

"最後までこの機能を完成させて"
"テストが通るまで止めないで"
"完了まで進めて"

明示的呼び出し:

/persistent-mode
/persistent-mode --max-iterations 30
/persistent-mode --plan .tmp/plans/my-task.md
/persistent-mode --plan .tmp/plans/my-task.md --max-iterations 30

有効化時にAIがすべきこと:

# State ファイル生成 (基本モード)
mkdir -p .claude/state

cat > .claude/state/persistent-state.json << 'EOF'
{
  "active": true,
  "iteration": 1,
  "max_iterations": 50,
  "started_at": "2026-02-05T10:00:00+09:00",
  "last_checked_at": "2026-02-05T10:00:00+09:00",
  "prompt": "[元の作業リクエスト]",
  "error_history": []
}
EOF

# State ファイル生成 (--plan モード)
mkdir -p .claude/state

cat > .claude/state/persistent-state.json << 'EOF'
{
  "active": true,
  "iteration": 1,
  "max_iterations": 50,
  "started_at": "2026-02-05T10:00:00+09:00",
  "last_checked_at": "2026-02-05T10:00:00+09:00",
  "prompt": "[元の作業リクエスト]",
  "error_history": [],
  "completion": {
    "type": "plan",
    "plan_file": ".tmp/plans/my-task.md"
  }
}
EOF

Plan 基盤の自動完了 (v5.0)

動作フロー:

1. AIがState ファイルを生成 (completion.type: "plan" を含む)
2. AIが計画ファイルを生成 (マークダウンチェックボックス)
3. 作業を進めながら完了項目を - [x] でチェック
4. Stop Hookが毎回の反復でチェックボックスの状態を確認
5. 全て完了 → 自動終了 (State + 計画ファイル削除)

計画ファイルの例:

# 作業計画: SPEC 文書分析

## チェックリスト

- [ ] SPEC-006 読み込みおよび分析
- [ ] SPEC-007 読み込みおよび分析
- [ ] SPEC-008 読み込みおよび分析
- [ ] 最終要約文書作成

進捗表示:

[PERSISTENT MODE - 5/20] 進捗率: 2/4 (50%)

未完了項目:
  - [ ] SPEC-008 読み込みおよび分析
  - [ ] 最終要約文書作成

全ての項目完了時に自動で終了します。

終了条件の比較:

2. 作業実行

State ファイルが存在すれば、AIが停止しようとするたびにStop Hookが強制的に継続させます。

[PERSISTENT MODE - 1/50]

## 現在の作業

FR-02901: 単語帳リスト画面の実装

## 実行中

- VocabularyListPage 実装...

3. 検証失敗時の自動リトライ

[PERSISTENT MODE - 2/50]

## 前回の失敗

- npm run lint: 2個 warning (unused import)

## 修正作業

- src/features/vocabulary/components/ListPage.tsx:3
  - 未使用 import 削除

## 再検証中...

4. モード終了 (/cancel)

作業完了後、必ず /cancel で終了:

# State ファイル削除
rm .claude/state/persistent-state.json

## Persistent Mode 終了

State ファイル削除完了
これでAIが正常に停止できます

State ファイル構造

{
  "active": true,
  "iteration": 5,
  "max_iterations": 50,
  "started_at": "2026-02-05T10:00:00+09:00",
  "last_checked_at": "2026-02-05T10:15:00+09:00",
  "prompt": "全てのテスト通過まで続行して",
  "error_history": ["npm run lint: 2 warnings", "npm test: 1 failed"]
}

終了条件

成功終了

1. 全ての検証通過:

   • npm run lint: Exit 0, エラー 0個
   • npm test: 全テスト通過
   • Task システム: pending/in_progress 0個

2. /cancel 実行でState ファイル削除

[PERSISTENT MODE - 完了]

## 最終検証結果

| 項目            |     状態     |
| --------------- | :----------: |
| npm run lint    |   0 issues   |
| npm test        | 47/47 passed |
| Tasks           |  0 pending   |

→ 全ての検証通過!
→ 反復回数: 3回

失敗終了

[PERSISTENT MODE - 中断]

## 同一エラー3回反復

エラー: npm test - VocabularyViewModel テスト失敗
原因: MockSupabase 設定の問題と推定

## 推奨対処

1. MockSupabase 設定を手動で検証
2. テスト環境の依存関係確認
3. /cancelでモード終了後、手動解決

設定オプション

デフォルト設定

{
  "max_iterations": 50,
  "staleness_hours": 2,
  "same_error_limit": 3
}

カスタム設定

# 最大反復回数変更
/persistent-mode --max-iterations 100

# 高速失敗モード (同一エラー2回で中断)
/persistent-mode --same-error-limit 2

連携スキル

web-qaとの組み合わせ

# QA サイクル + 完了保証
/web-qa --persistent

→ web-qaのQAサイクルをpersistent-modeで強制

turbo-modeとの組み合わせ

# 並列実行 + 完了保証
/turbo-mode --persistent

→ 並列作業が全て完了するまで強制

トラブルシューティング

1. モードが終了しない

原因: State ファイルが残っている

解決:

# 手動削除
rm .claude/state/persistent-state.json

# または強制 cancel
/cancel --force

2. Stop Hookが動作しない

原因: settings.jsonにHookが登録されていない

確認:

cat .claude/settings.json | grep stop-handler

解決: Hookを再登録

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/scripts/stop-handler.mjs",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

3. Stalenessにより自動無効化された

原因: 2時間以上応答なし

解決: モードを再有効化

/persistent-mode

既存バージョンとの比較

参照文書

• stop-handler.mjs (統合 Stop Hook ハンドラー)
• cancel SKILL.md
• web-qa SKILL.md
• turbo-mode SKILL.md

変更履歴