workflow-enforcement について
Claudeを22段階の開発ワークフローに沿って進め、進捗管理と必須チェックポイントのリマインダーを示す仕様型スキルです。手順を案内しますが、未実施の工程を強制的にブロックするものではありません。
主な機能
- 0122段階のワークフローガイド
- 02TodoWriteまたはYAMLでの状態管理
- 03必須チェックポイントの通知
- 04進捗表示形式
- 05エラー時に継続する復旧方針
活用シーン
- 01機能開発中の工程管理
- 02PRの作成・マージ前に必須レビューを確認
- 03状態ファイルがない場合の進捗復元
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/workflow-enforcementを入力して読み込まれたか確認します。
同梱ファイルREADME.md
詳細
ワークフロー強制スキル
目的
以下の方法で、Claude がワークフローの全ステップを完了するよう導きます。
- ステップ完了の追跡を促します（TodoWrite または
~/.amplihack/.claude/runtime/workflow_state.yamlを使用） - 省略してはならない必須ステップ（0、10、16～17）を強調します
- 視覚的な進捗表示の形式を提示します
- チェックポイントで想定されるブロック動作を定義します
実装状況：このスキルは現在、Claude の動作を導く仕様です。実際にブロックして強制するには、次のいずれかが必要です。
- Claude による自己遵守（現在の状態）
- 今後の実装：pre-commit フックまたは CI チェック（未実装）
問題（Issue #1607）
エージェントは必須のワークフローステップを頻繁に省略します。特に次のステップが対象です。
- ステップ 0：ワークフローの準備 - すべてのステップの ToDo を作成する（必須）
- ステップ 10：コミット前のコードレビュー（必須）
- ステップ 16：PR のレビュー（必須）
- ステップ 17：レビューのフィードバックを反映する（必須）
根本原因：
- 完了バイアス：「レビュー後に PR がマージされた」ではなく、「PR を作成した」時点で完了したと見なす
- コンテキストの減衰：実装作業が長時間続いた後、残りのステップを見失う
- 自律性の誤用：「自律的な実装」を「必須プロセスの省略」と混同する
哲学との整合性と正直な制約
皮肉な点
このスキルは、エージェントが機能の構築中にワークフローのステップを省略したことを受けて作成されました。ステップの省略を引き起こすのと同じ認知パターンにより、このスキル自体も無視される可能性があります。この制約を率直に認めます。
このスキルでできること
- Claude が従うための明確な指針を提示する
- 進捗追跡の標準形式を定義する
- Claude が一時停止して検証すべきチェックポイントを設ける
- セッション終了時の検証のために power_steering と連携する
- 今後のエージェント向けに、期待される動作を記録する
このスキルでできないこと
- Claude にこのスキルを読ませる（自動有効化トリガーに依存します）
- Claude が自律的に進めると「決めた」場合に、ステップの省略を防ぐ
- 操作を強制的にブロックする（pre-commit フックはまだ実装されていません）
- ワークフロー違反をリアルタイムで検出する（現在あるのはセッション終了時のチェックのみです）
哲学との整合性
| 原則 | このスキルとの整合性 |
|---|---|
| 徹底したシンプルさ | 状態管理には単一の YAML ファイルを使用し、複雑なインフラは不要です |
| ごまかしのない実装 | 強制ではなく指針であることを正直に示します |
| モジュール設計 | 明確な統合ポイントを備えた自己完結型のスキルです |
| フェイルオープン | エラー時はログを記録して続行し、ユーザーをブロックしません |
自己認識に関する注記：このスキル自体も、仕様から再生成できる一つの部品です。実行可能なコードは含まず、読み込まれたコンテキストを通じて Claude の動作を導くドキュメントです。
このスキルの使い方
手順
ワークフロー開始時（ステップ 0）
-
状態追跡を初期化する（いずれかを選択します）。
オプション A - TodoWrite（推奨）：
Create TodoWrite entries for ALL 22 steps (0-21): - "Step 0: Workflow Preparation - Create todos for ALL steps" - "Step 1: Prepare the Workspace" - ... - "Step 21: Ensure PR is Mergeable - TASK COMPLETION"オプション B - YAML 状態ファイル：
cp .claude/templates/workflow_state.yaml.template \ .claude/runtime/workflow_state.yaml # Edit workflow_id, task_description, started_at -
初期進捗を表示する：
WORKFLOW PROGRESS [0/22] [.......................] Step 0: Workflow Preparation Mandatory gates: Step 0 (Prep), Step 10 (Review), Step 16 (PR Review), Step 17 (Feedback) -
初期化を確認する：続行する前に、ToDo アイテムが 22 個あることを確認します。
各ステップの完了時
- TodoWrite または YAML でステップを
completedにする current_stepを次のステップ番号に更新する- 進捗表示を更新する
- 必須ステップ（10、16、17）が近づいたら、リマインダーを表示する
必須チェックポイント
ステップ 15（PR をドラフトとしてオープンする）の前：
+------------------------------------------------------------------+
| CHECKPOINT: Pre-PR Validation |
+------------------------------------------------------------------+
| [ ] Step 10: Pre-commit code review |
| Status: ??? (check your TodoWrite/YAML state) |
| |
| If Step 10 is NOT completed: |
| - STOP: Do not proceed to Step 15 |
| - ACTION: Invoke reviewer agent for code review |
| - ACTION: Invoke security agent for security review |
| - Then return here and verify completion |
+------------------------------------------------------------------+
ステップ 21（マージ可能であることを確認する）の前：
+------------------------------------------------------------------+
| CHECKPOINT: Final Validation |
+------------------------------------------------------------------+
| [ ] Step 10: Pre-commit code review |
| [ ] Step 16: PR review |
| [ ] Step 17: Review feedback implementation |
| |
| ALL mandatory steps must be completed before Step 21. |
| Check your TodoWrite/YAML state for status. |
+------------------------------------------------------------------+
ワークフロー終了時
- すべてのステップが完了していること（または、文書化された理由を添えて明示的にスキップされていること）を確認する
- 最終進捗を表示する：
[######################] 22/22 Steps Complete - 使用した場合は
~/.amplihack/.claude/runtime/workflow_state.yamlを削除する - workflow_tracker.py に完了を記録する
視覚的な進捗表示の形式
標準的な進捗バー
WORKFLOW: DEFAULT_WORKFLOW v1.1.0
PROGRESS: [##########............] 10/22 (45%)
Current: Step 10 - Pre-commit code review (MANDATORY)
Next: Step 11 - Incorporate Review Feedback
詳細なステータス表示
+======================================================================+
| DEFAULT WORKFLOW - Progress |
+======================================================================+
| Task: Add authentication feature |
| Session: session_20251125_143022 |
| Started: 2025-11-25T14:30:22 |
+----------------------------------------------------------------------+
| Progress: 10/22 steps (45%) |
| [##########............] 10/22 |
+----------------------------------------------------------------------+
| COMPLETED (10): |
| 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 |
| |
| CURRENT: |
| >> Step 10: Pre-commit code review (MANDATORY) << |
| |
| REMAINING (12): |
| 11, 12, 13, 14, 15, *16*, *17*, 18, 19, 20, 21 |
| (* = mandatory) |
+----------------------------------------------------------------------+
| MANDATORY GATES: |
| [X] Step 0 - Workflow Preparation COMPLETED |
| [ ] Step 10 - Pre-commit Review IN PROGRESS |
| [ ] Step 16 - PR Review PENDING |
| [ ] Step 17 - Feedback Implementation PENDING |
+======================================================================+
簡潔なステータス（更新用）
[10/22] Step 10 (MANDATORY) | Gates: 0[X] 10[>] 16[ ] 17[ ]
状態ファイル形式
テンプレートの場所：~/.amplihack/.claude/templates/workflow_state.yaml.template
アクティブな状態の場所：~/.amplihack/.claude/runtime/workflow_state.yaml
workflow_id: "session_20251125_143022"
workflow_name: DEFAULT
task_description: "Add authentication feature"
started_at: "2025-11-25T14:30:22"
current_step: 10
steps:
0: { status: completed, timestamp: "2025-11-25T14:30:22", mandatory: true }
1: { status: completed, timestamp: "2025-11-25T14:31:05" }
# ... steps 2-9 ...
10: { status: in_progress, mandatory: true }
# ... steps 11-15 ...
16: { status: pending, mandatory: true }
17: { status: pending, mandatory: true }
# ... steps 18-21 ...
mandatory_steps: [0, 10, 16, 17]
checkpoints:
before_step_15:
required_steps: [10]
error_message: "Cannot open PR without completing Step 10"
before_step_21:
required_steps: [10, 16, 17]
error_message: "Cannot mark mergeable without all mandatory reviews"
Power Steering との統合
Power Steering は、considerations.yaml の dev_workflow_complete の考慮事項を通じて、セッション終了時の検証を行います。
仕組み
- セッション中：このスキルがガイダンスを提供し、Claude は TodoWrite で手順を追跡します
- セッション終了時：Power Steering の
_check_dev_workflow_completeがトランスクリプトを分析します - 使用するヒューリスティック：
- architect、builder、reviewer の各エージェントが呼び出されたか
- テストが実行されたか（Bash ツールの使用）
- git 操作が行われたか
- 結果：ワークフローの証拠がない場合、セッションの完了をブロックします
統合ポイント
considerations.yaml
==================
- id: dev_workflow_complete
category: Workflow Process Adherence
question: Was full DEFAULT_WORKFLOW followed?
severity: blocker
checker: _check_dev_workflow_complete
applicable_session_types: ["DEVELOPMENT"]
現在の制限：Power Steering はワークフローの証拠（エージェントの使用、テストの実行）を確認しますが、workflow_state.yaml は読み込みません。これは今後の拡張候補です。
提案されている拡張（未実装）
# In power_steering_checker.py (future)
def _check_dev_workflow_complete(self, transcript, session_id):
# Check for workflow_state.yaml
state_file = Path(".claude/runtime/workflow_state.yaml")
if state_file.exists():
state = yaml.safe_load(state_file.read_text())
mandatory = state.get("mandatory_steps", [0, 10, 16, 17])
steps = state.get("steps", {})
for step_num in mandatory:
step = steps.get(step_num, {})
if step.get("status") != "completed":
return False # Mandatory step incomplete
return True # All mandatory steps completed
# Fall back to heuristic analysis
return self._check_workflow_heuristics(transcript)
TodoWrite との統合
TodoWrite を使用する場合は、手順番号がワークフローの追跡と一致するようにしてください。
TodoWrite(todos=[
{"content": "Step 0: Workflow Preparation - Create todos for ALL steps", "status": "completed", "activeForm": "Creating step todos"},
{"content": "Step 10: Pre-commit code review - MANDATORY", "status": "in_progress", "activeForm": "Reviewing code"},
{"content": "Step 16: PR review - MANDATORY", "status": "pending", "activeForm": "Reviewing PR"},
{"content": "Step 17: Implement review feedback - MANDATORY", "status": "pending", "activeForm": "Implementing feedback"},
])
重要な点：TodoWrite が主要な追跡手段です。YAML 状態ファイルは、追加の永続化と構造化された検証のための任意の手段です。
ブロック動作（自己遵守パターン）
必須手順がスキップされた場合、Claude は次のパターンを表示して従う必要があります。
+======================================================================+
| WORKFLOW ENFORCEMENT: BLOCKED |
+======================================================================+
| |
| Cannot proceed to Step 15 (Open PR as Draft). |
| |
| MISSING MANDATORY STEP: |
| Step 10: Pre-commit code review |
| |
| WHY THIS MATTERS: |
| - Code review catches bugs before they reach CI |
| - Philosophy compliance ensures quality |
| - Issue #1607 identified this as a recurring problem |
| |
| ACTION REQUIRED: |
| 1. Invoke reviewer agent for comprehensive code review |
| 2. Invoke security agent for security review |
| 3. Mark Step 10 as completed in TodoWrite |
| 4. Then proceed to Step 15 |
| |
+======================================================================+
エラーからの復旧
状態ファイルが見つからない場合、または破損している場合：
- 現在の手順に関する情報を TodoWrite で確認します
- 会話のコンテキストから状態を再構築します
- 復旧できない場合は、現在の手順をユーザーに確認します
- 常にフェイルオープンとし、ブロックするのではなく警告を表示して続行します
今後の作業：厳格な適用への道筋
フェーズ 1：現在の状態（ガイダンスのみ）
- スキルがドキュメントとパターンを提供します
- 効果は Claude の自己遵守によって決まります
- Power Steering がセッション終了時に警告を表示します
フェーズ 2：Power Steering の強化（計画中）
- Power Steering が workflow_state.yaml を読み込みます
- チェックポイントの手順でリアルタイム検証を行います
dev_workflow_completeのチェックをさらに細分化します
フェーズ 3：コミット前の統合（将来）
# .pre-commit-config.yaml (future)
- repo: local
hooks:
- id: workflow-validation
name: Validate workflow completion
entry: python .claude/tools/amplihack/validate_workflow.py
language: system
pass_filenames: false
フェーズ 4：CI ゲート（将来）
# .github/workflows/ci.yml (future)
- name: Validate Workflow Compliance
run: |
python -c "
from pathlib import Path
import yaml
state = yaml.safe_load(Path('.claude/runtime/workflow_state.yaml').read_text())
mandatory = state.get('mandatory_steps', [0, 10, 16, 17])
for step in mandatory:
if state['steps'].get(step, {}).get('status') != 'completed':
print(f'FAIL: Mandatory step {step} not completed')
exit(1)
print('PASS: All mandatory workflow steps completed')
"
関連コンポーネント
- DEFAULT_WORKFLOW.md：ステップ 0 のガイダンスを含む標準ワークフロー定義
- templates/workflow_state.yaml.template：構造化された状態追跡用のテンプレート
- workflow_tracker.py：履歴ログ（JSONL 形式）
- power_steering_checker.py：セッション終了時の適用（トランスクリプトベース）
- considerations.yaml：
dev_workflow_completeの考慮事項の定義
コメント
Markdown 対応