Add glossary_guide.md to standardize glossary.md generation

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v1.4.1 (2026-07-23)
+
+### Fixed
+
+- **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)
 
 ### New

ofuda/VERSION

@@ -1,2 +1,2 @@
-1.4.0
-202607210610
+1.4.1
+202607230114

ofuda/examples/glossary.md

@@ -2,6 +2,11 @@
 
 > このファイルは miko スキルの品質基準を示すサンプルです。
 > 実際のプロジェクトの用語集ではありません。
+>
+> 各項目は 1〜2文で「意味」だけを書く。判定: 実装技術を置き換えてもこの定義文は変わらないか？ 変わるなら実装の詳細（クラス名・メソッド名・API・処理手順）であり、glossary には書かない。
+>
+> 悪い例: 確定（confirm）— `OrderConfirmService#call` が注文の `status` を `confirmed` に更新する処理のこと
+> 良い例: 確定（confirm）— 注文内容が変更不可になること。決済処理の開始条件
 
 ## 全体
 

skills/miko.catchup/SKILL.md

@@ -164,7 +164,7 @@ $ARGUMENTS
 
 **glossary.md の更新:**
 - proposal で新しい用語が登場した場合は `miko/glossary.md` に追加する（ファイルがなければ作成）
-- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する
+- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く
 
 ### 12. high_level_design.md 更新
 

skills/miko.new-cap/SKILL.md

@@ -239,7 +239,7 @@ HLD の骨子（`.miko/examples/high_level_design.md` と同等の構造）を
 
 **glossary.md の更新:**
 - 新しい用語が出てきた場合は `miko/glossary.md` に追加する（ファイルがなければ作成）
-- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する
+- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く
 - 複数ケイパビリティで共通の用語は `## 全体` セクションに置く
 
 **生成時の注意:**

skills/miko.propose/SKILL.md

@@ -197,7 +197,7 @@ business_rules.md が存在するケイパビリティを対象に、サブエ
 
 **glossary.md の更新:**
 - proposal で新しい用語が登場した場合は `miko/glossary.md` に追加する（ファイルがなければ作成）
-- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する
+- `.miko/examples/glossary.md` のフォーマットに従い、該当ケイパビリティのセクションに追加する。実装の詳細（クラス名・メソッド名・API・処理手順）は書かず、1〜2文の定義だけを書く
 
 ### 11. 完了報告
 

skills/miko.quick-catchup/SKILL.md

@@ -115,7 +115,7 @@ diff ソース、変更の要約、ビジネスルールへの影響（新設/
 **ステップ 6 で生成した proposal の内容を business_rules.md に反映する。**
 - proposal の新設・改訂を適用する
 - 実装マッピングを更新する
-- 新しい用語があれば `miko/glossary.md` に追加する（`.miko/examples/glossary.md` のフォーマットに従う）
+- 新しい用語があれば `miko/glossary.md` に追加する（`.miko/examples/glossary.md` のフォーマットに従う。実装の詳細は書かず、1〜2文の定義だけを書く）
 
 ### 8. high_level_design.md 更新
 

skills/miko.setup/SKILL.md

@@ -123,7 +123,7 @@ miko を新しいプロジェクトに導入するための初期セットアッ
 
 用語集ファイルを生成する。コード調査で発見したドメイン用語を記載する。
 
-- `.miko/examples/glossary.md` のフォーマットに従う
+- `.miko/examples/glossary.md` のフォーマットに従う。実装の詳細（クラス名・メソッド名・API・処理手順）は書かない。辞書として1〜2文で意味だけを書く
 - 名前から想像しにくいもの、このプロジェクト固有の意味を持つものだけ
 - 一般的な技術用語は書かない
 - 同じ用語がケイパビリティごとに異なる意味を持つ場合は、それぞれのケイパビリティセクションに定義を書く