diff --git a/CHANGELOG.md b/CHANGELOG.md index 5923997..bf63961 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## v1.5.0 (2026-09-05) + +### New + +- **横断カテゴリ（cross-cutting category）を導入** — 複数ケイパビリティに効果が及ぶルール（例: 規約違反ユーザーの発信制限）を管理する仕組み。BR の階層（ケイパビリティ / カテゴリ / ルール）を（パッケージ / モジュール / 関数）と見立て、横断カテゴリを**カテゴリの可視性修飾**として表現する: オーナーは概念のカテゴリ見出しに `[横断]` マークと `` マーカーを付けて public 化し（lead 文が宣言文、定義はカテゴリ内の通常ルール）、効果を持つケイパビリティは自分のルールに `[xc:{cap}/{プレフィックス}]` タグを付けて参照する（import に相当）。非適用は記録しない。一覧は `grep 'cross-category' miko/*/business_rules.md`、特定概念の全体像（宣言 + 全適用ルール）は ID の grep で都度導出し、中央レジストリは持たない。public カテゴリの改名・分割・マーク変更は proposal 必須（private カテゴリの再編は従来どおり自由）。網羅性は記録や事後監査ではなく **プロセスの門で構成的に保証する** — ケイパビリティ × 概念の全ペアは、概念の宣言（propose の影響調査）かケイパビリティの新規作成（new-cap の判定ステップ）の遅い方で必ず一度検討される。判定テスト（他者性・全称性・必達性）、ID・マーク・タグの書式、書き込み時 lint（orphan 参照・マーク整合・書式）を `business_rules_guide.md` の「横断カテゴリとは何か」に定義。`.miko/examples/business_rules.md` に実例（横断カテゴリ `xc:order_management/DEFAULT` とタグ付きルール ORD-05）を追加。検討経緯と却下した代替案（中央レジストリ・ルール単位マーク・適合セクション・非適用の記録・グローバル連番 ID・専用セクション + 宣言行・harae での網羅監査）は `business_rules_driven_development.md` の「解決済みの論点」を参照 + +### Changed + +- **`/miko.propose` の他ケイパビリティ影響調査を任意から必須に変更** — 従来の「調査しますか？」の確認をやめ、デフォルトで実行する（主さまが明示的にスキップを指示した場合のみ省略し、proposal に記録）。横断カテゴリの網羅保証の門その 1。調査ガイドに横断カテゴリの観点（宣言・定義に触れる変更の影響先を ID の grep で特定、昇格候補の報告）を追加 +- **`/miko.new-cap` に全ケイパビリティ BR の関連調査（サブエージェント・必須）と横断カテゴリの判定ステップを追加** — 従来は「外部との接点」に挙がった隣接 BR だけを読んでいたが、新規ケイパビリティ作成時が横断ルールの取りこぼしが最も起きやすいため、全 BR の走査と、宣言済み横断カテゴリの判定（grep → 対話 → 効果を持つならタグ付きルールを作成）を必須化。横断カテゴリの網羅保証の門その 2 +- **BR を更新するスキルに書き込み時 lint を追加** — `/miko.quick-impl`・`/miko.speckit.implement`・`/miko.catchup`・`/miko.quick-catchup`・`/miko.new-cap` は BR 更新直後に横断カテゴリの構文検査（orphan `xc:` 参照・`[横断]` マークとマーカーの整合・横断カテゴリとタグの書式）を実行する + ## v1.4.2 (2026-07-28) ### Changed diff --git a/business_rules_driven_development.md b/business_rules_driven_development.md index 2f9038e..7356430 100644 --- a/business_rules_driven_development.md +++ b/business_rules_driven_development.md @@ -268,6 +268,7 @@ proposal に代替案を追記（AI：重要な検討経緯があれば） - **ビジネスポリシー（ビジネス方針）**: `POL-{連番}` 形式。ケイパビリティを貫く価値判断。3〜5 個程度を目安に少数に保つ。セクション末尾に `` で最終採番を記録する - **2.1 ドメインビジネスルール / 2.2 システムビジネスルール**: ルールを「紙運用」テストで振り分けて配置する。カテゴリ（ORD、PAY 等）はどちらか一方に置く +- **横断カテゴリ**: 専用セクションは持たない。オーナーがカタログ内のカテゴリに `[横断]` マークを付けて宣言する（カテゴリ＝モジュール、横断＝可視性）。詳細は「解決済みの論点 > 横断的なビジネスルールの管理」と `ofuda/guides/business_rules_guide.md` の「横断カテゴリとは何か」を参照 ### 操作の定義（Operations） @@ -379,6 +380,42 @@ miko//proposals/ ## 解決済みの論点 +### 横断的なビジネスルールの管理（横断カテゴリ） + +**決定（v1.5.0〜）:** 複数ケイパビリティに効果が及ぶルール（例: 「規約違反ユーザーは各所で発信系の操作が制限される」）は、**横断カテゴリ**という一級市民の仕組みで管理する。 + +**構造:** + +- **横断しているのはルール（文）ではなく概念（名詞）。** ルールは書き方次第で分割・統合される不安定な単位のため、義務は概念に付ける。横断なのはエンティティ（ユーザー）ではなく状態（規約違反）である +- **カテゴリ＝モジュール、横断＝可視性。** BR の階層（ケイパビリティ / カテゴリ / ルール）は（パッケージ / モジュール / 関数）に対応する。カテゴリは既定で private（オーナーが自由に再編できる整理棚）だが、`[横断]` マークで public モジュールになり、名前が公開 API になる。共有の実体は関数（ルール）だが、思考と契約の単位はモジュール（カテゴリ）— という プログラミングの直感に合わせる。可視性 ≠ 義務（義務の根拠は判定テストを通った宣言文）であり、将来「特定ケイパビリティにのみ公開」等が必要になれば別のマークを立てる +- **判定テスト（3 問すべて Yes で横断カテゴリ）:** ①他者性 — 他ケイパビリティが所有する操作の可否・意味を変えるか ②全称性 — 義務の相手を列挙できないか（将来のケイパビリティも対象か。列挙できる二者間依存は境界セクションで足りる） ③必達性 — 新しいケイパビリティを作る人に必ず伝えることか +- **概念 ID:** `xc:{ケイパビリティディレクトリ名}/{カテゴリプレフィックス}`（例: `xc:user_management/TOS`）。ID がオーナー BR へのポインタを兼ねる。プレフィックスは既存機構の再利用で、新しい採番・命名はない +- **宣言（オーナーのみ）:** 概念のカテゴリ見出しに `[横断]` マーク + `` マーカーを付け、lead 文に宣言文（各ケイパビリティが何を表明すべきかの軸）を書く。定義はカテゴリ内の通常ルール。定義が既存カテゴリに埋まっている場合は public 化の時点でカテゴリを切り出す。マークの付与・除去・横断カテゴリの改名は proposal 必須（横断プロポーザル）。private カテゴリの再編は従来どおり自由 +- **適用（効果を持つケイパビリティ）:** 効果を担うルールに `[xc:…]` タグを付ける（import に相当。置き場は自分のカテゴリでよく、オーナーの分類法を持ち込まない）。「概念に誰が応えているか」は ID の grep で都度導出する（宣言 + 全適用ルールが 1 コマンドで列挙される） +- **非適用は書かない。** 「検討したが効果を持たない」の記録は持たない（propose の影響調査が「調査したケイパビリティの一覧」を proposal に残すのみ） +- **一覧は grep で導出:** `grep -n 'cross-category' miko/*/business_rules.md`。中央レジストリファイルは持たない（本体と索引の二重管理によるズレを避ける）。機構自体は guide とスキル手順（miko 本体、upgrade で配布・復元される）が所有する + +**網羅性は記録ではなくプロセスの門で保証する（構成的保証）:** ケイパビリティ × 概念のすべての組は、どちらか遅い方の誕生イベントで必ず一度検討される。 + +1. **門 1 — propose の他ケイパビリティ影響調査（必須化）:** 概念の宣言・変更は横断プロポーザルになり、影響調査が全ケイパビリティに判定を下す。調査は昇格候補（未宣言の横断関係）の発見も担う +2. **門 2 — new-cap の横断カテゴリ判定ステップ（新設）:** 新規ケイパビリティ作成時に宣言を grep し、各概念について対話で判定する。適用なら `[xc:…]` タグ付きルールを作る + +加えて、BR を更新するスキルは更新直後に **書き込み時 lint**（orphan `xc:` 参照・`[横断]` マークとマーカーの整合・横断カテゴリとタグの書式）を実行する。harae に横断カテゴリの必須ステップは持たせない — harae は完成したはずのルール体系を攻撃的に疑う事後の監査であり、必ず通るべき門をそこに置くと保証にならないため（不完全性軸の攻撃観点の一つとして残るのみ）。 + +**既存 BR への遡及なし:** `[横断]` マークとタグは概念に関わる変更（proposal / new-cap）が入ったときに初めて現れる。マイグレーション不要。 + +**検討・却下した代替案:** + +- **glossary での管理** — glossary は参考情報でありルールとして管理・強制されない。ただし「横断するのは用語（概念）」という着眼だけは採用した +- **ルール単位の `[横断]` マーク（横断性の宣言をルールに付ける）** — ルールは言い回しで分割・統合されるため、マークの付け先が不安定。なお採用した `[xc:…]` タグは別物で、概念への「参照」なので分割・統合で壊れない +- **中央レジストリファイル / system HLD への機構の記載** — レジストリは本体と索引の二重管理でズレる。system HLD はプロジェクトが編集できるデータであり、miko の機構を置く場所ではない（消されても誰も復元しない） +- **サブエージェント全走査のみ（宣言なし）** — 走査は確率的な想起であり、漏れたことを検出する分母がない。門の入力源（昇格候補の発見）として併用する +- **適合セクション（各 BR に全宣言への適用/非適用を明示する verdict 台帳）** — 適用行はルール側タグと二重管理になり、非適用行は概念 × ケイパビリティの積で増えるノイズ。網羅性を「事後の照合」で保証する発想の産物で、門の構成的保証に置き換えて廃止 +- **非適用の記録（BR / harae.md / proposal のいずれかに残す）** — 「無記載と検討済みの区別」は事後照合が前提のときだけ必要。門で保証するなら証明の役目を失う。理由の陳腐化（後から該当操作が増える等）は記録では検出できず、残す理由にならない +- **グローバル連番の概念 ID（XC-01 等）** — 並行ブランチで採番が衝突し、番号が情報を担わない。概念は少数で名前が一意なので、修飾付き名前で足りる +- **専用セクション + 宣言行（カテゴリとは独立した公開面）** — カタログ再編の自由を守るための間接層だったが、可視性の意味論（public にしたカテゴリだけ再編が契約変更になり、private は自由なまま）で同じ目的がより一般的に達成できる。カテゴリ＝モジュールの見立てに置き換えて廃止 +- **消費側も同名カテゴリで持つ（アスペクト複製型）** — オーナーの分類法を消費側に強制することになる。効果ルールの置き場は消費側のドメインの整理に従い、タグで参照する + ### 複数ケイパビリティにまたがる変更 **決定（v0.6.0〜）:** umbrella/sub パターンに統一する。propose で横断影響を含む 1 本のプロポーザルを作成し、split-proposal で影響先ケイパビリティに影響先サブプロポーザルを作成する。implement は各サブの BR 変更に従って各ケイパビリティの business_rules.md を更新する。 @@ -388,8 +425,7 @@ miko//proposals/ ``` /miko.propose 時: → 対話でドラフトを確定 - → 「他ケイパビリティへの影響を調査しますか？」と確認 - → サブエージェントが business_rules.md 存在するケイパビリティを走査 + → サブエージェントが business_rules.md 存在するケイパビリティを走査（必須。v1.5.0 で任意から必須に変更） → 調査結果をもとに proposal の「他ケイパビリティへの影響」セクション + マーカーを付与 → 完了報告で /miko.split-proposal の実行を案内 diff --git a/ofuda/VERSION b/ofuda/VERSION index 1a6966b..7e45753 100644 --- a/ofuda/VERSION +++ b/ofuda/VERSION @@ -1,2 +1,2 @@ -1.4.2 -202607281022 +1.5.0 +202609070637 diff --git a/ofuda/examples/business_rules.md b/ofuda/examples/business_rules.md index 72b1549..0533e9e 100644 --- a/ofuda/examples/business_rules.md +++ b/ofuda/examples/business_rules.md @@ -92,6 +92,12 @@ stateDiagram-v2 - **ORD-04** [制約] 猶予期間経過後のキャンセルは管理者操作でのみ可能とする。 +- **ORD-05** [制約][xc:order_management/DEFAULT] 支払い不履行ユーザーが同時に持てる未決済の注文は 1 件までとする。決済済みの注文には影響しない。 + + +
実装マッピング @@ -100,10 +106,11 @@ stateDiagram-v2 - ORD-02 → `Ec::OrdersController#cancel` / キャンセル前のガード - ORD-03 → `Ec::Order::CANCEL_GRACE_PERIOD` / 定数定義 - ORD-04 → `Ec::OrderPolicy#cancel?` / ロール判定 +- ORD-05 → `Ec::Order#confirmable?` / 未決済注文数の判定
- + --- @@ -128,6 +135,38 @@ stateDiagram-v2 --- +#### 支払い不履行ユーザー（DEFAULT）[横断] + +未決済の自動キャンセルを繰り返したユーザー。 +各ケイパビリティは、与信が発生する操作（後払い・予約・取り置き等）の制限を表明すること。 + + + +**ルール:** +- **DEFAULT-01** [導出] 直近90日間で未決済による自動キャンセル（PAY-01）が3回発生したユーザーは「支払い不履行ユーザー」と定義する。 + + + +
実装マッピング + +- DEFAULT-01 → `Ec::Orders::PaymentDefaultQuery` / 直近90日の自動キャンセル集計 + +
+ + + +> **サンプル解説（実際の business_rules.md には書かない）:** この概念が「横断」なのは、注文管理の外の操作にも効くからである。効果を持つ**他ケイパビリティ側**の書き方は、例えば `miko/reservation/business_rules.md`（予約管理）では次のようになる — 自分のドメインのカテゴリに自分のルールとして書き、タグで参照する: +> +> ```markdown +> - **RSV-04** [制約][xc:order_management/DEFAULT] 支払い不履行ユーザーは商品の取り置きを申し込めない。 +> ``` + +--- + ### 2.2 システムビジネスルール #### 決済連携の非同期処理（RETRY） diff --git a/ofuda/guides/business_rules_guide.md b/ofuda/guides/business_rules_guide.md index 53dcc1b..1096af2 100644 --- a/ofuda/guides/business_rules_guide.md +++ b/ofuda/guides/business_rules_guide.md @@ -325,6 +325,102 @@ high_level_design.md（AI が更新：構造の変化） --- +## 横断カテゴリとは何か + +**横断カテゴリとは、他ケイパビリティが所有する操作の可否や意味を変える状態・属性（横断的な概念）を表す public なカテゴリである。** 「規約違反ユーザー」「凍結テナント」のように、状態の定義は 1 つのケイパビリティが持つが、効果はシステム全体に及ぶ。 + +横断カテゴリは、**まだ存在しないケイパビリティも含めた全ケイパビリティ**に「この状態にどう向き合うか」の検討を義務づける。義務をルール（文）ではなくカテゴリ（が表す概念）に付けるのは、ルールは書き方次第で分割・統合される不安定な単位である一方、概念は言い回しで増減しないためである。 + +### 判定テスト: 横断カテゴリにすべきか + +候補の状態・属性を横断カテゴリとして public 化すべきかは、以下の 3 問で判定する。**すべて Yes のときだけ**横断カテゴリにする。 + +1. **他者性**: その状態・属性は、**他ケイパビリティが所有する操作**の可否や意味を変えるか？ 自ケイパビリティの操作しか変えないなら No（例: 注文の「出荷済み」はキャンセル可否を変えるが、それは注文管理自身の操作 → No） +2. **全称性**: 義務の相手を列挙できないか？ 特定の 2〜3 ケイパビリティ間の話なら、境界セクションとルールの相互参照で足りる（No）。**将来作られるケイパビリティも対象**になるものだけが Yes +3. **必達性**: 新しいケイパビリティを作る人に、中身を聞く前に必ず伝えるべきことか？ + +**数の目安**: 横断カテゴリはシステム全体で数個に収まるはずである（例: 規約違反ユーザー、テナント分離、料金プランによる機能制限、退会ユーザーのデータ保持）。10 個に近づいたら、判定テストの運用が緩んでいるか、ドメイン設計自体の問題（神概念の存在）を疑う。 + +**横断なのはエンティティではなく状態である。** 「ユーザー」という概念全体が横断なのではない。「規約違反」という特定の状態だけが横断であり、「メール確認済み」「最終ログイン日時」はオーナーに閉じる。 + +### カテゴリ＝モジュール、横断＝可視性 + +BR の階層（ケイパビリティ / カテゴリ / ルール）は、プログラミングの（パッケージ / モジュール / 関数）に対応する。横断カテゴリはこの見立ての上の**可視性修飾**である: カテゴリは既定で private（オーナーの整理棚。自由に分割・改名・統合してよい）だが、`[横断]` マークを付けたカテゴリは **public モジュール**になり、その名前（プレフィックス）は他ケイパビリティから参照される公開 API になる。 + +- public にしたカテゴリの改名・分割・除去は契約変更であり、proposal 必須（横断プロポーザル）。private カテゴリの再編は従来どおり自由 +- 概念の定義ルールが既存カテゴリの中に埋まっている場合は、public 化の時点で概念のカテゴリとして**切り出す**（関数を公開したくなったらモジュールを抽出するのと同じ。凝集を強制する良い圧である） +- 可視性 ≠ 義務: 全ケイパビリティに検討を義務づける根拠は `[横断]` マークではなく、判定テストを通った宣言文である。現時点のマークは「public かつ全称義務」の 1 種類のみ + +### 責務の分担 + +| 何を | どこに書くか | +|---|---| +| 横断カテゴリの宣言（義務の発生源・判断の軸） | オーナーの BR の横断カテゴリ（`[横断]` マーク + lead 文） | +| 概念の定義（誰がその状態になるか・解除条件） | 横断カテゴリ内の通常ルール（[導出] / [制約]） | +| 各ケイパビリティでの具体的な効果 | 効果を持つケイパビリティの通常ルール（`[xc:…]` タグ付き。置き場はそのケイパビリティ自身のカテゴリ） | +| 非適用（効果を持たない判断） | **書かない**（後述） | + +効果を各ケイパビリティに書くのは、「チャットでは発言不可・いいねは可」のような線引きが**そのケイパビリティのドメインで下した判断**（「却下した代替案」テストが働く場所）だからである。オーナーには判断の軸（宣言文）だけを書き、他ケイパビリティの操作は列挙しない。オーナーの分類法（カテゴリ名）を消費側に強制しない — 消費側のルールは自分のドメインのカテゴリに置き、タグで参照する。 + +### 横断カテゴリの ID + +横断カテゴリの ID は `xc:{ケイパビリティディレクトリ名}/{カテゴリプレフィックス}` 形式である。 + +- ケイパビリティ部は `miko/` 配下のディレクトリ名をそのまま使う。ID がオーナーの BR ファイルへのポインタを兼ねる +- プレフィックス部は横断カテゴリの英字プレフィックスそのもの（例: `xc:user_management/TOS`）。新しい命名機構は導入しない +- 日本語の業務用語（「規約違反ユーザー」）は glossary とルール本文の語彙のまま使う。ID は参照用の機械キーであり、対訳はカテゴリ見出しが持つ + +### 宣言の書き方（オーナーの BR の横断カテゴリ） + +概念のカテゴリ見出しに `[横断]` マークと機械マーカー `` を付け、lead 文として宣言文（モジュールの docstring に相当）を書く。定義ルールはカテゴリ内の通常ルール。 + +```markdown +#### 規約違反ユーザー（TOS）[横断] + +規約違反が確定したが、ビジネス上 BAN はできないユーザー。 +各ケイパビリティは、ユーザーが発信する操作への制限を表明すること。 + +**ルール:** +- **TOS-01** [導出] 通報が確定し、かつ有償契約が継続中のユーザーは「規約違反ユーザー」と定義する。 +- **TOS-02** [制約] 規約違反状態の解除は運営者の手動操作でのみ行える。 +``` + +- 宣言文には、概念の説明と「各ケイパビリティが何を表明すべきか」の軸を書く。個別ケイパビリティの操作名は列挙しない +- マーカー `` は横断カテゴリの見出し行以外に書かない。**システム全体の横断カテゴリ一覧はこの grep で都度導出する**（中央のレジストリファイルは持たない）: + +```bash +grep -n 'cross-category' miko/*/business_rules.md +``` + +- **`[横断]` マークの付与・除去、横断カテゴリの改名・分割は proposal 必須。** 全ケイパビリティに検討の義務を課す（または契約を変える）変更であり、横断プロポーザル（``）として全ケイパビリティへの影響を扱う + +### 適用の書き方（効果を持つケイパビリティのルール） + +横断カテゴリの効果を担うルールは、タグ位置に横断カテゴリの ID を付ける（モジュールの import に相当）。 + +```markdown +- **ORD-05** [制約][xc:user_management/TOS] 規約違反ユーザーは注文コメントを投稿できない。 +``` + +- ルール本文は通常どおりビジネス語彙（日本語の用語）で書く。タグが機械可読なリンクを担う +- **オーナー自身が自分の概念の効果ルールを持つ場合も、同じタグを付ける**（grep の結果が効果の全量になる）。定義ルール（[導出] で状態を定義するもの）にはタグ不要 — 横断カテゴリへの包含が定義であることを表す +- 「この概念にどのケイパビリティのどのルールが応えているか」は `grep -n 'xc:user_management/TOS' miko/*/business_rules.md` で都度導出する（宣言 + 全適用ルールが 1 コマンドで列挙される）。オーナーは消費者の一覧を持たない +- **横断カテゴリへの依存は境界セクションに書かない**（タグが唯一の置き場。二重管理を避ける） + +### 非適用は書かない + +「検討したが効果を持たない」判断は、どこにも記録しない。網羅性は記録ではなく**プロセスの門**で保証する。ケイパビリティ × 概念のすべての組は、概念の宣言（propose の影響調査が全ケイパビリティに判定を下す）か、ケイパビリティの新規作成（new-cap の横断カテゴリ判定ステップ）の、どちらか遅い方のイベントで必ず一度検討される。propose の影響調査が「調査したケイパビリティの一覧」を proposal に残すため、痕跡はそこにある。 + +### 書き込み時の検査（lint） + +business_rules.md を更新するスキルは、更新の直後に以下を機械的に検査し、問題があれば修正する（できなければユーザーに報告する）: + +1. **orphan 参照**: `xc:` 参照のうち、対応する横断カテゴリ（`[横断]` + `` 付き見出し）が存在しないもの +2. **マークの整合**: `[横断]` マークと見出し行のマーカーが片方だけになっていないか。同じ ID の横断カテゴリが複数存在しないか +3. **書式**: 横断カテゴリの見出しが「業務用語（プレフィックス）[横断] マーカー」の形式か、lead 文（宣言文）があるか。タグが `[制約]/[導出]` の直後に置かれているか + +--- + ## ドキュメント構造 ``` @@ -340,7 +436,7 @@ high_level_design.md（AI が更新：構造の変化） ## 3. 関連ケイパビリティとの境界 ``` -**既存 BR の扱い:** この構造は新規ケイパビリティ向け。既存の `business_rules.md` は、ユーザーから明示的な移行依頼がない限り、**ファイル構造**（ポリシーセクションの新設、2.1/2.2 への分割、等）と **proposal が触らない既存ルールの本文**には手を入れない（文字数・語彙規律など現在基準への合わせ込みも行わない）。proposal で **改訂・新設するルール** には現在基準を適用する（既存ファイルの構造は踏襲したまま、改訂後の本文・新規ルールの本文だけが新基準に従う）。 +**既存 BR の扱い:** この構造は新規ケイパビリティ向け。既存の `business_rules.md` は、ユーザーから明示的な移行依頼がない限り、**ファイル構造**（ポリシーセクションの新設、2.1/2.2 への分割、等）と **proposal が触らない既存ルールの本文**には手を入れない（文字数・語彙規律など現在基準への合わせ込みも行わない）。proposal で **改訂・新設するルール** には現在基準を適用する（既存ファイルの構造は踏襲したまま、改訂後の本文・新規ルールの本文だけが新基準に従う）。横断カテゴリの仕組みも既存 BR に遡及しない — `[横断]` マークや `[xc:…]` タグは、概念に関わる変更（proposal / new-cap）が入ったときに初めて現れる。 ### 各セクションの指針 @@ -369,7 +465,9 @@ high_level_design.md（AI が更新：構造の変化） **ビジネスルール・カタログ**: `### 2.1 ドメインビジネスルール`（紙の運用でも成り立つもの）と `### 2.2 システムビジネスルール`（システム前提のもの）の 2 セクションに分けて配置する。同一カテゴリ（ORD、PAY 等）はどちらか一方に置く。ドメインとシステムが混じるカテゴリはカテゴリの分割を検討する。詳細は前述の「ドメインビジネスルール / システムビジネスルールの区別」と、後述の「ビジネスルール・カタログの書き方」を参照。 -**境界**: 他のケイパビリティとのビジネス上の責務分担。「借りているもの」「渡しているもの」「境界の注意点」の3軸。このケイパビリティの責務がどこまでかを明確にする。 +**境界**: 他のケイパビリティとのビジネス上の責務分担。「借りているもの」「渡しているもの」「境界の注意点」の3軸。このケイパビリティの責務がどこまでかを明確にする。相手を列挙できる二者間の依存はここで扱う（横断カテゴリにしない）。逆に、**横断カテゴリへの依存は境界には書かない**（ルールの `[xc:…]` タグが唯一の置き場。二重管理を避ける）。 + +横断カテゴリに専用セクションはない — 宣言はカタログ内の横断カテゴリ（`[横断]` マーク）として表現する。詳細は前述の「横断カテゴリとは何か」を参照。 > **注意:** アーキテクチャ上の決定事項（ADR）は business_rules.md には書かない。技術選択の「決定・意図・トレードオフ」は high_level_design.md の「設計上の特徴」セクションに記載する。 @@ -386,6 +484,8 @@ high_level_design.md（AI が更新：構造の変化） ### スレッド管理（THREAD） ``` +カテゴリは既定で private（自由に分割・改名・統合してよいオーナーの整理単位）。横断カテゴリのカテゴリだけは `[横断]` マークで public になり、改名等が契約変更になる（「横断カテゴリとは何か」参照）。 + ### ルールID `{プレフィックス}-{連番}` 形式。削除したルールの番号は欠番にする（詰めない）。harae.md や proposal がルールIDで指摘を参照しているため、番号を振り直すと参照が壊れる。 @@ -450,6 +550,7 @@ high_level_design.md（AI が更新：構造の変化） 6. 各ルール候補に「紙運用」テストを適用し、ドメインビジネスルール（2.1）とシステムビジネスルール（2.2）に振り分ける。1 ルール内に両方が混在している場合は分解する 7. 実装マッピングを `
` 内に記載する 8. コードに暗黙的に埋め込まれているが明文化されていないルール・ポリシーがあれば「暗黙のルール（要確認）」として末尾に列挙する +9. `grep -n 'cross-category' miko/*/business_rules.md` で宣言済みの横断カテゴリを列挙し、コードから概念の効果（制限等）を実装しているルールが見つかった場合は、そのルールに `[xc:…]` タグを付ける（前述「適用の書き方」参照） ### モード B: 提案から生成する場合 * 提案には、ビジネスルールではない詳細な仕様が書かれることがあるが、それはビジネスルールには記載しない。 @@ -460,3 +561,4 @@ high_level_design.md（AI が更新：構造の変化） 4. ルール候補に「紙運用」テストを適用し、ドメインビジネスルール（2.1）とシステムビジネスルール（2.2）に振り分ける 5. 提案に明示されていないが論理的に必要なルール・ポリシーを推論し「暗黙のルール（要確認）」として末尾に列挙する 6. 提案に技術選択が含まれる場合、high_level_design.md の「設計上の特徴」への追記を検討する +7. 提案に含まれる状態・属性に「判定テスト: 横断カテゴリにすべきか」を適用し、満たすものは横断カテゴリの昇格候補としてユーザーに提示する（宣言は proposal を通す） diff --git a/ofuda/guides/harae_guide.md b/ofuda/guides/harae_guide.md index 3f64261..936ca2f 100644 --- a/ofuda/guides/harae_guide.md +++ b/ofuda/guides/harae_guide.md @@ -109,6 +109,8 @@ business_rules.md の「操作の定義」から全操作を、「状態遷移 「関連ケイパビリティとの境界」を確認し、境界で「借りているもの」「渡しているもの」それぞれについて、失敗時や遅延時のルールが定義されているか確認する。 +あわせて横断カテゴリも見る: `grep -n 'cross-category' miko/*/business_rules.md` で宣言済みの横断カテゴリを列挙し、対象ケイパビリティの操作に関係しそうな概念なのに `[xc:…]` タグ付きルールが 1 本もない場合は、対応漏れの可能性として指摘する（関係するかどうかは操作の内容から推論する。網羅の義務チェックではなく攻撃の観点として扱う）。 + > 例: 在庫管理との境界で「在庫引き当てにはタイムアウトがある」「バッチによる自動キャンセルまで引き当てが残り続ける」と記述されている。在庫引き当てがタイムアウトした場合（在庫管理側でタイムアウト解放、注文管理側ではまだ confirmed）、注文側のステータスはどうなるか？ この状態不整合を扱うルールがない。 > 例: 配送管理との境界で「通知遅延により実際の配達完了とステータス更新にタイムラグが生じる」と記述されている。このタイムラグ中にユーザーがキャンセルを試みた場合（shipped 状態だが実際には配達済み）、ORD-02 により返品プロセスへ誘導されるが、実際にはまだ「出荷済み」として扱われている。これは意図通りか？ diff --git a/skills/miko.catchup/SKILL.md b/skills/miko.catchup/SKILL.md index 64e9921..fdd9415 100644 --- a/skills/miko.catchup/SKILL.md +++ b/skills/miko.catchup/SKILL.md @@ -161,6 +161,7 @@ $ARGUMENTS - 承認された削除 - 実装マッピング - 操作の定義（コードから新しい操作が見つかった場合） +- **横断カテゴリの書き込み時検査（lint）** — 更新後、`.miko/guides/business_rules_guide.md` の「書き込み時の検査（lint）」を実行する（orphan `xc:` 参照・`[横断]` マークとマーカーの整合・横断カテゴリとタグの書式）。問題があれば修正し、修正できないものは主さまに報告する **glossary.md の更新:** - proposal で新しい用語が登場した場合は `miko/glossary.md` に追加する（ファイルがなければ作成） diff --git a/skills/miko.miko/SKILL.md b/skills/miko.miko/SKILL.md index e2d7c43..d2133dd 100644 --- a/skills/miko.miko/SKILL.md +++ b/skills/miko.miko/SKILL.md @@ -169,7 +169,13 @@ miko の実装フローでは **constitution**（`.specify/memory/constitution.m 5. **「用語の定義はどこに書く？」** - すべて `miko/glossary.md` に定義する（BR には用語集セクションを持たない） -6. **「constitution に何を書けばいい？」「CLAUDE.md に書くのと何が違う？」** +6. **「複数のケイパビリティに効くルールはどこに書く？」「これって横断カテゴリ？」** + - `business_rules_guide.md` の「判定テスト: 横断カテゴリにすべきか」（他者性・全称性・必達性）を一緒に適用する + - 3 問すべて Yes → オーナーの BR で概念のカテゴリに `[横断]` マークを付ける（`/miko.propose` 経由）。効果は各ケイパビリティのルールに `[xc:…]` タグ付きで書く + - 相手を列挙できる二者間の依存 → 境界セクションで足りる（横断カテゴリにしない） + - 現在の宣言一覧は `grep -n 'cross-category' miko/*/business_rules.md`、特定の概念の全体像（宣言 + 適用ルール）は `grep -n 'xc:{cap}/{プレフィックス}' miko/*/business_rules.md` で提示する + +7. **「constitution に何を書けばいい？」「CLAUDE.md に書くのと何が違う？」** - 実装フローで毎回守ってほしいプロジェクト固有のルール → constitution - 日常の開発作業全般に効かせたい指示 → CLAUDE.md - 具体例: 「API 実装時は Swagger 必須」「スキーマ変更は独立フェーズ」→ constitution 向き diff --git a/skills/miko.new-cap/SKILL.md b/skills/miko.new-cap/SKILL.md index 348d1d0..daac4b7 100644 --- a/skills/miko.new-cap/SKILL.md +++ b/skills/miko.new-cap/SKILL.md @@ -136,15 +136,33 @@ $ARGUMENTS **コードが見つからなかった場合:** - 完全に新規のケイパビリティ。実装マッピングは全て `（未実装）` とする -**6b. 隣接ケイパビリティの BR 読み込み** +**6b. 全ケイパビリティ BR の関連調査（サブエージェント・必須）** -- `miko/*/business_rules.md` を Glob で検出し、確認①の「外部との接点」に挙がったケイパビリティの business_rules.md を読む -- 外部との接点に該当しなくても、ケイパビリティ名やドメイン概念が関連しそうなものは読む -- **確認する観点:** - - 同じ概念に矛盾する定義がないか（用語の不整合） - - 境界の責務分担が既存 BR と整合するか - - 隣接 BR から借りられるルール（重複定義を避ける） -- 隣接 BR との整合性の問題を発見した場合、ステップ 9 の確認②に「隣接 BR との整合性」セクションを追加して報告する +`miko/*/business_rules.md` を Glob で列挙する。既存 BR が 1 つもなければこのステップをスキップする。 + +存在する場合、Sonnet サブエージェント（Agent ツール、model: "sonnet"）を起動し、**全ケイパビリティ**の BR を調査する（対象が多い場合はケイパビリティを分担して並列起動する）。「外部との接点」に挙がったものだけに絞らない — 新規ケイパビリティ作成時は、関連の見落としが最も起きやすい。 + +サブエージェントに渡す情報: +- 確認①の要約（目的・主要な操作・中心データ・外部との接点） +- 担当ケイパビリティの business_rules.md のパス + +サブエージェントに報告させる観点: +- 同じ概念に矛盾する定義がないか（用語の不整合） +- 境界の責務分担が既存 BR と整合するか / 借りられるルール（重複定義を避ける） +- 新ケイパビリティとの間に横断的な依存がないか（あれば境界セクションの候補として報告） + +発見された問題は、ステップ 9 の確認②に「既存 BR との整合性」セクションを追加して報告する。 + +**6c. 横断カテゴリの判定（必須）** + +`grep -n 'cross-category' miko/*/business_rules.md` で宣言済みの横断カテゴリを列挙する。ヒットが 1 件もなければこのステップをスキップする。 + +ヒットした各概念について: +1. 横断カテゴリ（見出しの業務用語・`xc:` ID・lead 文の宣言文）を読む。判定に必要なら、オーナー BR からそのカテゴリの定義ルールだけを読む（BR ファイル全体は読まない） +2. ユーザーに確認する（例: 「ユーザー管理が横断カテゴリ『規約違反ユーザー』を宣言しております。このケイパビリティにはユーザーが発信する操作はございますか？ 制限は必要でしょうか？」） +3. 効果を持つと判定された概念について、効果を表すルールをルール候補に加える（生成時に `[xc:…]` タグを付ける）。効果を持たない概念については何も書かない（この対話で検討したこと自体が保証であり、非適用の記録は持たない） + +ヒアリングやコード調査で、新ケイパビリティ自身が横断カテゴリ（`.miko/guides/business_rules_guide.md` の「判定テスト: 横断カテゴリにすべきか」を満たす状態）を持ちそうな場合は、この場では宣言せず**昇格候補**として記録し、ステップ 12 の完了報告で `/miko.propose` を案内する（宣言は全ケイパビリティに義務を課すため proposal を通す）。 ### 7. ルール策定・構造化 @@ -214,6 +232,10 @@ HLD の骨子（`.miko/examples/high_level_design.md` と同等の構造）を - 実装マッピング: - 既存コードがある場合: `
` 内に記載 - 未実装の場合: `
` 内に `（未実装）` マーク付きで記載 +- **横断カテゴリ**（ガイドの「横断カテゴリとは何か」参照）: + - ステップ 6c で効果を持つと判定した概念のルールに `[xc:…]` タグを付ける + - `[横断]` マーク付きカテゴリは作らない（横断カテゴリの新設は proposal を通すため、new-cap では昇格候補の案内まで） + - 生成後、ガイドの「書き込み時の検査（lint）」を実行する（orphan `xc:` 参照・タグの書式） - 未決事項がある場合、末尾に「未決事項」セクションを追加 ```markdown @@ -250,4 +272,4 @@ HLD の骨子（`.miko/examples/high_level_design.md` と同等の構造）を ### 12. 完了報告 -生成したファイル、ルール総数（制約/導出の内訳、実装済み/未実装）、暗黙のルール数、未決事項数をサマリーテーブルで提示する。次のアクションとして `/miko.new-harae` によるルール検証をお勧めする。 +生成したファイル、ルール総数（制約/導出の内訳、実装済み/未実装）、暗黙のルール数、未決事項数、横断カテゴリの判定結果（検討した概念数と、効果を持つと判定した概念 → 対応ルール）をサマリーテーブルで提示する。次のアクションとして `/miko.new-harae` によるルール検証をお勧めする。ステップ 6c で横断カテゴリの昇格候補を記録した場合は提示し、`/miko.propose` による宣言を案内する。 diff --git a/skills/miko.propose/SKILL.md b/skills/miko.propose/SKILL.md index 152d691..c28833f 100644 --- a/skills/miko.propose/SKILL.md +++ b/skills/miko.propose/SKILL.md @@ -153,19 +153,9 @@ $ARGUMENTS 最終的な proposal と同じ構造（`.miko/examples/proposal.md` 参照）で骨子を提示し、フィードバックを受ける。特にビジネスルールの変更案の妥当性、機能仕様のスコープ、見落としている代替案がないかを確認する。禊の審査結果（審査件数・修正・除外・覆しと理由）も簡潔に報告する。大きな方向転換があればステップ 5 に戻る。 -### 9. 他ケイパビリティへの影響調査（任意） +### 9. 他ケイパビリティへの影響調査（必須） -確認②が承認されたら、以下を確認する: - -``` -⛩️ 他のケイパビリティへの影響を調査いたしましょうか？ -business_rules.md が存在するケイパビリティを対象に、サブエージェントが調査いたします。 -（はい / いいえ） -``` - -**「いいえ」の場合:** このステップをスキップし、ステップ 10 へ進む。 - -**「はい」の場合:** サブエージェント（Agent ツール）を起動して調査を行う。 +確認②が承認されたら、サブエージェント（Agent ツール）を起動して調査を行う。**このステップは省略しない**（主さまが明示的にスキップを指示した場合のみ省略し、その旨を proposal の影響範囲セクションに記録する）。`miko/` 配下に他ケイパビリティの business_rules.md が 1 つも存在しない場合はスキップしてよい。 サブエージェントに渡す情報: - `.claude/skills/miko.propose/guides/cross_capability_impact_guide.md` のパス — 「このファイルを読み、指示に従え」と指示する @@ -175,6 +165,9 @@ business_rules.md が存在するケイパビリティを対象に、サブエ **調査結果の扱い:** - 影響なし: 「他ケイパビリティへの影響はございませんでした」と報告し、ステップ 10 へ進む - 影響あり: 結果をユーザーに提示し、内容を確認・修正してもらう。確認後にステップ 10 でプロポーザルの「他ケイパビリティへの影響」セクションに反映し、**プロポーザルの先頭に `` マーカーを付与する**（このマーカーがないと実装対象プロポーザルとして扱われてしまうため） +- 横断カテゴリの昇格候補が報告された場合: ユーザーに提示し、宣言するか確認する。宣言する場合はビジネスルールの変更に「概念のカテゴリへの `[横断]` マーク付与（定義ルールが既存カテゴリに埋まっている場合はカテゴリの切り出しを含む）」を含め、影響先ケイパビリティの `[xc:…]` タグ付きルールの新設・改訂を「他ケイパビリティへの影響」に反映して `` を付与する + +**横断プロポーザルになる典型:** 変更が横断カテゴリの宣言・定義に触れる場合（新規宣言・宣言文の変更・除去・定義ルールの改訂）は、その概念を `[xc:…]` タグで参照している全ケイパビリティが影響対象になる（詳細は調査ガイドが扱う）。 ### 10. プロポーザル生成 @@ -184,7 +177,7 @@ business_rules.md が存在するケイパビリティを対象に、サブエ **構造:** `.miko/examples/proposal.md` に従う。以下の点に注意: - 該当するセクションのみ含める（空セクションは作らない） -- 「他ケイパビリティへの影響」はステップ 9 で影響ありの場合のみ +- 「他ケイパビリティへの影響」はステップ 9 で影響ありの場合のみ。ステップ 9 を主さまの指示でスキップした場合は、影響範囲セクションに「他ケイパビリティへの影響調査は主さまの指示によりスキップ」と記録する - ステップ 9 で影響ありの場合、プロポーザルの先頭に `` マーカーを付与する - 「祓え検証」セクションは `/miko.harae` が後から追記する。propose では生成しない - 検討・却下した代替案は「これを知らないと将来間違えそう」というものだけ記録する diff --git a/skills/miko.propose/guides/cross_capability_impact_guide.md b/skills/miko.propose/guides/cross_capability_impact_guide.md index 0aa3d3d..09f8a6f 100644 --- a/skills/miko.propose/guides/cross_capability_impact_guide.md +++ b/skills/miko.propose/guides/cross_capability_impact_guide.md @@ -11,12 +11,18 @@ ## 最初に読むファイル 調査を始める前に、以下のファイルを自分で読み込むこと: -- `.miko/guides/business_rules_guide.md` — ルールの判定テスト基準 +- `.miko/guides/business_rules_guide.md` — ルールの判定テスト基準（「横断カテゴリとは何か」を含む） - `miko/<メインケイパビリティ>/business_rules.md` — メインケイパビリティの現行ルール - `miko/<メインケイパビリティ>/high_level_design.md` — メインケイパビリティの構造（あれば） - `miko/system_high_level_design.md` — システム全体のアーキテクチャ（あれば） - `miko/glossary.md` — 用語集。ケイパビリティ間で共有される概念の定義を確認する（あれば） +さらに、宣言済みの横断カテゴリを列挙しておく: + +```bash +grep -n 'cross-category' miko/*/business_rules.md +``` + ## 目的 今回の変更案が、メインケイパビリティ以外のケイパビリティのビジネスルールに波及的な変更を必要とするかを調査する。 @@ -64,6 +70,11 @@ business_rules.md が存在しないケイパビリティは管理対象外で **廃止が必要なケース:** - 変更案でメインケイパビリティの責務が変わり、このケイパビリティのルールが不要になる +**横断カテゴリに関わるケース:** +- 変更案が宣言済み横断カテゴリの宣言文・定義ルールを変える → その概念の ID（`xc:…`）を grep し、タグで参照している全ルールが影響対象。各ルールの改訂要否を判定する +- 変更案が新しい横断カテゴリの宣言を含む → 全ケイパビリティについて、概念の効果を持つ操作があるかを判定する。効果を持つケイパビリティには `[xc:…]` タグ付きルールの新設を提案する。効果を持たないケイパビリティは報告しない（調査済み一覧に含まれることが検討の痕跡になる） +- 変更案に含まれる状態・属性が「判定テスト: 横断カテゴリにすべきか」（business_rules_guide.md）を満たす → 変更案自体は宣言していなくても **昇格候補** として報告する + ### 3. 影響なしの判定基準 以下の場合は「影響なし」と判定し、報告しない: @@ -103,6 +114,19 @@ business_rules.md が存在しないケイパビリティは管理対象外で ``` +横断カテゴリに関わる新設・改訂ルールには、本文の先頭タグに横断カテゴリの ID を含めて提案する（例: `[制約][xc:user_management/TOS]`）。 + +### 横断カテゴリの昇格候補（該当する場合） + +変更案に含まれる状態・属性が横断カテゴリの判定テストを満たす場合、影響一覧とは別に報告する: + +``` +### 横断カテゴリの昇格候補 + +- **{概念名}** — {宣言文の案（各ケイパビリティが何を表明すべきかの軸を含む）} + - 判定根拠: 他者性 / 全称性 / 必達性 それぞれの理由 +``` + **ルール ID の採番:** - 改訂・廃止: 既存のルール ID をそのまま使う - 新設: 対象ケイパビリティの既存カテゴリの末尾コメント `` を確認し、続きの番号を採番する。適切なカテゴリがなければ新カテゴリを提案する diff --git a/skills/miko.quick-catchup/SKILL.md b/skills/miko.quick-catchup/SKILL.md index f33247e..681ccf3 100644 --- a/skills/miko.quick-catchup/SKILL.md +++ b/skills/miko.quick-catchup/SKILL.md @@ -115,6 +115,7 @@ diff ソース、変更の要約、ビジネスルールへの影響（新設/ **ステップ 6 で生成した proposal の内容を business_rules.md に反映する。** - proposal の新設・改訂を適用する - 実装マッピングを更新する +- **横断カテゴリの書き込み時検査（lint）** — 更新後、`.miko/guides/business_rules_guide.md` の「書き込み時の検査（lint）」を実行する（orphan `xc:` 参照・`[横断]` マークとマーカーの整合・横断カテゴリとタグの書式）。問題があれば修正し、修正できないものはステップ 8 末尾の確認で主さまに報告する - 新しい用語があれば `miko/glossary.md` に追加する（`.miko/examples/glossary.md` のフォーマットに従う。実装の詳細は書かず、1〜2文の定義だけを書く） - ケイパビリティの節は配置の軸であり、意味のスコープではない。見出し語はシステム全体で一意にする。既存の見出し語と衝突する場合は、同じ意味なら1項目に統合し、別概念なら一意な別名を立てる（注文確定 / 決済確定） diff --git a/skills/miko.quick-impl/SKILL.md b/skills/miko.quick-impl/SKILL.md index 2738f83..6b80ab5 100644 --- a/skills/miko.quick-impl/SKILL.md +++ b/skills/miko.quick-impl/SKILL.md @@ -144,6 +144,10 @@ miko の原則として BR ルール本文の変更には proposal が必要。p - proposal がある場合のみ: proposal の新設・改訂・廃止を BR 本文に適用する - proposal がない場合: BR 本文は一切触らない（スコープガード (d) で除外済みのはず） +#### 横断カテゴリの書き込み時検査（lint） + +business_rules.md を更新した場合、`.miko/guides/business_rules_guide.md` の「書き込み時の検査（lint）」を実行する（orphan `xc:` 参照・`[横断]` マークとマーカーの整合・横断カテゴリとタグの書式）。問題があれば修正し、修正できないものは主さまに報告する。BR を更新しない実行ではスキップする。 + #### 実装マッピングの横断更新（Sonnet サブエージェント） 実装の変更がどの cap の実装マッピングに波及したかを機械的にチェック・更新する。 diff --git a/skills/miko.speckit.implement/SKILL.md b/skills/miko.speckit.implement/SKILL.md index 439641c..9848ee5 100644 --- a/skills/miko.speckit.implement/SKILL.md +++ b/skills/miko.speckit.implement/SKILL.md @@ -143,6 +143,7 @@ tasks.md の最終フェーズに到達したら、以下の順序で実行す - 今回の実装で作成・変更したファイルを元に、該当ルールの実装マッピング（`
` 内）を更新する - 既存ルールでも実装場所が変わったものがあれば更新する - **spec.md の Miko コンテキストに複数ケイパビリティのサブプロポーザルが含まれている場合:** 各サブプロポーザルの BR 変更セクションに従って、各ケイパビリティの `miko//business_rules.md` をそれぞれ更新する +- **横断カテゴリの書き込み時検査（lint）:** 更新した各 business_rules.md に対して、`.miko/guides/business_rules_guide.md` の「書き込み時の検査（lint）」を実行する（orphan `xc:` 参照・`[横断]` マークとマーカーの整合・横断カテゴリとタグの書式）。問題があれば修正し、修正できないものはステップ 6 の確認で主さまに報告する **3. high_level_design.md の更新** - 今回の実装で構造に変更があった場合、`miko//high_level_design.md` を更新する