ramp
不慣れなリポジトリ内のトピックを、グループ化されたノード、ラベル付きエッジ、クリックスルー詳細パネル、そして実際の実行時シーケンスを追跡する番号付きウォークスルーを持つインタラクティブなマップに変換します。
パイプラインは意図的に分割されています。静的パスはどのコードが重要かを見つけ、あなたがそれが何を意味するかを決定し、レンダラーがそれを描画します。静的パスをスキップしてリポジトリを自由に読むのは遅く、ファイルを見落とします。あなたのパスをスキップすると、誰も何も学べないコールグラフが生成されます。
ワークフロー
1. スキャン
node ~/.claude/skills/ramp/scripts/scan.js <repo> --topic "<トピック>" --max 30 --out /tmp/scan.json
パスは絶対パスです。なぜなら、ここからではなくターゲットリポジトリから実行するからです。
まだリポジトリの形状がわからない場合は、最初に --topic なしで実行してください。言語構成、最大のディレクトリ、最もインポートされているファイル（hubs）の概要が表示されます。これで通常、良いトピックを選ぶのに十分です。
トピックスキャンは、ランク付けされた nodes（ファイル、score、マッチした用語 matched、抽出された defs を含む）と、それらの間の edges を返します。seed: true は直接的なトピック一致を示します。残りはグラフ展開によって到達したもので、全体像を完成させる呼び出し元と呼び出し先です。
何も返されない場合は、トピック用語がコード内に存在しません。ユーザーが使用した語彙ではなく、コードベースで使用されている語彙を試してください。
2. 読み取り
シードファイルと、名前から示唆に富む展開されたノードを読んでください。きちんと読みましょう。マップの価値はすべて説明にあり、ファイルリストから有用な detail を書くことはできません。
読み取り中は、特に以下を探してください：
- エントリポイント — このフローは実行時にどこから始まるか？
- 非自明なもの — バグを防ぐガード、実際の処理を行う設定フラグ、新人が驚くようなもの
- 実際のシーケンス — 実行時に何が何を、どの順序で呼び出すか
3. モデリング
モデルJSON（スキーマは以下）を書いてください。これには判断力が必要な部分です。
4. レンダリング
node ~/.claude/skills/ramp/scripts/render.js /tmp/model.json -o /tmp/<repo>-<topic>.html
厳密に検証し、壊れたモデル（エッジ内の不明なノードID、重複ID、存在しないウォークスルー参照）は拒否します。説明されていないノードや孤立ノードに関する警告は、無視するよりも修正する価値があります。
5. 公開
レンダリングされたファイルをArtifactツールで公開し、ユーザーにリンクを渡してください。artifact-design を先にロードしないでください。テンプレートは既にデザインされています。そのまま公開してください。
モデルスキーマ
{
"title": "サインインフロー",
"repo": "my-app",
"summary": "1〜2文：全体の形状と、それについて最も有益な事実。",
"groups": [{ "id": "boot", "label": "アプリ起動", "hint": "オプションのツールチップ" }],
"nodes": [{
"id": "provider",
"label": "AuthProvider",
"group": "provider",
"role": "セッション状態を所有",
"detail": "新人が実際に必要とする段落。",
"files": ["src/context/AuthContext.jsx:12"],
"symbols": ["AuthProvider", "signInWithGoogle"]
}],
"edges": [{ "from": "provider", "to": "supabase", "label": "getSession, OAuth" }],
"walkthrough": [{ "node": "provider", "text": "このステップで何が起こるか。" }]
}
groups は左から右へ、依存関係の順の列です。エントリポイントを左に、プリミティブを右に配置します。エッジはインポーターからインポート先へ描画されるため、この順序に従ったグループはきれいにレイアウトされます。最大6つのグループに異なる色が割り当てられます。
walkthrough はオプションですが、これが教える機能です。ファイル構造ではなく実行時シーケンスで順序付けしてください。ノードは複数回出現しても構いません。フローはループバックすることがあり、それを示すことが重要です。
良いマップと役に立たないマップの違い
ノードは概念であり、ファイルではありません。 1つのアイデア（AuthContext.jsx + AuthContextValue.js）を表す2つのファイルは1つのノードにできます。1つのファイルに2つの無関係な責任がある場合は2つのノードにできます。実際のファイルはすべて、files に含めてください。
6〜14ノード。 40ノードのマップは、ユーザーがすでに凝視していたヘアボールです。フローを伝えるものに絞ってください。スキャンの score 順序が何を残すべきかを示します。summary で何を省いたかを述べてください。
role は役割であり、言い換えではありません。 「セッション状態を所有」— 「認証プロバイダコンポーネント」ではありません。
detail はクリックに値するものでなければなりません。 名前から自明でないことを書いてください。なぜこのように分割されているのか、重要なフラグ、防いでいる障害、前提としていること。detail がラベルを言い換えているだけなら、そのノードを削除するか、実際に何をするのか調べてください。
すべてのエッジに実際の関係をラベル付けしてください — 「uses」や「imports」ではなく、「userで制御」、「getSession, OAuth」など。
行番号を引用してください。 files 内の path/to/file.ts:42 は、読者を正確な場所に導きます。
重要な部分とそうでない部分を述べてください。 新人が最も知る必要があるのは、どの部分を無視してもよいかです。
注意事項
- スキャンはゼロ依存のNodeであり、インストールは不要です。ターゲットがgitリポジトリの場合、
.gitignoreを尊重します。 - Swift、および同じパッケージ内のJava/C#にはファイルレベルのインポートがありません。これらの場合、スキャンは代わりに一意の型参照からエッジを推測します。これらのエッジは強いヒントとして扱い、確実なものとは見なさないでください。
- インポート解決は正規表現ベースであり、型チェッカーではありません。相対パス、バンドラーエイリアス（
@/）、およびパッケージスタイルの指定子をパス接尾辞で解決します。動的インポートや生成されたインポートは見逃されます。期待するファイルがない場合は、自分でモデルに追加してください。