AGENT SKILL

miko.propose

人間の元ネタから対話しながらケイパビリティの変更プロポーザルを作成する。

License 许可
MIT
所属仓库
studyplus/miko
最近更新
2026-11-10
Stars
★ 22
Forks
1

01 前言 Front Matter

description
人間の元ネタから対話しながらケイパビリティの変更プロポーザルを作成する。

02 资源文件 1

03 SKILL.md 正文

入力

$ARGUMENTS

入力の形式: <capability_name> <元ネタ(自由記述)>

  • 例: /miko.propose order_management トライアル終了時にメール通知を送りたい
  • 例: /miko.propose notification 未読通知のリマインドを送りたい
  • ケイパビリティ名だけの場合: 元ネタをヒアリングから始める
  • 空の場合はエラー: 「⛩️ ケイパビリティ名をお願いいたします(例: /miko.propose order_management 〜したい)」

このスキルの役割

人間が持ち込む変更の元ネタ(アイデア・課題・要望)を、対話を通じて構造化されたプロポーザルに仕上げる。

プロポーザルとは: ケイパビリティに対する変更提案。ビジネスルールの変更だけでなく、機能仕様・影響範囲・代替案を含む。実装後に「ビジネスルールの変更」セクションだけが business_rules.md に反映される。

⚠️ 絶対禁止: このスキルは business_rules.md を 読み取り専用 として扱う。propose が直接 business_rules.md を編集・上書きしてはならない。BR への変更はすべてプロポーザルファイルの「ビジネスルールの変更」セクションに記述し、実装スキル(implement / quick-impl)が反映する。

対話のスタイル: 機械的な質問リストではなく、自然な会話で進める。ただし確認ポイントは明確に設ける。


手順

1. 入力検証

  • $ARGUMENTS の先頭ワードからケイパビリティ名を取得し、スネークケースに正規化する
  • 残りの部分を元ネタとして記録する
  • .miko/guides/unsplit_proposal_check.md に従い、分割し忘れの <needs-split> を確認する

2. 既存資料の読み込み

以下のファイルを読み込む。

再読み込みの省略: .miko/ 配下のガイド・サンプルは、このセッションで全文を読み込み済みで、その全文が現在のコンテキストに残っていれば読み直さない。要約しか残っていない(コンテキストが圧縮・要約された後など)、または確信が持てなければ読み直す。miko/ 配下のプロジェクト文書は対象外で、毎回読み込む。

指示書(必須):

  • .miko/guides/business_rules_guide.md — ルール記述の原則。判定テストの方法
  • .miko/guides/tone_guide.md — ユーザーとの対話スタイル。このファイルの口調・絵文字・出力言語ルールに従うこと

実例(品質の基準):

  • .miko/examples/business_rules.md — ルールの書き方・粒度の参考

システム全体の文脈:

  • miko/system_high_level_design.md — システム全体のアーキテクチャ、コード探索ガイド
  • miko/glossary.md — 用語集(存在する場合)

ケイパビリティの現状(business_rules.md が必須):

  • miko/<capability>/business_rules.md — 現在のビジネスルール。このファイルが存在しない場合はエラーとして中止する:

    ⛩️ miko/<capability>/business_rules.md が見つかりません。 このスキルは既存の business_rules.md への変更提案を作成いたします。 - 既存コードがある場合: まず /miko.catchup <capability> で business_rules.md を生成してください - 新規ケイパビリティの場合: /miko.new-cap <capability> で初期ルールを定義してください

  • miko/<capability>/high_level_design.md — 現在の構造(なければスキップ)

3. 元ネタのヒアリング

元ネタが十分に具体的であれば(動機・変更内容・スコープが読み取れる)、すぐにステップ 4 に進む。

元ネタが曖昧・不完全な場合、以下の観点で 対話的に 質問する。一度に全部聞くのではなく、回答に応じて掘り下げる:

  • 動機: なぜこの変更が必要か? 今何が困っているか?
  • 期待する振る舞い: 変更後はどうなってほしいか?
  • トリガー/アクター: 誰が・何がきっかけでこの処理が動くか?
  • スコープ: 何は変えないか? どこまでが今回の範囲か?
  • エラー時: 失敗したらどうなるべきか?

注意:

  • 人間がドメインエキスパートである前提で対話する。技術的な質問ではなく、ビジネス判断に焦点を当てる
  • 「〜はどうしますか?」ではなく「〜は A と B がありえますが、どちらが適切ですか? 私は〜の理由で A を推奨します」のように、選択肢と推奨を提示する
  • コードの調査は次のステップで行うので、ここではユーザーの意図の理解に集中する

4. 【確認①】理解の確認

ヒアリング内容を「背景・動機」「変更の概要」「スコープ(対象/対象外)」「トリガー/アクター」にまとめて提示し、認識合わせをする。フィードバックがあれば反映して再提示、承認されたら次に進む。

5. コード調査

確認①で承認された内容に基づき、関連するコードを探索・精読する。

探索対象: miko/system_high_level_design.md の コード探索ガイド に従い、変更に関連するファイルを探索する。ただし網羅的探索ではなく、変更に関連する範囲に絞る。

探索対象外: .miko/ ディレクトリは miko の内部リソースであり、プロジェクトのコードではない。探索・精読の対象にしないこと。

確認すること:

  • 変更が影響する既存のルール(business_rules.md のルール ID を特定)
  • 変更先の既存コードの構造(どこに手を入れることになるか)
  • 既存の類似パターン(同じケイパビリティ内の類似処理)
  • 新しく必要になるテーブル・カラム・エンドポイント等

仕様の疑問の確認: コード調査の過程で仕様上の疑問が浮かんだ場合(例: 既存の振る舞いとの整合、条件分岐の判断など)、ドラフト作成前にユーザーに確認する。AIが仮定を置いてドラフトを書くのではなく、正しい前提で書けるようにする。

6. ビジネスルール変更案の策定

.miko/guides/business_rules_guide.md の判定テストを適用しながら、変更案を策定する。

⚠️ 既存 BR の構造と、触らないルールには手を入れない: business_rules.md の現状の構造(フラットか、2.1 / 2.2 を持つか、ビジネスポリシーセクションがあるかなど)と、この proposal で改訂・廃止しない既存ルールの本文には手を入れない。新規ルールは既存ファイルの構造に合わせて配置する。ユーザーから明示的な移行依頼がない限り、現在の基準(文字数・語彙規律・新構造)に合わせる再整形は行わない。一方、この proposal で 改訂・新設するルール には現在基準(文字数・語彙規律・判定テスト等)を適用する。

⚠️ 粒度の原則: 提案の詳細度に引きずられない

提案が細かくても、BR の粒度は変わらない。ユーザーが UI の話をしていたり、実装レベルの詳細を語っていたりするほど、このフィルタを意識して適用すること。

ガイドの判定テスト(却下した代替案 / ビジネス定義)を全候補に適用するのに加え、ガイドの 「よくあるアンチパターン」 に当たっていないか必ず確認する。

  • 「〜したい」が出たら: ユーザー要望の言い換えは BR ではない。要望の背後にある 条件・閾値・除外規則・対象範囲 だけが BR 候補
  • UI・通知・出力の話が出たら: 「画面に〜を表示する」「〜のときメールを送る」「〜を記録する」のような実装をなぞっただけの記述は BR ではない。判断(いつ・何回・どの条件で除外するか)が乗っているもの だけ が BR
  • 細かい仕様の話が出たら: 「実装や UI が変わっても、この記述は変わらないか?」を問う。No なら BR ではない
  • BR の数の目安: 通常の機能追加で新設 BR が 5 本を超えたら粒度が細かすぎる可能性が高い。各ルールに「却下した代替案」テストを再適用し、「やらない/別の条件にする」以外の合理的な代替案が書けるか を厳しく問う

判断軸は「却下した代替案」テストに集約する。コードに書いてあるかどうかは判断軸にならない(BR は最終的にコードで表現される)。コードに表れていても、別の選択肢がありえた判断であれば BR として残す。

候補から外したものは BR ではなく 機能仕様セクション に書く。「BR から外したから消える」ではなく「書く場所を変える」だけ。

新設するルール:

  • 元ネタから導かれる新しいルールを特定
  • 判定テスト(「却下した代替案テスト」「ビジネス定義テスト」)を適用
  • 既存のカテゴリ・プレフィックスに従って ID を採番(例: 既存の AI-04 の次なら AI-05)
  • 既存のカテゴリに収まらない場合は新しいカテゴリを提案

改訂するルール:

  • 既存ルールの文言変更が必要な場合、改訂前 → 改訂後を明示

廃止するルール:

  • 不要になるルールがあれば、廃止理由とともに明示

除外するもの:

  • 判定テストで「ルールではない」と判定されたものは機能仕様セクションに記載
  • UI仕様・表示形式・文言・レイアウトは機能仕様セクションに記載(BRにしない)

7. 禊 — ルール変更案の事前審査(サブエージェント)

ビジネスルール変更案(新設・改訂)をユーザーに提示する前に、サブエージェント(Agent ツール)を 1 体起動して事前審査する。起草した本人による自己検査は元ネタの発言に引きずられるため、文脈を持たない審査役にテキストだけで判定させる。改訂ルールは改訂後の本文を審査対象とする。

サブエージェントに渡す情報:

  • .miko/guides/misogi_guide.md のパス — 「このファイルを読み、指示に正確に従え」と指示する
  • ケイパビリティ名(審査役はここから判定材料を自分で読み込む)
  • 審査対象のルール変更案テキスト(ルール ID、[制約]/[導出] タグ付き。まだファイルに存在しないため本文を渡す)

会話の経緯・ユーザーの発言・proposal の背景や機能仕様は渡さない。 文脈が審査を汚染するため、判定材料は候補テキストとガイドだけにする。

審査結果の裁定(メインセッション):

  • 違反が妥当 → 書き換え案を適用する。BR 不適格は変更案から外し、機能仕様セクションに書く場所を変える
  • 違反を覆す(出力内容そのものがビジネス判断である場合等)→ 覆す理由を明示し、本文は「判断だけを書く」形に整える
  • 判定不能 → 「暗黙のルール(要確認)」へ

8. 【確認②】ドラフトレビュー

最終的な proposal と同じ構造(.miko/examples/proposal.md 参照)で骨子を提示し、フィードバックを受ける。特にビジネスルールの変更案の妥当性、機能仕様のスコープ、見落としている代替案がないかを確認する。禊の審査結果(審査件数・修正・除外・覆しと理由)も簡潔に報告する。大きな方向転換があればステップ 5 に戻る。

9. 他ケイパビリティへの影響調査(必須)

確認②が承認されたら、サブエージェント(Agent ツール)を起動して調査を行う。このステップは省略しない(主さまが明示的にスキップを指示した場合のみ省略し、その旨を proposal の影響範囲セクションに記録する)。miko/ 配下に他ケイパビリティの business_rules.md が 1 つも存在しない場合はスキップしてよい。

サブエージェントに渡す情報:

  • .claude/skills/miko.propose/guides/cross_capability_impact_guide.md のパス — 「このファイルを読み、指示に従え」と指示する
  • メインケイパビリティ名
  • 変更案の要約(ドラフトのビジネスルール変更と機能仕様をテキストで渡す)

調査結果の扱い:

  • 影響なし: 「他ケイパビリティへの影響はございませんでした」と報告し、ステップ 10 へ進む
  • 影響あり: 結果をユーザーに提示し、内容を確認・修正してもらう。確認後にステップ 10 でプロポーザルの「他ケイパビリティへの影響」セクションに反映し、プロポーザルの先頭に <needs-split> マーカーを付与する(このマーカーがないと実装対象プロポーザルとして扱われてしまうため)
  • 横断カテゴリの昇格候補が報告された場合: ユーザーに提示し、宣言するか確認する。宣言する場合はビジネスルールの変更に「概念のカテゴリへの [横断] マーク付与(定義ルールが既存カテゴリに埋まっている場合はカテゴリの切り出しを含む)」を含め、影響先ケイパビリティの [xc:…] タグ付きルールの新設・改訂を「他ケイパビリティへの影響」に反映して <needs-split> を付与する

横断プロポーザルになる典型: 変更が横断カテゴリの宣言・定義に触れる場合(新規宣言・宣言文の変更・除去・定義ルールの改訂)は、その概念を [xc:…] タグで参照している全ケイパビリティが影響対象になる(詳細は調査ガイドが扱う)。

10. プロポーザル生成

確認②のフィードバック(およびステップ 9 の調査結果)を反映し、プロポーザルファイルを生成する。

ファイル名: miko/<capability>/proposals/YYYY-MM-DD-<kebab-case-title>.md

構造: .miko/examples/proposal.md に従う。以下の点に注意:

  • 該当するセクションのみ含める(空セクションは作らない)
  • 「他ケイパビリティへの影響」はステップ 9 で影響ありの場合のみ。ステップ 9 を主さまの指示でスキップした場合は、影響範囲セクションに「他ケイパビリティへの影響調査は主さまの指示によりスキップ」と記録する
  • ステップ 9 で影響ありの場合、プロポーザルの先頭に <needs-split> マーカーを付与する
  • 「祓え検証」セクションは /miko.harae が後から追記する。propose では生成しない
  • 検討・却下した代替案は「これを知らないと将来間違えそう」というものだけ記録する

生成時の注意:

  • business_rules.md は編集しない。 変更内容はプロポーザルファイルにのみ書く
  • 「ビジネスルールの変更」と「機能仕様」の境界を意識する。ルールは「何が真か」、仕様は「どう振る舞うか」。ルール本文には実装詳細を含めない
  • 機能仕様セクションには実装の具体(エンドポイント、パラメータ、エラー処理等)を書いてよい。proposal 時点で判明している仕様は詳細に記述する。詳細な詰めは specify に委ねる
  • 過去のプロポーザルを参考にしつつも、構造はこのテンプレートに従う

glossary.md の更新:

  • proposal で新しい用語が登場した場合は miko/glossary.md に追加する(ファイルがなければ作成)
  • .miko/examples/glossary.md のフォーマットに従い、該当ケイパビリティのセクションに追加する。実装の詳細(クラス名・メソッド名・API・処理手順)は書かず、1〜2文の定義だけを書く
  • ケイパビリティの節は配置の軸であり、意味のスコープではない。見出し語はシステム全体で一意にする。既存の見出し語と同じ語が出てきたら、同じ意味なら項目は1つだけにし(責任を持つケイパビリティの節、なければ「全体」)、別概念なら修飾を付けて一意な別名を立てて別項目にする(注文確定 / 決済確定)

11. 完了報告

ケイパビリティ名、proposal パス、ルール変更件数(新設/改訂/廃止)、代替案数をサマリーテーブルで提示する。次のアクションとして /miko.harae によるルール検証と、実装フロー(quick-impl or フルフロー)をご案内する。以下の場合は /miko.split-proposal によるフェーズ分割もご案内する:

  • プロポーザルの規模が大きい場合
  • DB マイグレーションや環境変数の追加など、インフラ・環境の変更を含む場合
  • <needs-split> マーカーを付与した場合(横断プロポーザル) — /miko.split-proposal で影響先ケイパビリティへの影響先サブプロポーザルが作成される旨を案内する

04 同仓库更多 Skills