> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouquet-inc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lessons

# mintlify — 学び

> **書き方の規約**（全ファイル共通）
>
> * 教訓の**正は `~/Projects/プロジェクト管理/knowledge/lessons/`**（1教訓=1ノート）。入口は `~/tasks/lessons.md`
> * ここに書くのは **このリポジトリ固有**の教訓だけ
> * 本文は **事象 / なぜ起きたか / ルール** の3点セット。「なぜ起きたか」が書けないときは見出しを残して「（記録なし）」と書く
> * `scope`: `global`（全社）/ `noren` / `bouquet` / `repo:<リポジトリ名>`
> * **同じ失敗が2回出たら全社へ昇格する**（別の案件・別の部署で再発したら `knowledge/lessons/` にノートを作る）
> * **昇格したら、昇格元はポインタ1行にする。** 本文を2箇所に置かない（必ず片方が古くなる）

## 昇格済み（本文はここに置かない）

（なし）

## 2026-09-26

### アプリの注記にある「適用範囲」は、経路ごとに実装を見て書き分ける

scope: repo:mintlify

**事象**: Discount Deck の「マイページに表示しないクーポンコード」のページ初版で、「キーワードは登録したあとに作成されたクーポンから適用されます」を節全体の前提として書いた。スクリーンショットを撮ったところ、2025年作成のクーポンにも「表示対象外」ラベルが付き、手動表示もできなくなっていた。適用が「登録後のクーポンから」なのは自動表示（`discounts/create` の webhook）だけで、一覧のラベルと手動表示の制限は登録前のクーポンにもすぐ効く。
**なぜ起きたか**: アプリのヘルプ文（`excludeKeywordsHelpNotRetroactive`）の言い回しを節の見出しに流用し、webhook・一覧・詳細画面の3経路それぞれで判定がいつ走るかを確かめなかった。同じヘルプ文の「クーポン一覧から非表示に」も実装上は不可能（一覧で対象外の行は選択できない）で、画面の文言は実装どおりとは限らなかった。
**ルール**:

1. マニュアルでアプリの注記を言い換えるときは、その注記がどの経路（webhook / 一覧 / 詳細 / 同期ジョブ）の話かを実装で特定し、経路ごとに書き分ける
2. 画面の文言と実装が食い違ったら、実装に合わせて書き、食い違いをアプリ側へ報告する（今回は discount-deck#390 で文言が直った）
3. 可能なら、該当状態の画面を撮ってから本文を確定する。スクショで初めて気づくズレがある

### 制限・上限だけの変更は更新履歴に載せない

scope: repo:mintlify

**事象**: Discount Deck の「お客様1人あたりの表示クーポンを最大100件に」（discount-deck#360）を、スキルの「制約を隠さない」に従って更新履歴に書いた。ユーザーから「マイナスになるのでリリースにはのせない」と差し戻された
**なぜ起きたか**: 上限の追加は、リリース時点でどのストアの表示も変えない安全装置だった。載せても、マーチャントには「できることが減った」としか読めない。「制約を隠さない」は新機能に付く条件の話で、単独の制限を告知しろという意味ではなかった
**ルール**:

1. 制限・上限・機能縮小だけの変更で、リリース時点でマーチャントの表示や操作が変わらないものは載せない
2. 載せるかどうか迷ったら、下書きの段階でユーザーに確認する

### 最新日と同じ日にマージされた PR は list\_prs.py に出ないので、gh で確かめる

scope: repo:mintlify

**事象**: 9/26 の作業で、9/23 にマージされた discount-deck#370・#371 が候補に出なかった。9/23 の更新履歴を書いた前回のセッションでも拾われておらず、どこにも載っていなかった
**なぜ起きたか**: `tools/changelog-draft/list_prs.py:121` が `mergedAt[:10] > since` で、最新日と同じ日のマージを落とす。日付は UTC で比べている
**ルール**:

1. `list_prs.py` を実行したら、`gh pr list --state merged --search "merged:>=<最新日>"` で最新日当日のマージも確認する
2. スクリプトを直すまでは、このルールを毎回適用する

### 文言だけの変更も、活用施策を添えて前向きに書く

scope: repo:mintlify

**事象**: #390（「自動表示対象外のクーポンコード」→「マイページに表示しないクーポンコード」）は、動作の変わらない文言変更だった。ユーザーから「さも全てに対応できるようになった方向性で、シークレットセールなどの施策提案も含めて」と指示された。そのあと、例示の「社販クーポン」も「シークレットセールや社販対応」に広げるよう指示された
**なぜ起きたか**: スキルは「文言の表記ゆれ直しは書かない」としていて、販促に使える変更かどうかという観点がなかった
**ルール**:

1. 設定の意味が伝わりやすくなる文言変更は、「何に使えるか」の活用例（シークレットセール・会員限定など）を添えて載せる
2. 動作が変わっていないのに「新しくできるようになった」とは書かない。過去の更新履歴と食い違うため。「どの方法でも〜できる」のように、今の仕様を打ち出す
3. 例示は、売上施策（シークレットセールなど）を先に置く