Skip to main content

​
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. 例示は、売上施策（シークレットセールなど）を先に置く