polite-mcp-conventions

Polite-MCP ファミリー：エージェント間の連携規約

この作者自身のショッピング／クラシファイド自動化ファミリーにおける動作規約です。対象は、作者のマシン上にのみ存在する olx-polite-mcp とその兄弟リポジトリです。同じリポジトリの開発ループ／配布の仕組みを扱う mcp-server-shipping や、マシンに常時読み込まれている、真に普遍的な規約をまとめた指示ファイルとは別のものです。これらは、ユーザー自身の、ログイン済みの個人アカウントを使った自動化というドメインに特化したものです。別の環境にインストールしても規約の内容は変わりませんが、リポジトリ名は作者のものです。

初回の実際の変更操作の前に確認する

セッション中にユーザーの実際の個人アカウント（ログイン済み）に対して初めて変更を伴うブラウザー操作を行う前に（例：ドライリードではなく、実際にカートに追加するクリック）、操作を実行するのではなく、AskUserQuestion を使って確認してください。範囲が限定され、低コストで、元に戻せる操作であっても同様です。一般的な許可の依頼ではなく、単発の限定的なテストとして（何を実行するか、該当する場合はその後に取り消す／元に戻すことも）説明してください。承認を得て、操作の内容と動作を確認した後は、同じセッション中に同種の操作を続ける際、再確認は不要です。

**理由：**このファミリーでは、チェックアウトや個人アカウントに関する操作を、単なる読み取りよりも実質的にリスクの高いカテゴリとしてすでに扱っています。各リポジトリの境界に関するドキュメントにも、「チェックアウトは自動化しない」「CAPTCHA を解かない」などと記載されています。実際のアカウントを使った初回の変更テストは、個々の操作が小規模であっても、同じカテゴリに当てはまります。2026-08-14 に freshful-polite-mcp で実施した確認では、最初のカート追加テストの前に尋ねたところ、手間のかからない明確な「はい、安価な商品を1つ使ってテストしてください」という回答が得られました。過剰に慎重になるのではなく、これが適切なデフォルトです。

アイテムごとの対話的な判断はまとめて行い、入力リストを求めない

ワークフローでユーザーに複数の小さな個別判断を求める場合（例：「この8つのアイテムをそれぞれ何個にしますか？」）、おすすめのデフォルトを最初の選択肢としてあらかじめ設定したうえで、AskUserQuestion を使っておおむね4件ずつまとめて尋ねてください。大きなリストを提示して、すべての回答を1回の返信で入力するよう求めないでください。

**理由：**Freshful の再注文フローのセッション中に、明確なフィードバックがありました。「全部の品目の数量を提案して、1つずつ聞いてください。対話的に進める必要があります。全部を入力しないといけないと、使い勝手が悪くなります。」長く構造化された返信を入力するより、短いガイド付きの質疑応答のほうが優れたユーザー体験です。どちらも同じ情報を伝えられるとしてもです。

**適用方法：**この方法で分けられない判断や、まとめて尋ねても手軽に収まらないほどアイテム数が多い場合に限り、自由記述の質問を1つだけ使ってください。その場合は、すべてを一律にまとめて尋ねるのではなく、フロー自体の再構成が必要かどうかを検討してください（例：「そろそろ必要なアイテム」と「めったに注文しないアイテム」に分ける）。

実装の前または並行して、スパイク／調査の結果をPLAN.mdに記録する

調査／スパイクの段階（実環境でのCDP調査、APIのプローブ、DOMの調査）で、計画を変更または裏付ける知見が得られたら、実際の実装コードを書く前または並行して、まずリポジトリのPLAN.mdに独立したセクションとして記録してください。ドキュメントの既存の記述スタイルに合わせてください。知見を会話の中だけに留めて、すぐにコードに取りかかってはいけません。

理由： 明示的な指示、freshful-polite-mcp（2026-08-14）：「すべてを計画に記録してから実装するのがよいです」。このリポジトリ群に共通する既存の方針にも合致しています。PLAN.md（単一の長大なファイルです。このリポジトリ群は、plan-docsスキルで説明されているplans/YYYY-MM-DD-topic.md規約よりも前から存在しており、そちらへの移行も行われていません）は、アーキテクチャがその形になっている「理由」を長期にわたって記録するものです。コードコメントからは、同じ説明を繰り返さず、PLAN.mdを参照します。

適用方法： これらのリポジトリで実環境を使ったスパイク／調査を行った後は、実装に進む前に、PLAN.mdの該当セクションを更新してください。解決済みの未解決事項に印を付け、日付入りの調査結果セクションを追加し、その知見に関わる境界に関する判断を改めて記載または補足します。そのラウンドでユーザーから記録を明示的に求められていない場合も、必ず行ってください。これを標準的な手順として扱います。