| name | bizspec-refine |
| description | 業務プロセスを BizSpec YAML(最小 unit)へ分解する。新規プロセスの分解、および既存プロセスへの unit 追加の両方に使う。 |
| argument-hint | ["プロセスの説明"] |
| disable-model-invocation | true |
あなたの役割
ユーザーが与えた業務プロセスを、AIエージェントまたはスクリプトが迷わず実行できる最小単位(unit)へと分解し、BizSpec YAML として出力する。
既存プロセスへの unit 追加も同じスキルで行う。
分解アルゴリズム
ステップ1: プロセスゴールと IPO の明確化
まず対象プロセスのゴールを 1 文で定義する。
例:「Ready な PBI の一覧と SP を揃える」「本番環境へのデプロイが完了し動作確認済みになる」
このゴール定義が core 判定の基準になる。ゴールが曖昧な場合はユーザーに確認する。
次に対象プロセス全体の Input / Process / Output を特定する。
ステップ2: 再帰的な分割
以下の分割停止条件を満たすまで再帰的に分割する。
止めてよい条件(どちらか一方):
- 「このステップをスクリプト(API呼び出し・正規表現・条件分岐)として実装できるか?」→ YES
- 「このステップの指示をAIに与えたとき、判断に迷わず一意に実行できるか?」→ YES
続けるべきサイン:
- 「場合によって異なる」という曖昧さが残っている
- 複数の Output が混在している
- 実行主体が unit 内で切り替わる
安全装置(暴走防止):
- 1 プロセスの unit 数が 15 を超える、または分解の階層が 4 段を超える 場合は分割を止め、ユーザーに「統合可否」を確認する。
- 「これ以上分割すると逆に管理しづらくなる」と感じた段階で、AI 単独で続けず必ずユーザーに判断を仰ぐ。
ステップ3: link の整理
link.up/down は実行順序を表す(データの依存関係ではない)。
link.up: この unit の前に実行される unit
link.down: この unit の後に実行される unit
- データの依存関係は
io.in/out で表現する
executor の判断基準
| 条件 | executor.type |
|---|
| 入出力が定型的(API・正規表現・固定ルール) | script |
| 自然言語の解析・推論・状況判断が必要 | ai_agent |
| 判断がつかない、または承認・署名が必要 | manual |
ai_agent は script で代替できない場合にのみ選ぶ。必ず executor.reason に根拠を 1 行で書く。
core スクリーニング
基準: プロセスゴールの達成に直接必要か
| 判定 | core |
|---|
| この unit がなければプロセスゴールに到達できない | true |
| ゴール達成に直接関与しないことが明確(ログ・通知・レポート・ガバナンス記録等) | false |
| 迷う場合(中間成果物・ガバナンス・証跡等) | ユーザーに確認 |
迷ったときの問いかけ(ゴールを明示して問う):
「『〇〇』ですが、このステップがなければプロセスのゴール『{ゴール}』は達成できませんか?それともガバナンス・記録目的ですか?」
AIが独断で core を確定させてはいけない。
フィールド責務ルーブリック
各フィールドへの書き分けを徹底する。同じ内容を複数フィールドに重複させない。
| フィールド | 責務 | ここには書かない |
|---|
aim | この unit が達成する目的を 1文で | 手順・制約・データ |
rule | 守るべき 制約・判断基準・ガイドライン | 作業手順・データ |
io.in | この unit が受け取る 入力データ(モノ) | アクション・制約 |
io.process | 入力 → 出力への 処理ステップ(IPO の P。手順・動詞句) | 制約・判断基準 |
io.out | この unit が渡す 出力データ(モノ) | アクション・制約 |
迷ったときの判別:
- 「〇〇しなければならない / 〇〇の場合は…」→
rule
- 「〇〇する / 〇〇を行う」という手順 →
io.process
- 名詞(ドキュメント・リスト・結果・フラグ)→
io.in / io.out
出力フォーマット(BizSpec YAML v1)
複数の unit は --- で区切る。
必須部分
unit: <動詞+目的語で簡潔に>
aim: <この unit が達成する目的>
phase: <このunitが属する工程フェーズ(例: spec / dev / test / release)>
rule:
- <制約・判断基準>
link:
up:
- <依存する前工程の unit 名>
down:
- <繋げる後工程の unit 名>
core: true | false | undetermined
io:
in:
- <入力データ>
process:
- <処理手順(動詞句)>
out:
- <出力データ>
executor:
type: script | ai_agent | manual
reason: <選んだ根拠(1行)>
status: draft | review | stable | deprecated
拡張フィールド(条件付きで埋める)
以下は省略可能だが、ユーザーとの会話やプロセス情報から 以下のヒントが得られたら必ず埋める。
これらが揃っていると bizspec viz(ヒートマップ・ステータス色分け・並列エッジ)と /bizspec-refactor(負荷分析・ボトルネック検出)が機能する。
effort:
duration: 0.5
frequency: 4
automation:
difficulty: low | medium | high
status: manual | partially-automated | automated
deprecated_reason: <廃止理由>
埋めるヒューリスティクス:
| ユーザー発言 / 観察 | 埋めるフィールド |
|---|
| 「30 分くらいかかる」「週 2 回やる」など時間・頻度に言及 | effort.duration / effort.frequency |
| 「今は手作業」「自動化したい」「半自動」など現状言及 | automation.status |
| 「スクリプト化は難しい」「API があるから簡単」など難易度言及 | automation.difficulty |
| 「まだドラフト」「廃止予定」などライフサイクル言及 | status の値を変更 |
埋めるかどうか不明なら省略してよい(effort / automation)。
利用できる CLI コマンド
YAML を直接手で書き換えるより、コマンドを使うほうが参照の更新漏れやタイポを防げる。
積極的に使うこと。
| コマンド | 使いどころ |
|---|
bizspec new <process> <unit> [--up ...] [--down ...] | 新規 unit のスケルトン生成(隣接 unit との初期リンクも指定可) |
bizspec rename <process> <old> <new> | unit 名を変更する(link.up/down 参照を一括更新) |
bizspec rm <process> <unit> [--force] | unit を削除する(link 参照を一括削除。フロー分断検知あり) |
bizspec renumber <process> | 大幅な構造変更後にファイルを実行順で揃えたいとき(ユーザーに提案してから実行) |
bizspec validate <process> | 保存後の整合性チェック |
bizspec list <process> | 現在の unit 一覧を把握するとき |
注意: bizspec new --up/--down は新規 unit 側にしかリンクを書かない。
隣接する既存 unit の link.down / link.up は手動で更新する必要がある。
出力先
確定した unit ごとに bizspec/<プロセス名>/<unit名>.yaml として保存する。
<プロセス名> は分解対象のプロセスをケバブケースで表す(例: issue-refinement)。ユーザーが指定した場合はそれを使う。
<unit名> は unit フィールドの値をそのままファイル名にする(変換・ケバブ化しない。例: Ready判定.yaml)
- ディレクトリが存在しない場合は作成する
core: undetermined が残ったまま保存しない(必ずユーザー確認を経てから保存)
- 同名ファイルが既存の場合は保存前に確認する:「上書きしますか?または別名で保存しますか?(候補:
<unit名>_改.yaml)」
検証方法(優先順位順)
保存後の validate は以下の順で試し、成功した方法を使う。
bizspec validate <プロセス名> — CLI がインストール済みの場合
python3 -m bizspec.cli validate <プロセス名> — BizSpec リポジトリ内で作業している場合
- 手動検証 — 上記がいずれも使えない場合、以下を自分でチェックする:
- 必須フィールド(unit / aim / phase / rule / link / core / io / executor / status)の存在
core が true / false のいずれかであること
executor.type が script / ai_agent / manual のいずれかであること
link.up/down の参照先ファイルがすべて存在すること
link.up/down の双方向整合性(A.down に B があれば B.up に A があること)
進め方
新規プロセスの場合
- 不明な点があれば確認してから分解を開始する。曖昧な部分・矛盾・前提不明な箇所は積極的に掘り下げて質問する。すでに明確な情報については質問しない
- 分解結果を YAML で提示し、
core: undetermined の unit についてユーザーに確認する
- ユーザーの回答を反映して YAML を確定する
- 各 unit の失敗モードを掘り起こす(
rule の充実)
YAML 提示後、unit ごとに以下を聞く(まとめて聞いてもよい):
- 「このステップで一番よくある失敗・詰まりポイントは何ですか?」
- 「新しい人がここで間違えやすいことは?」
- 「緊急時・特定の相手・特定の時期など、手順が変わるケースはありますか?」
得られた回答を
rule に追加する。既存の一般論より具体的な内容が出たら差し替えを提案する。
- 粒度の調整(分割 or 統合)の提案は必要に応じて行う
- すべての unit が確定したら
bizspec/ に保存する
- 保存後に検証を実行し、結果をユーザーに報告する(「検証方法」セクション参照)
既存プロセスへの unit 追加・変更の場合
bizspec list <プロセス名> で現在の unit 一覧を把握する
- 必要なら既存 unit ファイルを読み込んでフロー構造を確認する
- 変更の種類に応じてコマンドを使い分ける:
- unit の追加:
bizspec new でスケルトンを生成し、内容を埋める。隣接 unit の link.up/down は手動で更新する
- unit の名前変更:
bizspec rename <process> <old> <new>(link 参照を自動更新)
- unit の削除:
bizspec rm <process> <unit>(フロー分断が検知された場合はユーザーに確認してから --force)
- 保存後に検証を実行し、結果をユーザーに報告する(「検証方法」セクション参照)
検証後のエラー対応
| エラー種別 | 対応 |
|---|
link の双方向不整合(A.down に B があるが B.up に A がない) | どちらのリンクが誤りかを判断できないため、ユーザーに選択肢を提示して確認する(例:「①B.up に A を追加する ②A.down から B を削除する、どちらが正しいですか?」)。確認後に修正して再検証 |
link 参照先が存在しない(タイポ等) | 候補ファイル名と照合して一意に特定できれば自動修正、できなければユーザーに確認 |
必須フィールド欠落・core / executor.type の値不正 | 原因を示してユーザーに確認(値の選択が必要なため) |
| その他 | 原因を示してユーザーに確認 |