From b87a01d6e02a673617da3389a318237f60fe34a1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 23 Jul 2026 01:14:47 +0000 Subject: [PATCH 1/2] =?UTF-8?q?glossary:=20=E5=AE=9F=E8=A3=85=E3=81=AE?= =?UTF-8?q?=E8=A9=B3=E7=B4=B0=E3=82=92=E6=9B=B8=E3=81=8B=E3=81=AA=E3=81=84?= =?UTF-8?q?=E7=94=9F=E6=88=90=E6=8C=87=E7=A4=BA=E6=9B=B8=E3=82=92=E8=BF=BD?= =?UTF-8?q?=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 用語集の項目に実装の詳細（クラス名・メソッド名・API・処理手順）が書かれてしまい、実装変更のたびに glossary への追従が必要になる問題に対処。glossary_guide.md を新設し、判定テスト・書くもの/書かないもの・長さの目安を明文化。setup / new-cap / catchup / quick-catchup / propose の glossary.md 更新手順から参照するようにした。 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_012ZqeVeR6bCYCJ8Ze1BxVkb --- CHANGELOG.md | 6 +++ CLAUDE.md | 1 + business_rules_driven_development.md | 3 ++ ofuda/VERSION | 4 +- ofuda/examples/glossary.md | 1 + ofuda/guides/glossary_guide.md | 61 ++++++++++++++++++++++++++++ skills/miko.catchup/SKILL.md | 2 + skills/miko.new-cap/SKILL.md | 2 + skills/miko.propose/SKILL.md | 2 + skills/miko.quick-catchup/SKILL.md | 3 +- skills/miko.setup/SKILL.md | 1 + 11 files changed, 83 insertions(+), 3 deletions(-) create mode 100644 ofuda/guides/glossary_guide.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c04eadf..a461c08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## v1.5.0 (2026-07-23) + +### New + +- **glossary.md の生成指示書（`glossary_guide.md`）を追加** — 用語集の項目が実装の詳細（クラス名・メソッド名・API・処理手順）まで書かれてしまい、実装変更のたびに追従が必要になる問題に対処。「実装技術を置き換えても定義文は変わらないか」という判定テストと、書くもの/書かないものの対比表、1〜2文に収める長さの目安を明文化。`.miko/examples/glossary.md` にも簡潔な定義のみを書く旨を明記し、`/miko.setup`・`/miko.new-cap`・`/miko.catchup`・`/miko.quick-catchup`・`/miko.propose` の glossary.md 更新手順から参照するようにした + ## v1.4.0 (2026-07-17) ### New diff --git a/CLAUDE.md b/CLAUDE.md index 626ef6d..4139807 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,7 @@ - `README.md` - `business_rules_driven_development.md` - `ofuda/guides/business_rules_guide.md` +- `ofuda/guides/glossary_guide.md` - `ofuda/guides/tone_guide.md` - `ofuda/examples/` 配下のファイル - 各スキルの `skills/miko.*/SKILL.md` diff --git a/business_rules_driven_development.md b/business_rules_driven_development.md index 51110d3..fa269cc 100644 --- a/business_rules_driven_development.md +++ b/business_rules_driven_development.md @@ -62,6 +62,7 @@ speckit は SDD のためではなく、**Claude に丁寧にコードベース | `miko/system_high_level_design.md` | システム全体のアーキテクチャ（テナント構造、API 構造、コード探索ガイド等） | | `miko/glossary.md` | 用語の定義。ケイパビリティごとのセクションに分けて管理する | | `ofuda/guides/business_rules_guide.md` | business_rules.md の生成指示書（AI 向け） | +| `ofuda/guides/glossary_guide.md` | glossary.md の生成指示書（AI 向け）。実装の詳細を書かず辞書として簡潔に書く原則 | | `ofuda/guides/business_rules_driven_development.md` | この文書。開発手法の設計メモ | ### 使い捨ての成果物 @@ -421,4 +422,6 @@ miko//proposals/ - `ofuda/examples/business_rules.md` — business_rules.md のサンプル - `ofuda/examples/high_level_design.md` — high_level_design.md のサンプル +- `ofuda/examples/glossary.md` — glossary.md のサンプル - `.miko/guides/business_rules_guide.md` — business_rules.md の生成指示書 +- `.miko/guides/glossary_guide.md` — glossary.md の生成指示書 diff --git a/ofuda/VERSION b/ofuda/VERSION index 27e66e8..076d636 100644 --- a/ofuda/VERSION +++ b/ofuda/VERSION @@ -1,2 +1,2 @@ -1.4.0 -202607210610 +1.5.0 +202607230114 diff --git a/ofuda/examples/glossary.md b/ofuda/examples/glossary.md index 4d7da7c..1a95df8 100644 --- a/ofuda/examples/glossary.md +++ b/ofuda/examples/glossary.md @@ -2,6 +2,7 @@ > このファイルは miko スキルの品質基準を示すサンプルです。 > 実際のプロジェクトの用語集ではありません。 +> 各項目は 1〜2文の定義のみで、実装の詳細（クラス名・メソッド名・API・処理手順）を含まない。書き方のルールは `guides/glossary_guide.md` を参照。 ## 全体 diff --git a/ofuda/guides/glossary_guide.md b/ofuda/guides/glossary_guide.md new file mode 100644 index 0000000..ffedce7 --- /dev/null +++ b/ofuda/guides/glossary_guide.md @@ -0,0 +1,61 @@ +# glossary.md 生成指示書 + +## このドキュメントの目的 + +`miko/glossary.md` の項目を生成・追記するための指示書。既存コードからの逆引き、proposal からの新規追加のいずれにも適用する。 + +--- + +## glossary.md とは何か + +**glossary.md は辞書である。** 「この語はプロジェクト内でどういう意味を持つか」を一言で示すものであり、「どう実装されているか」を説明する場所ではない。 + +実装の詳細まで書くと、実装が変わるたびに glossary も直さなければならなくなる。修正は面倒なうえ、AI が対応を忘れる可能性もある。**実装が変わっても glossary の記述は変わらない** ことを常に確認する。 + +### 迷ったときの判定 + +**実装技術を別のものに置き換えても、この定義文は変わらないか？** + +- Yes → 定義として書いてよい +- No（クラス名・メソッド名・API・処理手順を言い換えただけで意味が保てない）→ 実装の詳細であり、glossary には書かない + +この判定は `business_rules_guide.md` の「ルール本文の語彙規律」と同じ物差しである。 + +--- + +## 書くもの / 書かないもの + +| 書くもの | 書かないもの | +|---|---| +| その語がビジネス上何を意味するか | どのクラス・メソッド・テーブルで実現しているか | +| 一般語と紛らわしい場合の、プロジェクト固有の意味の違い | API のエンドポイント名・パラメータ名 | +| マスター値・enum 値とビジネス用語の対訳 | 判定条件の処理手順・アルゴリズム | +| ケイパビリティごとに意味が異なる場合の、その違い | 画面上の表示場所・レイアウトなどの UI 仕様 | +| 状態の名称とその意味（例:「確定」とは何を指すか） | 状態がどう遷移するか・遷移の実装（該当ケイパビリティの business_rules.md / high_level_design.md に書く） | + +**書かないもの**は「実装方法」「実装トレース」に当たるかどうかで機械的に判定する。`business_rules_guide.md` の「書かないもの」と判断軸は同じ。 + +--- + +## 長さの目安 + +1項目は 1〜2文。それを超えて長くなる場合、「なぜそうなっているか」「条件の詳細」「手順」が紛れ込んでいる可能性が高い。条件・閾値・経緯は business_rules.md や proposal に譲り、glossary には結論の一言だけを書く。 + +### 書き換え例 + +| 悪い例（実装を説明している） | 良い例（意味だけを説明している） | +|---|---| +| 確定（confirm）— `OrderConfirmService#call` が注文の `status` を `confirmed` に更新し、`Payment::ChargeJob` をキューに積む処理のこと | 確定（confirm）— 注文内容が変更不可になること。決済処理の開始条件 | +| キャンセル猶予期間 — `cancellable?` メソッドが `confirmed_at` から `GRACE_PERIOD_HOURS`（24時間）以内かどうかで判定する期間 | キャンセル猶予期間 — 注文確定後、一定時間内であればキャンセルを受け付ける期間 | +| 削除済みユーザー — `deleted_at` が非 null のユーザーで、`SoftDelete` concern により論理削除される | 削除済みユーザー — 退会処理が完了したユーザー。データは監査目的で保持されるが、ログインや操作はできない | + +--- + +## フォーマット + +`.miko/examples/glossary.md` のフォーマットに従う。 + +- ケイパビリティごとに `## ケイパビリティ名` セクションを分ける +- 複数ケイパビリティで共通の用語は `## 全体` セクションに置く +- 同じ用語がケイパビリティごとに異なる意味を持つ場合、曖昧にせず、それぞれのセクションに定義を併記する +- 名前から意味が想像しやすい一般的な技術用語は書かない。このプロジェクト固有の意味を持つもの、名前から想像しにくいものだけを書く diff --git a/skills/miko.catchup/SKILL.md b/skills/miko.catchup/SKILL.md index a11ef73..baa91ba 100644 --- a/skills/miko.catchup/SKILL.md +++ b/skills/miko.catchup/SKILL.md @@ -43,6 +43,7 @@ $ARGUMENTS **指示書（必須）:** - `.miko/guides/business_rules_guide.md` — business_rules.md の生成ルール。**このファイルの指示に厳密に従うこと** +- `.miko/guides/glossary_guide.md` — glossary.md の生成ルール。実装の詳細を書かない原則 - `.miko/guides/tone_guide.md` — ユーザーとの対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと** **システム全体の文脈:** @@ -164,6 +165,7 @@ $ARGUMENTS **glossary.md の更新:** - proposal で新しい用語が登場した場合は `miko/glossary.md` に追加する（ファイルがなければ作成） +- `.miko/guides/glossary_guide.md` に従う。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く - `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する ### 12. high_level_design.md 更新 diff --git a/skills/miko.new-cap/SKILL.md b/skills/miko.new-cap/SKILL.md index 4e7888e..95c7a5e 100644 --- a/skills/miko.new-cap/SKILL.md +++ b/skills/miko.new-cap/SKILL.md @@ -58,6 +58,7 @@ $ARGUMENTS **指示書（必須）:** - `.miko/guides/business_rules_guide.md` — business_rules.md の生成ルール。判定テストの方法 +- `.miko/guides/glossary_guide.md` — glossary.md の生成ルール。実装の詳細を書かない原則 - `.miko/guides/tone_guide.md` — ユーザーとの対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと** **システム全体の文脈:** @@ -239,6 +240,7 @@ HLD の骨子（`.miko/examples/high_level_design.md` と同等の構造）を **glossary.md の更新:** - 新しい用語が出てきた場合は `miko/glossary.md` に追加する（ファイルがなければ作成） +- `.miko/guides/glossary_guide.md` に従う。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く - `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する - 複数ケイパビリティで共通の用語は `## 全体` セクションに置く diff --git a/skills/miko.propose/SKILL.md b/skills/miko.propose/SKILL.md index 0ddc6f1..dce0842 100644 --- a/skills/miko.propose/SKILL.md +++ b/skills/miko.propose/SKILL.md @@ -42,6 +42,7 @@ $ARGUMENTS **指示書（必須）:** - `.miko/guides/business_rules_guide.md` — ルール記述の原則。判定テストの方法 +- `.miko/guides/glossary_guide.md` — glossary.md の生成ルール。実装の詳細を書かない原則 - `.miko/guides/tone_guide.md` — ユーザーとの対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと** **実例（品質の基準）:** @@ -197,6 +198,7 @@ business_rules.md が存在するケイパビリティを対象に、サブエ **glossary.md の更新:** - proposal で新しい用語が登場した場合は `miko/glossary.md` に追加する（ファイルがなければ作成） +- `.miko/guides/glossary_guide.md` に従う。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く - `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する ### 11. 完了報告 diff --git a/skills/miko.quick-catchup/SKILL.md b/skills/miko.quick-catchup/SKILL.md index afeea7a..b77e76f 100644 --- a/skills/miko.quick-catchup/SKILL.md +++ b/skills/miko.quick-catchup/SKILL.md @@ -53,6 +53,7 @@ miko フローを通さずに入ったコード変更（緊急 FIX 等）を、 **読み込むファイル:** - `.miko/guides/business_rules_guide.md` — ルールの書き方、判定テスト +- `.miko/guides/glossary_guide.md` — glossary.md の生成ルール。実装の詳細を書かない原則 - `.miko/guides/tone_guide.md` — 対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと** - `miko/system_high_level_design.md` — コード探索ガイド（着目点の参照） - `miko//business_rules.md` — 現在のビジネスルール。**存在しない場合はエラー:** @@ -115,7 +116,7 @@ diff ソース、変更の要約、ビジネスルールへの影響（新設/ **ステップ 6 で生成した proposal の内容を business_rules.md に反映する。** - proposal の新設・改訂を適用する - 実装マッピングを更新する -- 新しい用語があれば `miko/glossary.md` に追加する（`.miko/examples/glossary.md` のフォーマットに従う） +- 新しい用語があれば `miko/glossary.md` に追加する（`.miko/guides/glossary_guide.md` に従う。実装の詳細は書かず、`.miko/examples/glossary.md` のフォーマットで 1〜2文の定義だけを書く） ### 8. high_level_design.md 更新 diff --git a/skills/miko.setup/SKILL.md b/skills/miko.setup/SKILL.md index 073115d..26654f4 100644 --- a/skills/miko.setup/SKILL.md +++ b/skills/miko.setup/SKILL.md @@ -123,6 +123,7 @@ miko を新しいプロジェクトに導入するための初期セットアッ 用語集ファイルを生成する。コード調査で発見したドメイン用語を記載する。 +- `.miko/guides/glossary_guide.md` — 書き方の指示書。**必ず読んで従うこと**。実装の詳細（クラス名・メソッド名・API・処理手順）を書かない、辞書として簡潔に書く、という原則がある - `.miko/examples/glossary.md` のフォーマットに従う - 名前から想像しにくいもの、このプロジェクト固有の意味を持つものだけ - 一般的な技術用語は書かない From 77df65b0b48f73a08f2c94a1088172d40d64bfd2 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 23 Jul 2026 10:06:28 +0000 Subject: [PATCH 2/2] =?UTF-8?q?glossary:=20=E7=8B=AC=E7=AB=8B=E3=82=AC?= =?UTF-8?q?=E3=82=A4=E3=83=89=E3=82=92=E3=82=84=E3=82=81=E3=80=81example?= =?UTF-8?q?=20=E3=81=A8=E3=82=B9=E3=82=AD=E3=83=AB=E6=8C=87=E7=A4=BA?= =?UTF-8?q?=E3=81=AB=E7=9B=B4=E6=8E=A5=E3=83=AB=E3=83=BC=E3=83=AB=E3=82=92?= =?UTF-8?q?=E5=9F=8B=E3=82=81=E8=BE=BC=E3=82=80=E8=BB=BD=E9=87=8F=E7=89=88?= =?UTF-8?q?=E3=81=AB=E5=A4=89=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit glossary_guide.md は判断がシンプル（実装技術を置き換えても定義文は変わらないか、の一問）なので独立ファイルにするほどではないと判断。判定テストと悪い例/良い例を .miko/examples/glossary.md に直接書き、各スキルの glossary.md 更新手順には一文だけ追記した。 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_012ZqeVeR6bCYCJ8Ze1BxVkb --- CHANGELOG.md | 6 +-- CLAUDE.md | 1 - business_rules_driven_development.md | 3 -- ofuda/VERSION | 2 +- ofuda/examples/glossary.md | 6 ++- ofuda/guides/glossary_guide.md | 61 ---------------------------- skills/miko.catchup/SKILL.md | 4 +- skills/miko.new-cap/SKILL.md | 4 +- skills/miko.propose/SKILL.md | 4 +- skills/miko.quick-catchup/SKILL.md | 3 +- skills/miko.setup/SKILL.md | 3 +- 11 files changed, 14 insertions(+), 83 deletions(-) delete mode 100644 ofuda/guides/glossary_guide.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a461c08..c783aa9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,10 @@ # Changelog -## v1.5.0 (2026-07-23) +## v1.4.1 (2026-07-23) -### New +### Fixed -- **glossary.md の生成指示書（`glossary_guide.md`）を追加** — 用語集の項目が実装の詳細（クラス名・メソッド名・API・処理手順）まで書かれてしまい、実装変更のたびに追従が必要になる問題に対処。「実装技術を置き換えても定義文は変わらないか」という判定テストと、書くもの/書かないものの対比表、1〜2文に収める長さの目安を明文化。`.miko/examples/glossary.md` にも簡潔な定義のみを書く旨を明記し、`/miko.setup`・`/miko.new-cap`・`/miko.catchup`・`/miko.quick-catchup`・`/miko.propose` の glossary.md 更新手順から参照するようにした +- **glossary.md に実装の詳細が書かれてしまう問題を修正** — 用語集の項目にクラス名・メソッド名・API・処理手順まで書かれ、実装変更のたびに追従が必要になっていた。`.miko/examples/glossary.md` に「実装技術を置き換えても定義文は変わらないか」という判定テストと悪い例/良い例を追記し、`/miko.setup`・`/miko.new-cap`・`/miko.catchup`・`/miko.quick-catchup`・`/miko.propose` の glossary.md 更新手順にも「実装の詳細は書かず1〜2文の定義だけを書く」旨を明記 ## v1.4.0 (2026-07-17) diff --git a/CLAUDE.md b/CLAUDE.md index 4139807..626ef6d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,7 +7,6 @@ - `README.md` - `business_rules_driven_development.md` - `ofuda/guides/business_rules_guide.md` -- `ofuda/guides/glossary_guide.md` - `ofuda/guides/tone_guide.md` - `ofuda/examples/` 配下のファイル - 各スキルの `skills/miko.*/SKILL.md` diff --git a/business_rules_driven_development.md b/business_rules_driven_development.md index fa269cc..51110d3 100644 --- a/business_rules_driven_development.md +++ b/business_rules_driven_development.md @@ -62,7 +62,6 @@ speckit は SDD のためではなく、**Claude に丁寧にコードベース | `miko/system_high_level_design.md` | システム全体のアーキテクチャ（テナント構造、API 構造、コード探索ガイド等） | | `miko/glossary.md` | 用語の定義。ケイパビリティごとのセクションに分けて管理する | | `ofuda/guides/business_rules_guide.md` | business_rules.md の生成指示書（AI 向け） | -| `ofuda/guides/glossary_guide.md` | glossary.md の生成指示書（AI 向け）。実装の詳細を書かず辞書として簡潔に書く原則 | | `ofuda/guides/business_rules_driven_development.md` | この文書。開発手法の設計メモ | ### 使い捨ての成果物 @@ -422,6 +421,4 @@ miko//proposals/ - `ofuda/examples/business_rules.md` — business_rules.md のサンプル - `ofuda/examples/high_level_design.md` — high_level_design.md のサンプル -- `ofuda/examples/glossary.md` — glossary.md のサンプル - `.miko/guides/business_rules_guide.md` — business_rules.md の生成指示書 -- `.miko/guides/glossary_guide.md` — glossary.md の生成指示書 diff --git a/ofuda/VERSION b/ofuda/VERSION index 076d636..ff4ba9e 100644 --- a/ofuda/VERSION +++ b/ofuda/VERSION @@ -1,2 +1,2 @@ -1.5.0 +1.4.1 202607230114 diff --git a/ofuda/examples/glossary.md b/ofuda/examples/glossary.md index 1a95df8..07d3e36 100644 --- a/ofuda/examples/glossary.md +++ b/ofuda/examples/glossary.md @@ -2,7 +2,11 @@ > このファイルは miko スキルの品質基準を示すサンプルです。 > 実際のプロジェクトの用語集ではありません。 -> 各項目は 1〜2文の定義のみで、実装の詳細（クラス名・メソッド名・API・処理手順）を含まない。書き方のルールは `guides/glossary_guide.md` を参照。 +> +> 各項目は 1〜2文で「意味」だけを書く。判定: 実装技術を置き換えてもこの定義文は変わらないか？ 変わるなら実装の詳細（クラス名・メソッド名・API・処理手順）であり、glossary には書かない。 +> +> 悪い例: 確定（confirm）— `OrderConfirmService#call` が注文の `status` を `confirmed` に更新する処理のこと +> 良い例: 確定（confirm）— 注文内容が変更不可になること。決済処理の開始条件 ## 全体 diff --git a/ofuda/guides/glossary_guide.md b/ofuda/guides/glossary_guide.md deleted file mode 100644 index ffedce7..0000000 --- a/ofuda/guides/glossary_guide.md +++ /dev/null @@ -1,61 +0,0 @@ -# glossary.md 生成指示書 - -## このドキュメントの目的 - -`miko/glossary.md` の項目を生成・追記するための指示書。既存コードからの逆引き、proposal からの新規追加のいずれにも適用する。 - ---- - -## glossary.md とは何か - -**glossary.md は辞書である。** 「この語はプロジェクト内でどういう意味を持つか」を一言で示すものであり、「どう実装されているか」を説明する場所ではない。 - -実装の詳細まで書くと、実装が変わるたびに glossary も直さなければならなくなる。修正は面倒なうえ、AI が対応を忘れる可能性もある。**実装が変わっても glossary の記述は変わらない** ことを常に確認する。 - -### 迷ったときの判定 - -**実装技術を別のものに置き換えても、この定義文は変わらないか？** - -- Yes → 定義として書いてよい -- No（クラス名・メソッド名・API・処理手順を言い換えただけで意味が保てない）→ 実装の詳細であり、glossary には書かない - -この判定は `business_rules_guide.md` の「ルール本文の語彙規律」と同じ物差しである。 - ---- - -## 書くもの / 書かないもの - -| 書くもの | 書かないもの | -|---|---| -| その語がビジネス上何を意味するか | どのクラス・メソッド・テーブルで実現しているか | -| 一般語と紛らわしい場合の、プロジェクト固有の意味の違い | API のエンドポイント名・パラメータ名 | -| マスター値・enum 値とビジネス用語の対訳 | 判定条件の処理手順・アルゴリズム | -| ケイパビリティごとに意味が異なる場合の、その違い | 画面上の表示場所・レイアウトなどの UI 仕様 | -| 状態の名称とその意味（例:「確定」とは何を指すか） | 状態がどう遷移するか・遷移の実装（該当ケイパビリティの business_rules.md / high_level_design.md に書く） | - -**書かないもの**は「実装方法」「実装トレース」に当たるかどうかで機械的に判定する。`business_rules_guide.md` の「書かないもの」と判断軸は同じ。 - ---- - -## 長さの目安 - -1項目は 1〜2文。それを超えて長くなる場合、「なぜそうなっているか」「条件の詳細」「手順」が紛れ込んでいる可能性が高い。条件・閾値・経緯は business_rules.md や proposal に譲り、glossary には結論の一言だけを書く。 - -### 書き換え例 - -| 悪い例（実装を説明している） | 良い例（意味だけを説明している） | -|---|---| -| 確定（confirm）— `OrderConfirmService#call` が注文の `status` を `confirmed` に更新し、`Payment::ChargeJob` をキューに積む処理のこと | 確定（confirm）— 注文内容が変更不可になること。決済処理の開始条件 | -| キャンセル猶予期間 — `cancellable?` メソッドが `confirmed_at` から `GRACE_PERIOD_HOURS`（24時間）以内かどうかで判定する期間 | キャンセル猶予期間 — 注文確定後、一定時間内であればキャンセルを受け付ける期間 | -| 削除済みユーザー — `deleted_at` が非 null のユーザーで、`SoftDelete` concern により論理削除される | 削除済みユーザー — 退会処理が完了したユーザー。データは監査目的で保持されるが、ログインや操作はできない | - ---- - -## フォーマット - -`.miko/examples/glossary.md` のフォーマットに従う。 - -- ケイパビリティごとに `## ケイパビリティ名` セクションを分ける -- 複数ケイパビリティで共通の用語は `## 全体` セクションに置く -- 同じ用語がケイパビリティごとに異なる意味を持つ場合、曖昧にせず、それぞれのセクションに定義を併記する -- 名前から意味が想像しやすい一般的な技術用語は書かない。このプロジェクト固有の意味を持つもの、名前から想像しにくいものだけを書く diff --git a/skills/miko.catchup/SKILL.md b/skills/miko.catchup/SKILL.md index baa91ba..c9a8223 100644 --- a/skills/miko.catchup/SKILL.md +++ b/skills/miko.catchup/SKILL.md @@ -43,7 +43,6 @@ $ARGUMENTS **指示書（必須）:** - `.miko/guides/business_rules_guide.md` — business_rules.md の生成ルール。**このファイルの指示に厳密に従うこと** -- `.miko/guides/glossary_guide.md` — glossary.md の生成ルール。実装の詳細を書かない原則 - `.miko/guides/tone_guide.md` — ユーザーとの対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと** **システム全体の文脈:** @@ -165,8 +164,7 @@ $ARGUMENTS **glossary.md の更新:** - proposal で新しい用語が登場した場合は `miko/glossary.md` に追加する（ファイルがなければ作成） -- `.miko/guides/glossary_guide.md` に従う。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く -- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する +- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く ### 12. high_level_design.md 更新 diff --git a/skills/miko.new-cap/SKILL.md b/skills/miko.new-cap/SKILL.md index 95c7a5e..99029b8 100644 --- a/skills/miko.new-cap/SKILL.md +++ b/skills/miko.new-cap/SKILL.md @@ -58,7 +58,6 @@ $ARGUMENTS **指示書（必須）:** - `.miko/guides/business_rules_guide.md` — business_rules.md の生成ルール。判定テストの方法 -- `.miko/guides/glossary_guide.md` — glossary.md の生成ルール。実装の詳細を書かない原則 - `.miko/guides/tone_guide.md` — ユーザーとの対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと** **システム全体の文脈:** @@ -240,8 +239,7 @@ HLD の骨子（`.miko/examples/high_level_design.md` と同等の構造）を **glossary.md の更新:** - 新しい用語が出てきた場合は `miko/glossary.md` に追加する（ファイルがなければ作成） -- `.miko/guides/glossary_guide.md` に従う。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く -- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する +- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く - 複数ケイパビリティで共通の用語は `## 全体` セクションに置く **生成時の注意:** diff --git a/skills/miko.propose/SKILL.md b/skills/miko.propose/SKILL.md index dce0842..8ec6335 100644 --- a/skills/miko.propose/SKILL.md +++ b/skills/miko.propose/SKILL.md @@ -42,7 +42,6 @@ $ARGUMENTS **指示書（必須）:** - `.miko/guides/business_rules_guide.md` — ルール記述の原則。判定テストの方法 -- `.miko/guides/glossary_guide.md` — glossary.md の生成ルール。実装の詳細を書かない原則 - `.miko/guides/tone_guide.md` — ユーザーとの対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと** **実例（品質の基準）:** @@ -198,8 +197,7 @@ business_rules.md が存在するケイパビリティを対象に、サブエ **glossary.md の更新:** - proposal で新しい用語が登場した場合は `miko/glossary.md` に追加する（ファイルがなければ作成） -- `.miko/guides/glossary_guide.md` に従う。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く -- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する +- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く ### 11. 完了報告 diff --git a/skills/miko.quick-catchup/SKILL.md b/skills/miko.quick-catchup/SKILL.md index b77e76f..4a21f67 100644 --- a/skills/miko.quick-catchup/SKILL.md +++ b/skills/miko.quick-catchup/SKILL.md @@ -53,7 +53,6 @@ miko フローを通さずに入ったコード変更（緊急 FIX 等）を、 **読み込むファイル:** - `.miko/guides/business_rules_guide.md` — ルールの書き方、判定テスト -- `.miko/guides/glossary_guide.md` — glossary.md の生成ルール。実装の詳細を書かない原則 - `.miko/guides/tone_guide.md` — 対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと** - `miko/system_high_level_design.md` — コード探索ガイド（着目点の参照） - `miko//business_rules.md` — 現在のビジネスルール。**存在しない場合はエラー:** @@ -116,7 +115,7 @@ diff ソース、変更の要約、ビジネスルールへの影響（新設/ **ステップ 6 で生成した proposal の内容を business_rules.md に反映する。** - proposal の新設・改訂を適用する - 実装マッピングを更新する -- 新しい用語があれば `miko/glossary.md` に追加する（`.miko/guides/glossary_guide.md` に従う。実装の詳細は書かず、`.miko/examples/glossary.md` のフォーマットで 1〜2文の定義だけを書く） +- 新しい用語があれば `miko/glossary.md` に追加する（`.miko/examples/glossary.md` のフォーマットに従う。実装の詳細は書かず、1〜2文の定義だけを書く） ### 8. high_level_design.md 更新 diff --git a/skills/miko.setup/SKILL.md b/skills/miko.setup/SKILL.md index 26654f4..45813dc 100644 --- a/skills/miko.setup/SKILL.md +++ b/skills/miko.setup/SKILL.md @@ -123,8 +123,7 @@ miko を新しいプロジェクトに導入するための初期セットアッ 用語集ファイルを生成する。コード調査で発見したドメイン用語を記載する。 -- `.miko/guides/glossary_guide.md` — 書き方の指示書。**必ず読んで従うこと**。実装の詳細（クラス名・メソッド名・API・処理手順）を書かない、辞書として簡潔に書く、という原則がある -- `.miko/examples/glossary.md` のフォーマットに従う +- `.miko/examples/glossary.md` のフォーマットに従う。実装の詳細（クラス名・メソッド名・API・処理手順）は書かない。辞書として1〜2文で意味だけを書く - 名前から想像しにくいもの、このプロジェクト固有の意味を持つものだけ - 一般的な技術用語は書かない - 同じ用語がケイパビリティごとに異なる意味を持つ場合は、それぞれのケイパビリティセクションに定義を書く