新規 Tip 作成スキル（ai-product-dev-tips）
このリポジトリは、AI プロダクト開発のための「Tip」を集めたコレクションです。
各 Tip は、カテゴリ配下の連番ディレクトリ（例: nlp_processing/35）に置かれ、README.md を中心に構成され、ルートの README.md からリンクされます。あなたの役割は、他の Tip と同じ作者が書いたように見える新規 Tip を追加することです。ディレクトリ構成・README のスタイル・リンク形式を既存に揃え、コレクション全体の一貫性を保ってください。
全体を通じての指針は「新しいフォーマットを発明せず、近くの既存 Tip を真似ること」です。迷ったら、既存 Tip を複数開いて、それに倣ってください。
以下のステップを順番に実行します。
ステップ1 — カテゴリと番号を決める
-
ユーザーのトピックから「カテゴリディレクトリ」を判断する。
既存カテゴリは次の通り。
acceleration_processing, audio_processing, conda_processing, docker_processing, dockerfile, front_end, image_processing, io_processing, ml_ops, nlp_processing, others_processing, pytorch_tips, server_processing, video_processing, web_scraping。
ユーザーがカテゴリを指定していればそれを使う。2つで迷う場合は、ユーザーに簡潔に確認する。
-
「次の番号」を決める。
そのカテゴリ内の数字ディレクトリを列挙し、最大値 + 1 を採る。シェルコマンド例は ls -d nlp_processing/*/ | grep -oE '[0-9]+' | sort -n | tail -1。一部のカテゴリには名前付きサブディレクトリ（例: image_processing/openpose/1）もあるが、ユーザーが明らかにその名前付きサブコレクションに追加しようとしている場合を除き、直下の数字ディレクトリだけを数える。
-
新規ディレクトリは <category>/<番号>（例: nlp_processing/35）。
これを作成する。
ステップ2 — Tip のタイプを判断する（README のみ / コード付き）
トピックから、どちらのタイプかを判断する。Tip に不要なコードは足さないこと。ここの良い Tip の多くは README のみで完結している。
-
README のみ — 概念・比較・概要、または CLI コマンドや外部 UI で進める手順系で、このリポジトリから実行するスクリプトを伴わないもの。
既存例は nlp_processing/31（LLM 学習の基礎）、nlp_processing/33（NeMo 概要）、nlp_processing/34（NIM デプロイ手順）。
いずれも README.md のみ。
-
コード付き — 読者が実行する Python スクリプトを示す Tip。
この場合はステップ5でコード雛形も生成する。既存例は nlp_processing/29（train.py + Dockerfile + sh）、nlp_processing/30（predict.py）、image_processing/11（複数の .py + .sh + in_image/out_image ディレクトリ）。
判断に迷う場合は README のみをデフォルトとし、実行コードが必要かをユーザーに確認する。
ステップ3 — 書く前に調べる（フォーマットとトピック）（最重要）
書く前の調査は、Tip の品質と一貫性を決める最も重要な段階です。
「リポジトリのフォーマット」と「トピックの内容」の両方を調べる。
3-1. フォーマットを調べる
新規 Tip を既存 Tip と「同じ作者が書いたように」見せるための調査。リポジトリのフォーマットは時間とともに変化しているため、字面の古いものより新しい慣習に合わせます。次の順で調べる。
-
ルートの README_format.md を読んで、基本の発想だけ把握する。ただしこれはあくまで緩い骨子で、実際の Tip はそこから乖離しているため、字義どおりには従わない。
-
「最新コミットの README フォーマットを優先的に確認する」。最近追加・更新された Tip ほど、現在の好ましい書き方を反映している。git log -20 --name-only --pretty=format: -- '*/README.md' | grep README | sort -u などで最近変更された README を特定し、それらを開いてフォーマットの最新傾向（見出し構成・図の使い方・記述の粒度）を掴む。迷ったときは、最新コミット側の書き方を優先する。
-
既存の README を「10本程度」読んで、構成・見出しの付け方・記述の深さ・図表の使い方を掴む。同じカテゴリのものを中心にしつつ、他のカテゴリの README も必ず数本含める。カテゴリをまたいで読むことで、リポジトリ全体で共通する書き方（題名の付け方、## 参考サイト の置き方、コードブロックや図の使い方など）が見えてくる。トピックや Tip タイプ（概念・手順・コード付き）が近いものを優先して選ぶ。
このフォーマット調査を丁寧にやることが、一貫性のための鍵です。
3-2. トピックの内容を調べる（必要に応じて Web 調査）
Tip に書く技術的な内容（概念の正確な説明、手順、コマンド、API、最新のバージョンや URL など）を、思い込みで書かずに調べる。
特に、自分の知識が古い／曖昧な可能性があるトピック、最新の状況が重要なトピック（新しいツール・サービス・ライブラリの仕様、公式ドキュメントの URL など）では、Web 調査を行う。
- まとまった調査が必要な場合は、
/deep-research コマンド（deep-research スキル）を使って Web 調査を行う。複数ソースを横断し、主張を突き合わせて事実確認した上で、出典付きで内容を整理できる。調査したいトピックや確認したい論点を具体的に渡す（例: 「<ツール名> の plugin のインストール方法と公式ドキュメントの現行 URL」）。
- 個別の事実・URL の確認など軽い検証で十分な場合は、
WebFetch / WebSearch で該当ページを直接確認してもよい。
- 調べた内容（特にコマンド・コマンド名・URL・バージョン）は、ステップ4の正確性ルールに従って README に反映する。確認できたものだけ断定的に書き、確認できなかったものは
<!-- TODO: 要確認 --> を残すか、ユーザーに確認する。
Web 調査は常に必須ではない。内容が確実に分かっている軽量な Tip では省略してよいが、少しでも不確実さがあるなら調べる方が安全。
ステップ4 — Tip の README.md を書く
リポジトリが実際に使っている慣習に従う。詳細とコピペ用テンプレートは references/readme-format.md を参照。
基本ルールは次の通り。
-
H1 タイトルで始める（# <タイトル>）。
兄弟 Tip と同じ言い回しのスタイルにする。言語特化の Tip では 【Python】 / 【シェルスクリプト】 のプレフィックスを付けることがあるので、近隣に合わせる。
-
何を示す Tip かと重要な注意点を述べる、短い導入段落を書く。
-
図表で視覚的にわかりやすくする。
- アーキテクチャ／フロー図は、画像アップロード不要で GitHub 上でレンダリングされる Mermaid 図（
```mermaid）を優先する。表や ```text フェンスブロックも良い。
- 実スクリーンショット／図が必要なときだけ
<img width="500" alt="Image" src="https://github.com/user-attachments/assets/..." /> を使うが、画像はアップロードできないので <!-- TODO: 画像を貼り付け --> のプレースホルダを明示して入れ、その旨をユーザーに伝える。
- 特に、コンソール UI や Web 管理画面・操作画面のスクリーンショットがあると分かりやすい Tip（クリック箇所・設定画面・実行結果の画面などを示したい場合）では、該当箇所に
<img> プレースホルダ（src を空にし <!-- TODO: 画像を貼り付け --> を添える）を先回りして置いておき、後でユーザー自身が GitHub のコメント欄に画像をドラッグ&ドロップして得られる user-attachments URL を差し込めるようにする。
- どこにどの画面のスクショを貼るとよいかを、プレースホルダのコメントで具体的に示す（例:
<!-- TODO: 作成フォームのスクショ -->）。
- 既存例として
dev_optimize/ 配下の Tip は、操作画面のスクショ（user-attachments URL）を多用している。
- 図は情報を持たせること（構造・グルーピング・フロー・依存関係などを表現する）。要素を単に放射状に並べただけの図は価値が低いので、対象を種類ごとにまとめる、処理の順序を矢印で示すなど、読者の理解を助ける構造を与える。
- スクショがログイン不要の公開ページで得られる場合は、プレースホルダで止めず、plugin の Playwright（
mcp__plugin_playwright_playwright__*、無ければ mcp__playwright__*）で自動取得して添付する。
例えば、公式ドキュメント・GitHub の画面・管理コンソールの公開ページ・OSS のデモサイトなど、認証なしで開けてボット検知（Cloudflare の "Verify you are human" 等）でブロックされないページが対象。
手順は次の通り。
browser_navigate で対象 URL を開き、browser_take_screenshot（必要なら fullPage: true や要素指定）で撮る。クリック箇所・設定画面・実行結果など、その手順で見せたい状態にしてから撮る。- 取得した PNG を Tip ディレクトリ配下（例:
<category>/<番号>/images/）に保存してコミット対象にし、README では <img> の src を相対パス（例: src="images/01-create-form.png"）にする。Playwright のスクショはローカルファイルであり user-attachments URL にはならないため、相対パス参照にする。
alt に何の画面かを書き、必要なら width を周囲に合わせる。
- 一方で、ログインや認証が必要なページ（例:
claude.ai 配下のログイン後の操作画面、各種 SaaS の管理画面）や、ボット検知でブロックされるページは自動取得できない。その場合は無理に取得せず、従来どおり src を空にした <img> プレースホルダ＋<!-- TODO: 画像を貼り付け --> を置き、ユーザー自身が GitHub のコメント欄にドラッグ&ドロップして得る user-attachments URL を後で差し込んでもらう。認証情報（パスワード・2FA など）をユーザーに尋ねて代理ログインすることはしない。
- 公式サイトのマーケティング用ビジュアルなど、第三者の著作物の画像を操作スクショの代わりに転載しない。実際の操作画面でないものを操作スクショとして貼らない。
-
準備・導入・設定・実行・確認のように「順を追って行う内容」は、箇条書きの羅列ではなく番号付きの手順で書く。
読者がその順にたどれるようにするのが目的で、「〜を用意する」「〜を設定する」といった操作のまとまりは番号付き手順にする方が分かりやすい。単なる性質・ポイントの列挙（順序が無いもの）は通常の箇条書きでよい。
-
使い方／手順は、内部実装ではなく「外部から見た動かすための手順」を番号付きリストで書く。
リポジトリの Markdown 慣習に合わせ、各項目を 1. で始める（GitHub が自動採番する）。
実行コマンドはフェンスドコードブロック（sh / bash）に入れる。手順は具体的に書き、「〜を設定する」で済ませず、実際に打つコマンドや操作を示す。ただし正確なコマンド・識別子・パラメータ値が不確実な場合は、推測でもっともらしい値を捏造しない。<!-- TODO: 要確認 --> のプレースホルダを置くか、ユーザーに確認する。誤った具体値より、正直な TODO の方が読者にとって安全。
-
追加した Python コードの主なポイント（重要な設計判断・注目すべき箇所）を箇条書きで添えるのは OK。
ただしハイライトに留め、ファイル全体を逐一解説しない。
-
同梱コードファイルは相対リンクで参照する（例: [`run.py`](run.py)）。
-
末尾に ## 参考サイト セクションを置き、参考 URL を箇条書きする（該当する場合）。
URL は現行の公式 URL かユーザー提供のものを使う。記憶頼りで古い／存在しない可能性のある URL を推測で書かない。
不確実な場合は、URL を確認する（必要なら Web で）か、ユーザーに尋ねる。確認できない URL は載せない方がよい。
-
英語と日本語が隣接するケースでは前後に半角スペースを追加（例: 一度だけDesign Systemを構築する => 一度だけ Design System を構築する）
正確性についての全体原則として、README に書く事実・コマンド・コマンド名・URL・バージョンは、できる限り検証して書く。もっともらしいが確認していない値を断定的に書くのは避け、不確実なものはプレースホルダ（<!-- TODO: 要確認 -->）にするか、ユーザーに確認する。Tip は他者が参照する資料なので、「それらしさ」より「正しさ」を優先する。
README は周囲の Tip に合わせて日本語で書く。
ステップ5 — コード雛形を生成する（コード付き Tip のみ）
リポジトリの慣習に厳密に合わせる。テンプレート全文は references/code-scaffold.md を参照。
-
train.py / predict.py / run.py — argparse を使う Python エントリポイント。
多くは --device {cpu,cuda} オプションを持ち、実ロジックは if __name__ == "__main__": ブロックに書く。
-
requirements.txt — バージョン固定の依存。
近くの Tip のファイルのスタイルを流用する。
-
Dockerfile — 既存の CUDA/Ubuntu テンプレート（FROM nvidia/cuda:...）をベースに、Python と必要なライブラリをインストールし、COPY . ${WORKDIR} する。
兄弟 Tip の Dockerfile から始める。
-
実行スクリプト *_cpu.sh / *_gpu.sh — #!/bin/sh + set -eux。
イメージが無ければビルドし、その後スクリプトを docker run する。
GPU 版は --gpus all を渡す。
Tip が実際に必要とするファイルだけ作る。
例えば推論のみの Tip なら predict.py + predict_*.sh + Dockerfile + requirements.txt だけ、など。画像処理系のように Docker を使わない軽量な Tip では、.py と実行用 .sh、in_image/ out_image/ ディレクトリだけ、という構成も多い（image_processing/11 参照）。
ステップ6 — 作成した内容を検証する（過不足・矛盾・虚偽の確認）
README とコードを作成したら、公開（リンク登録・コミット）の前に、内容を必ず自己検証する。推測のまま確定させず、Web 調査で裏取りする。次の観点で確認する。
- 過不足: Tip の目的を達成するのに必要な前提・手順・説明が欠けていないか。逆に、冗長・不要な記述や、関係ない内容が混ざっていないか。
- 矛盾: 記述同士で食い違いがないか。特に README の説明と同梱コード（実際の引数・関数名・デフォルト値・挙動）が一致しているか、図・本文・コマンドの間に齟齬がないかを確認する。
- 虚偽・不正確: 事実・コマンド名・API・オプション・URL・バージョンに誤りがないか。
検証の方法は次の通り。
- 自分の知識だけで「正しいはず」と判断しない。特にコマンド名・API・公式 URL・最新仕様など、間違えやすい／古くなりやすい点は、
/deep-research や WebFetch / WebSearch で実際に確認する。
- 可能なら一次情報（公式ドキュメント）に当たる。URL は実際に開いて、生存とページ内容（リダイレクト先が変わっていないか等）を確認する。
- コード付き Tip では、README に書いた使い方と、コードの実体（引数・デフォルト値・出力先など）を突き合わせる。
- 可能であれば、紹介する挙動を実際に再現・実行して確認する。推測で「こう動くはず」と書かず、確認できた事実だけを断定的に書く。
見つかった問題は修正する。
どうしても確認できない事項は、断定せず <!-- TODO: 要確認 --> を残すか、ユーザーに確認する。
コードの自動レビュー（/code-review）
コード付き Tip では、上記の内容検証に加えて、生成したコードに対して /code-review を実行し、バグや明らかな問題がないかを確認する。
- 組み込みの
/code-review は、現在の差分（手元の変更）を対象にコードの正確性（バグ・CLAUDE.md 準拠など）をレビューするもので、PR を作らずに実行できる。Tip のコードを作成したら、これを実行して指摘を確認する。
- 指摘が出たら修正する。ただし Tip は教材的な最小コードなので、過剰な作り込みを促す指摘は取捨選択してよい。
- README のみでコードを含まない Tip では
/code-review の効果は限定的なので必須ではない。その場合は、内容の正確性検証（上記の Web 調査による裏取り）を主とする。
- 参考: plugin 版の
/code-review:code-review や /pr-review-toolkit:review-pr は GitHub の PR を対象とする。別ブランチ＆PR で開発している場合は、その PR に対してこれらを使ってもよい（master 直接運用の場合は、PR がないため組み込みの /code-review を使う）。
この検証を、リンク登録・コミットの前のゲートとして必ず行う。
ステップ7 — ルート README.md にリンクを登録する
ルート README は、Tip を <details><summary>カテゴリ名</summary> ... </details> ブロック内のネストされた箇条書きとしてグループ化している。
-
該当する <details> セクションと、この Tip が属する最も適切なサブトピックを探す。同じテーマの近隣 Tip がどうグループ化・インデントされているかを見る。
-
近隣と完全に同じ形式で箇条書きを追加する。形式は次の通り。
- [<タイトル>](https://github.com/Yagami360/ai-product-dev-tips/tree/master/<category>/<番号>)
リンクテキストは Tip の H1 タイトルと一致させる。周囲のインデント（サブ項目は 4 または 8 スペース）を保つ。
-
未完成の Tip にはデフォルトで [In-progress] を付ける。重要なのは「[In-progress] をリンクの角括弧の中（リンクテキストの先頭）に置く」こと。正しい形式は - [[In-progress] <タイトル>](URL) で、- [In-progress] [<タイトル>](URL) のようにリンクの外に置くのは誤り。[In-progress] の直後の空白の有無は近隣の表記に合わせる（[[In-progress]【GCP】...] のように詰める例と、[[In-progress] Ambassador...] のように空ける例の両方がある）。ユーザーが「完成済み」と言った場合は付けない。迷う場合はユーザーに確認する。
-
URL は https://github.com/Yagami360/ai-product-dev-tips/tree/master/... をそのまま使う。別のホストやブランチを勝手に使わない。
ステップ8 — 報告する
ユーザーに簡潔に伝える。
- 新規ディレクトリのパスと作成したファイル。
- 作成した Tip の
README.md のフルパス（絶対パス）を明示する。ユーザーがすぐ開いて確認できるよう、/home/.../<category>/<番号>/README.md の形で必ず示す。コードファイルなど他の生成物もある場合は、それらのフルパスも併せて示す。
- ルート README にリンクを追加したこと、およびどのセクションに入れたか。
- 残した
TODO（画像アップロード、埋めるべきコマンド値、参考 URL など）。
コミット／反映について
新規 Tip の追加は、デフォルトで master ブランチへ直接コミット・push してよい。
別ブランチの作成や PR の作成は不要。これは個人運用のリポジトリで、新規 Tip 追加は単純な追記作業のため。
ただし、ユーザーから「別ブランチで開発したい」「PR を作って」といった依頼がある場合は、その限りではない。その場合は、新規ブランチを切ってコミットし、PR を作成する（ユーザーの指示に従う）。
なお、コミット・push を行うのはユーザーがそれを望むときだけにする。ファイルを作成しただけで、ユーザーが反映を指示していない段階では、勝手に push しない。
push が完了したら、リモート上の以下のリンクをユーザーに伝える。ユーザーがすぐに GitHub 上で確認できるようにするため。
- 追加した Tip ディレクトリ:
https://github.com/Yagami360/ai-product-dev-tips/tree/master/<category>/<番号>
- ルート README:
https://github.com/Yagami360/ai-product-dev-tips/blob/master/README.md
やってはいけないこと
README_format.md を機械的に当てはめない。実際の近隣 Tip、特に最新コミットのものを真似る。- リポジトリのコードを実行しない概念・手順系 Tip に、Dockerfile やスクリプトを生成しない。
user-attachments の画像 URL を捏造しない。プレースホルダを残す。- 既存 Tip の番号変更や並べ替えをしない。追記のみ。