workflow-patterns

workflow-patternsスキルの概要

workflow-patternsが実際に役立つこと

workflow-patterns は、実装作業を厳密なテスト駆動の順序で進めるためのプロセス系スキルです。Conductorスタイルのタスク遂行を前提に設計されており、次の予定タスクを選ぶ、plan.md に進捗状態を記録する、先に失敗するテストを書く、小さな単位で実装を進める、節目ごとに検証する、コミットをタスク状態に対応づける、といった流れを守らせます。AIエージェントに、いきなりコードを書かせるのではなく、規律ある実装フローに従って進めさせたいなら、workflow-patterns がそのためのスキルです。

このworkflow-patternsスキルが向いているケース

この workflow-patterns skill は、すでにタスク計画ベースで作業を整理していて、AIエージェントの実行精度を上げたいチームや個人開発者に向いています。特に次を重視する場合に有効です。

• フェーズごとのタスク順序を崩したくない
• red-green-refactor の流れを徹底したい
• 進捗を plan.md に残したい
• ステータス更新のコミットと実装コミットを分けたい
• 完了宣言の前に必ず検証を通したい

リポジトリにすでに計画ファイルやテスト基盤があるなら、汎用的な「この機能を実装して」というプロンプトよりも、このスキルの価値はかなり高くなります。

本当に解決したい仕事

多くのユーザーが求めているのは、TDDの理論ではありません。欲しいのは、計画済みタスクを渡したときに、ワークフロー上のコントロールを飛ばさず最後までやり切るエージェントです。つまり本質的な役割は、チェックボックス付きのタスクリストを、テスト漏れが少なく、引き継ぎが曖昧になりにくく、進捗追跡もしやすい、再現性のある実装ループへ変えることです。

通常のコーディングプロンプトとworkflow-patternsの違い

通常のプロンプトは、コードが先でプロセスが後になりがちです。workflow-patterns はそこを逆転させます。エージェントに対して、明確なチェックポイント付きのタスクライフサイクルを与えます。

1. 順番どおりに次の未着手タスクを選ぶ
2. 進行中に更新する
3. まず失敗するテストを書く
4. テストが通るまで実装する
5. リファクタリングする
6. 検証を実行する
7. タスク状態を更新し、適切にコミットする

コード生成そのものより、「制御されていない実行」が最大のリスクになっている現場では、この構造が効きます。

インストール前に知っておきたい重要な制約

このスキルは意図的に適用範囲を絞っています。フレームワーク固有の実装ルール、テストライブラリ、リポジトリ固有のコマンドまでは提供しません。それらは利用側で与える前提です。プロジェクトに plan.md がない、テストカバレッジが弱い、小さく規律あるコミット運用をする気がない、という場合は、workflow-patterns for Workflow Templates は硬すぎると感じるかもしれません。

workflow-patternsスキルの使い方

workflow-patternsスキルのインストール方法

wshobson/agents リポジトリからインストールします。

npx skills add https://github.com/wshobson/agents --skill workflow-patterns

インストール後は、エージェントに自由流儀で実装させるのではなく、リポジトリのタスクライフサイクルに従わせたい場面で呼び出します。

workflow-patternsの配置場所と最初に読むべきファイル

このスキルは次の場所にあります。

plugins/conductor/skills/workflow-patterns/SKILL.md

最初に読むべきなのは SKILL.md です。このスキルでは、そのファイルが唯一の正本であり、ワークフロー全体がまとまっています。補助フォルダや追加の支援ファイルはないため、導入時にまずやるべきことは、この順序を正しく理解し、自分のリポジトリ運用に合わせて落とし込むことです。

workflow-patternsがうまく機能するために必要な入力

このスキルは、具体的な実行コンテキストを与えるほど有用になります。

• plan.md のパス
• 現在のフェーズまたはマイルストーン
• 対象にする正確なタスクID、または次の [ ] 項目を選んでよいという許可
• テストコマンド
• lint/typecheck/build コマンド
• ブランチ運用やコミット方針
• 「生成ファイルは編集しない」などのリポジトリ制約

これらがないと、エージェントはプロセス自体は理解できても、あなたのプロジェクトで何をもって検証完了とするかを推測で補うことになります。

workflow-patternsを適切に呼び出す最小限のプロンプト

実用になる最小構成のプロンプトは、たとえば次のようなものです。

Use the workflow-patterns skill.

Project plan: docs/plan.md
Follow tasks in order and do not skip phases.
Select the next pending [ ] task, mark it [~], and keep status updates separate from implementation commits.
Use TDD: write failing tests first, then implement, then refactor.
Verification commands:
- pytest
- ruff check .
- mypy .
When complete, update the task to [x] only if verification passes.

これは単に「次の機能を実装して」と頼むよりはるかに良く、タスクの出所、順序、検証方法、完了条件まで明示できています。

曖昧な依頼を強いworkflow-patternsプロンプトに変える方法

弱い依頼:

Implement the next task with workflow-patterns.

より強い依頼:

Use the workflow-patterns skill for docs/plan.md.

Current target phase: Phase 2 only.
Select the next unchecked task in order.
Before coding, change that task from [ ] to [~].
Write failing tests covering happy path, edge cases, and one error path.
Use these commands:
- npm test -- --runInBand
- npm run lint
- npm run typecheck
Do not modify unrelated tasks.
When all checks pass, refactor if needed, update plan.md to [x], and summarize what changed.

強い版が防いでくれる最大の導入リスクは、エージェントがワークフロー自体は理解していても、ローカルな制約を分かっていないまま動いてしまうことです。

実運用でのworkflow-patternsの想定タスクライフサイクル

コアとなる workflow-patterns usage パターンは次のとおりです。

1. plan.md を確認する
2. 現在フェーズ内で次の未着手タスクを選ぶ
3. そのタスクを [~] にする
4. その状態変更をコミットする、または少なくとも他の変更から分離する
5. 失敗するテストを書く
6. 通るために必要最小限の変更を実装する
7. 安全にリファクタリングする
8. 検証を実行する
9. タスクを [x] にする
10. 最終コミットのメモとサマリーを残す

このスキルは単なるコード編集ではなく、状態遷移を中心に組まれているため、この流れが重要です。

plan.mdの品質が出力品質に直結する理由

このスキルの質は、実行対象となる計画の質に強く依存します。たとえば「auth flow を改善する」のような曖昧なタスク文では、テスト対象も完了条件も曖昧になります。良いタスクは、テスト可能なレベルまで具体化されています。

• 影響するファイルやモジュール
• 期待する振る舞い
• エラー条件
• 受け入れ確認項目
• 先行タスクへの依存関係

plan.md が薄いなら、workflow-patterns guide を評価する前に、まずそこを改善した方が良いです。

検証コマンドの扱い方

このスキルは検証プロトコルを重視しますが、どのコマンドを使うかまでは標準では知りません。必ず正確なコマンドと、失敗時の扱いを明示してください。たとえば次のようにします。

Verification must pass before task completion:
- cargo test
- cargo clippy -- -D warnings
- cargo fmt --check

If any verification step fails, do not mark the task complete.

こうしておくと、部分的にしかテストしていないのに「完了しました」と言ってしまう、よくある失敗を防げます。

コミット運用とステータス追跡

workflow-patterns install の実務上のメリットのひとつは、AI活用時のリポジトリ衛生を保ちやすいことです。このスキルは、ステータス更新と実装作業を明確に別イベントとして扱います。これは次のような運用に向いています。

• バージョン管理上でタスク進捗を可視化したい
• レビューを整理しやすくしたい
• ワークフローメタデータとコード変更を切り戻しやすくしたい
• 本当に着手中なのか完了なのかを曖昧にしたくない

チームとしてコミットを分けたくない場合は、その方針を最初に伝えたうえで、コミットは分けずに状態遷移だけ保持するよう指示するとよいです。

literalに従うよりworkflow-patternsを調整した方がよい場面

この順序は絶対視するルールブックではなく、リスクを抑えるための制御システムとして使うべきです。環境に応じて調整してください。

• monorepo ではパッケージ単位のテストコマンドが必要なことがある
• レガシーなリポジトリでは最初に characterization test が必要になることがある
• プロトタイプではコミット数を減らしつつも [ ] → [~] → [x] は維持したいことがある
• hotfix ではリファクタリング工程を絞る判断が妥当なことがある

重要なのは、リスク低減に効くチェックポイント、特にテスト先行と明示的な検証を残すことです。

workflow-patternsスキル FAQ

workflow-patternsはConductorユーザー専用ですか？

いいえ。ただし、Conductor流の計画管理とTDDの発想に強く寄っています。workflow-patterns は、そのエコシステム外でも、同等の計画ファイル、タスク順序、検証ルーチンがあれば使えます。逆にそれらがない環境では、このスキルの強みはかなり薄れます。

機能実装では通常のプロンプトよりworkflow-patternsの方が良いですか？

はい。課題が「実行規律」にあるなら、その可能性が高いです。通常のプロンプトでも妥当なコードは出せますが、タスク順序、進捗更新、テスト先行のような点は飛ばされがちです。速度そのものより、一貫性や追跡性が重要な現場では、workflow-patterns usage の方が適しています。

workflow-patternsは初心者向きですか？

中程度です。手順自体は追いやすいものの、次が不足していると初心者には難しい場面があります。

• 明確な plan.md
• 先に失敗するテストを書く自信
• プロジェクト固有の検証コマンド
• 小さくレビューしやすいコミットへの理解

TDDに不慣れなら、フェーズ全体を任せるのではなく、まずはスコープの明確な単一タスクから始めるのが無難です。

どんなときにworkflow-patternsスキルを使わない方がよいですか？

次のような場合は見送った方がよいです。

• タスク計画を維持していない
• 制御された実行より探索的なコーディングが必要
• リポジトリにテスト基盤がほとんどない、または存在しない
• キューに積まれたタスク完了ではなく、アーキテクチャの検討をエージェントにさせたい
• ステータス更新や検証のオーバーヘッドをかけるほどの作業量ではない

こうしたケースでは、より軽量な実装系スキルや直接的なプロンプトの方が適していることがあります。

workflow-patternsにはリポジトリ固有のコマンドや自動化が含まれますか？

含まれません。リポジトリの実体を見る限り、このスキルは補助スクリプトやルールファイル付きのパッケージではなく、実質的に SKILL.md のドキュメントです。価値の中心は実行パターンにあり、運用の細部は利用者が与える必要があります。

不完全だったり散らかった計画でもworkflow-patternsは役立ちますか？

一部までは役立ちます。順序や状態遷移を守らせることはできますが、曖昧なバックログ項目から良い受け入れ条件を自動で生み出すことはできません。タスク定義が弱いなら、強い出力を期待する前に計画そのものを改善すべきです。

workflow-patternsスキルを改善する方法

workflow-patterns向けにタスク定義を強化する

結果を最も早く改善できるのは、タスク文言の質を上げることです。このスキル向けの良いタスクは、振る舞い、制約、完了ラインまで含んでいます。たとえば次の違いがあります。

弱い例:

- [ ] Improve validation

より良い例:

- [ ] Task 2.1: Reject invalid email formats in user registration, return 400 with field-level error, and add tests for valid, invalid, and missing email cases

この一変更だけでも、失敗テストの設計、実装範囲、検証基準がかなり明確になります。

「run checks」ではなく正確なコマンドを渡す

workflow-patterns usage の失敗は、検証条件の指定不足で起きることが非常に多いです。「テストとlintを回す」ではなく、正確なコマンドと必要な環境情報まで渡してください。テストにサービス、fixture、パッケージフィルタが必要なら、それも含めるべきです。

タスク順序をどこまで厳密に守るかを伝える

このスキルは、現在フェーズ内での順次実行を基本にしています。実際の運用で例外が許されるなら、その条件を明示してください。そうしないと、エージェントが必要以上に先送りしたり、逆に勝手に飛ばしたりしてしまうことがあります。方針が明確なほど信頼性は上がります。

Do not skip tasks unless blocked by missing infrastructure.
If blocked, stop and report the blocker instead of jumping ahead.

レガシー比率が高いプロジェクトではリポジトリ固有のTDD指針を足す

成熟したリポジトリでは、純粋な red-green-refactor をそのまま当てはめにくいことがあります。テストハーネスが遅い、アーキテクチャが絡み合っている、といった場合には、このパターンをどう適用するかを明示した方がよいです。

• リファクタリング前に characterization test を優先する
• 変更範囲を触るモジュールに限定する
• 同一タスクで広範囲のクリーンアップをしない
• 既知の flaky test は別途切り分けて扱う

こうしておくと、workflow-patterns を教条的ではなく実務的に使えます。

よくある失敗パターンを先回りで防ぐ

典型的な問題はだいたい決まっています。

• すべてのチェックが通る前にタスクを完了扱いにする
• 実装後にテストを書く
• 一度に複数タスクを編集する
• 進行中の [~] 状態を飛ばす
• ワークフローメタデータと機能実装を曖昧に混ぜる

チームにとって重要なら、これらはプロンプト内で明示的に釘を刺しておくべきです。

タスク完了時の構造化レポートを求める

日々の実務でこのスキルをより役立てるには、各タスクの最後に簡潔な報告フォーマットで締めるよう求めるのが有効です。

• 選択したタスク
• 追加または更新したテスト
• 実装内容の要約
• 検証結果
• plan file のステータス変更
• ブロッカーや次の対応事項

これにより、workflow-patterns guide の出力が、レビュー担当者や次回セッションから見ても信頼しやすいものになります。

最初の実行結果が悪くても、すぐ置き換えずに入力を改善する

初回の結果がぎこちなくても、すぐに workflow-patterns skill 自体が弱いと判断しない方がよいです。たいていの原因は、実行コンテキストの不足です。改善するなら、次の順で入力を整えるのが効果的です。

1. タスク文をより明確にする
2. 検証コマンドを正確に指定する
3. 許可された作業範囲とファイル制約を明示する
4. コミット／ステータス運用の方針を決める
5. ブロッカー発生時の扱いを定義する

これらが揃うと、このスキルは制御された高信頼のタスク遂行をかなり実現しやすくなります。