ratel-assessment

/ratel-assessment — パートナーのエージェントコードベースを最初に監査

パートナーのスタートアップとの最初の会話が「Ratel を接続しましょう」になることは、ほとんどありません。「私たちのエージェントを理解していることを示してください」です。このスキルはその最初の窓口です。コードベースを読み、評価カタログのすべての観点を実行し、パートナーが社内で共有できる（そして実際に共有する）Markdown レポートを作成します。最終的に Ratel を使うことになるかどうかは問いません。

成果物は、<repo>/.ratel/ratel-assessment-<YYYY-MM-DD>.md に保存される、洗練されたエビデンス重視のレポートと、ブランドを反映したスコア付き HTML 版（ゲージ、レーダーチャート、観点ごとのスコアバー）です。HTML 版は <repo>/.ratel/ratel-assessment-<YYYY-MM-DD>.html に保存されます。各指摘にファイルパス、行範囲、または具体的な件数が記載されるため、このレポートには信頼性があります。Ratel に関連する指摘が「Ratel が適合する領域」セクションにまとめられ、具体的にリリース済みの機能やロードマップのバージョンと結び付けられるため、ストーリー性も備えています。さらに、スイートから適切な次のスキル（/ratel-observability-assessment、/ratel-integrate、/ratel-decompose-prompt、/ratel-tune-definitions）への条件付きの案内で締めくくるため、次の行動につながります。

このスキルは、スイート内のほかのスキルを補完します。

• ほかの4つより先に実行します。 パートナーによるセットアップがない状態で、初期状態のリポジトリに対して安全に実行できる唯一のスキルです。
• ほかのスキルへの道筋を示します。 「推奨される次のステップ」セクションでは、調査結果に応じて適切なフォローアップを示します。
• ほかのスキルのカタログと重複しません。 Ratel の観点からの指摘は ../ratel-observability-assessment/references/ratel-value-map.md を参照し、命名に関する参照先は ../ratel-observability-assessment/references/semantic-conventions.md です。

基本方針

ルールは3つです。どれか1つでも破れば、レポートは営業資料になり、パートナーにはすぐに見抜かれます。

1. すべての指摘に根拠を示すこと。 行範囲を含むファイルパス、件数、またはコードベースからの引用を示します。曖昧な主張（「可観測性の改善を検討してください」）には何の価値もありません。具体的な主張（「src/agents/*.ts 全体で47個のツールが登録されており、description が12語を超えるものはありません」）は、次の打ち合わせにつながります。根拠を示せない場合は、その指摘を削除してください。
2. 作り上げるより、正直にスキップすること。 コードベースがエージェントのものではない場合は、その旨を伝えて終了し、指摘をでっち上げないでください。ある観点に問題がなければ「良好」と評価して次に進み、無理に欠点を探さないでください。パートナーは、余計な内容があることより、ないことにすぐ気付きます。
3. Ratel は指摘の分類であり、結論ではありません。 Ratel の観点は、Ratel の対象領域（ツールの乱立、検索、分解、可観測性）に真に合致する指摘に関連付けます。すべての指摘に無理やり付け足して、「Ratel が適合する領域」セクションを膨らませてはいけません。Ratel に正当に結び付く指摘が2つだけなら、セクションに記載するのも2つです。水増しして8つにする必要はありません。

ワークフロー

ステップ1 — エージェントのコードベースを検出する

マニフェストを読み、エージェントの機能を検索します。顧客の技術スタックに応じて、ワークフローの残りの部分で検索するパターンが決まります。

# Manifests
test -f package.json && jq -r '.dependencies // {}, .devDependencies // {} | keys[]' package.json | sort -u
test -f pyproject.toml && head -200 pyproject.toml
test -f requirements.txt && cat requirements.txt
test -f uv.lock && head -50 uv.lock

# Agent surfaces — tool definitions, LLM clients, agent frameworks
grep -rEn 'tools:\s*\{|tools:\s*\[|defineTool|createTool|@tool\b|@function_tool\b|McpServer\(|StdioClientTransport|listTools|streamText|generateText|chat\.completions|messages\.create|invoke_model|graph\.add_node|Agent\(|Crew\(|@agent\b' \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' \
  | head -100

references/stack-detection.md を使って、技術スタックを分類します。技術スタックに応じて、ツール、プロンプト、サブエージェント、可観測性の設定をどこで探すかが決まります。エージェントの機能がまったく検出されない場合は、正直にスキップする手順を使います。

Step 2 — エージェントの構成を洗い出す

スコープを絞った単一のプロンプトを使って、Explore エージェントを 1 つ起動します（小規模なリポジトリであれば、直接作業してもかまいません）。エージェントの役割は、評価カタログで評価するための構成一覧を作成することです。次の項目をマッピングするよう依頼してください。

1. エージェントのエントリーポイント — HTTP ハンドラー、キューのコンシューマー、CLI の動詞、チャットプラットフォームの Webhook。各エントリーポイントを、ファイルパス付きで 1 つの箇条書きにします。
2. ツール定義 — ツールが宣言されているすべての箇所（レジストリ、デコレーター、MCP クライアントの設定）。総数。各ツールについて、ID、名前、説明の長さ、スキーマの有無、インラインか外部化されているかを記載します。
3. プロンプトテンプレート — すべてのシステム／ユーザー／ツールのプロンプト。保存場所（インライン文字列、個別ファイル、プロンプト管理サービス）。ファイルから容易に推定できる場合は、おおよそのトークン量も記載します。また、プロンプトに複数の関心事（役割＋ツールドキュメント＋出力形式＋例＋繰り返し実行する複数ステップの手順＋安全性）が混在しているか、繰り返し使われる指示ブロックが複数のプロンプトや呼び出し箇所に重複していないかも記録します。これはディメンション 11（プロンプトの分解）で使用します。
4. サブエージェントの境界 — スーパーバイザー／ワーカー／役割特化型エージェント、引き継ぎ箇所、サブエージェントが明示的（名前付き）か暗黙的（同じループを異なるプロンプトで実行）か。
5. セッション／コンテキストの処理 — 会話スレッド／ジョブの相関 ID の発生元、サブエージェントへの引き継ぎの有無。
6. モデルのルーティング — タスクごとに呼び出されるモデル、ルーティングがタスクを考慮しているか、または一律か。
7. エラー処理 — ツール呼び出し周辺の try/except の構成、リトライの有無、バックオフ、デッドレター。
8. メモリ／検索 — ベクトルストア、RAG パイプライン、会話メモリ、要約。
9. 可観測性の設定 — Ratel SDK のネイティブ OTLP テレメトリ／Langfuse／LangSmith／OTel／OpenInference／OpenLLMetry／Helicone／独自のロギング。環境変数、初期化箇所。
10. 評価対象 — 評価ディレクトリ、フィクスチャ、正解データセット、CI での呼び出し。

構成一覧は分析コンテキスト内に留めてください。これは成果物ではありません。レポートでは参照しますが、レポートには含めません。

Step 3 — オブザーバビリティを検出し、バックエンドに到達可能であればプローブする

Ratel のテレメトリはネイティブの OpenTelemetry です。SDK は、取得とツールのファネルを gen_ai.* スパン（semconv v1.42.0）と ratel.* のオーバーレイ（ratel.search、execute_tool <tool id>、ratel.skill.load）として出力し、パートナーがすでに運用している OTel バックエンド（Langfuse、LangSmith、独自のコレクター、または Ratel Cloud（近日公開））に標準の OTLP としてエクスポートします。Ratel は LLM 呼び出しのスパンを出力しません。それらはパートナー独自の LLM インストルメンテーションで扱います。そのため、検出ではベンダーを限定せず、特定のベンダーではなく、何らかのテレメトリの窓口を探します。

確認項目は 2 つです。

1. 静的確認：次のいずれかが存在するかを確認します。Ratel SDK のネイティブテレメトリ（configureTelemetry / configure_telemetry、ratelSpanProcessor / ratel_span_processor、RATEL_URL、またはローカルの trace= JSONL ストリーム）、エージェント関連の接続先を指す OTel/OTLP エクスポーター、.env* / サンプル環境変数ファイル / docker-compose にある Langfuse SDK または環境変数、LangSmith SDK、OpenInference / OpenLLMetry インストルメンテーション。
2. ライブ確認（可能な範囲で）：テレメトリバックエンドが接続され、到達可能な場合（認証情報があり、そのバックエンドの MCP サーバーがこのセッション用に設定されている場合）、低コストの集計クエリを 1 回試します（例：直近のトレース／サービス名を対象に、過去 24 時間のトレース数を取得する）。データが返された場合は、小規模なサンプル（トレース／実行を 50 件以下）を取得し、関連する所見（ツールサーフェス数、エラー率、レイテンシ、および Ratel の SDK が出力している場合は取得ファネルの top_k、hit_count、top_hit_score、origin）の補足に使用します。認証、ネットワーク、プロジェクトがない、トレースがないなど、何らかの理由で呼び出しに失敗した場合は、何も通知せず静的確認のみへ切り替えます。失敗を所見として提示しないでください。これはパートナー側の不具合ではありません。

カタログでは、ライブデータが必要な所見（「型情報のないツールの観測」— トレースでのみ観測可能）と、不要な所見（「件数に基づくツールの乱立」— 静的に観測可能）を区別しています。静的確認のみの場合は、ライブデータが必要な所見を単に省略します。それ以外の評価には影響しません。

Step 4 — 評価を実施する

references/assessment-catalog.md にあるすべての評価軸を確認します。それぞれについて、以下を行います。

• ステップ 2 のインベントリ（利用可能な場合はステップ 3 のライブサンプルも）を使って、検出ヒューリスティックを適用します。
• 評価基準に従って重要度を決定します：Critical / Major / Minor / Info。
• 根拠を添付します：ファイルパスと行範囲、件数、または引用したスニペット。
• カタログ項目に Ratel 関連の観点がある場合は、該当する Ratel の機能／バージョンを示す 1 行のタグを ../ratel-observability-assessment/references/ratel-value-map.md から付けます。

カタログにない評価軸を作らないでください。本当に新しい点に気付いた場合は、本文中に記載しつつ、レポートでは dimension: ad-hoc としてマークし、後でカタログに追加できるようにします。

Step 5 — スコアカードを採点する

12 個の評価軸それぞれに、次のいずれかを必ず 1 つ割り当てます。

• Strong — 適切に対処されています。Info を超える所見はありません。
• Adequate — 機能しています。Minor の所見は 1～2 件で、Major 以上の所見はありません。
• Weak — 重大な不足があります。Major の所見が少なくとも 1 件あります。
• Missing — 評価軸が存在しないか機能していません。Critical の所見が少なくとも 1 件あります。

次に、各ラベルをそのラベルの範囲内の 0～10 のスコアに変換し、references/assessment-catalog.md → 「Numeric score」の評価基準に従って総合スコア（12 個のスコアの平均、小数第 1 位まで）を算出します。ラベルを正式な評価とし、数値は HTML のゲージ、レーダーチャート、評価軸別のバーに表示する値です。ラベルと数値が食い違わないよう、各スコアを対応するラベルの範囲内に収めてください。

スコアカードはレポートの冒頭に置きます。パートナーが最初に目にするものです。正確に記載し、評価を甘くしないでください。

ステップ 6 — レポートを生成する

references/report-template.md の構成に従い、<repo>/.ratel/ratel-assessment-<YYYY-MM-DD>.md に出力します。日付を付けることで、複数回実行しても上書きせずに蓄積できます。

セクションは次の順序にします。

1. エグゼクティブサマリー — 1 段落の後にスコアカードの表を配置します。
2. 調査結果 — 重要度別（Critical → Major → Minor → Info）に分類します。各調査結果には、タイトル、ディメンション、重要度、根拠、重要である理由、推奨事項、任意で 1 行の Ratel の観点を含めます。
3. Ratel が適合する領域 — 各項目に含まれる Ratel の観点をまとめ、1 つの説明にします。価値マップにある具体的な Ratel の機能／ロードマップのバージョンと関連付けます。Ratel の観点がある調査結果が 1、2 件だけなら、このセクションは短くて構いません。
4. 推奨される次のステップ — 調査結果に基づく条件付きのスキル案内です。箇条書きで、それぞれ 1 行にします。以下の条件付き案内を参照してください。

次に、Markdown と並べてブランド化された HTML をレンダリングします。

1. 同じ内容を含む JSON ペイロードを組み立てます — partner、date、stack、scope、data_sources、overall_score、summary、12 個の dimensions（カタログの順序で {name, label, score} を含み、各カテゴリの展開可能なサブディメンションのドロップダウンに表示する「このスコアの理由」を 1 行で示す任意の why を追加可能）、任意の category_takeaways（{category name → one-line "so what"} のマップ。レンダラーは 12 個のディメンションを、レーダーグループ、ヒーロー部分のカテゴリ別ミニバー、スコアカードに表示される 4 つのスコア付きカテゴリ（Architecture & orchestration、Context & tools、Reliability & safety、Operations）にまとめます。これは各カテゴリの下に表示される、改善点を簡潔に示すハイレベルな説明です。下記の具体的な調査結果を示す必要があります）、findings 配列（title、dimension、severity、evidence、rationale、recommendation、任意の ratel_angle）、および任意の where_ratel_fits、next_steps、appendix。スキーマの詳細はassets/sample-payload.jsonに記載されています。コンテンツフィールドではインラインの `code` と *強調* を使用できます。レンダラーがそれらを変換し、それ以外はすべて HTML エスケープします。

2. ペイロードを一時ファイルに書き込み、同梱のレンダラーを実行します（チャートの幾何学的な描画と色分けはすべてレンダラーが行います。SVG を手動で計算しないでください）。

   python3 "<skill>/assets/render_report.py" \
     --data "<tmp>/payload.json" \
     --template "<skill>/assets/report-template.html" \
     --out "<repo>/.ratel/ratel-assessment-<YYYY-MM-DD>.html"
   

   <skill> は、このスキルのディレクトリです。出力されるのは、自己完結型の HTML ファイル 1 つです（CSS と SVG はインラインです。フォントは Google Fonts から読み込まれ、システムフォントにもフォールバックするため、オフラインでも読みやすく表示されます）。

3. フォールバック — python3 が利用できない場合は、assets/report-template.html を開き、同じペイロードの値を {{PLACEHOLDER}} トークンに直接入力します（トークンの一覧は render_report.py のヘッダーにあります）。どちらの場合も Markdown レポートに影響はありません。HTML の生成を妨げないでください。

ステップ 7 — 概要をインライン表示する

次の順序でチャットに出力します。

1. 総合スコア（Overall: 6.6 / 10）とスコアカード。簡潔な 1 行形式でも構いません（「Topology Strong 9.0 · Tools Weak 4.6 · Observability Missing 1.5 · ...」）。
2. 上位 3 件の調査結果。それぞれ 1 行で要約します。
3. 両方のファイルパス — .md と .html。
4. 推奨する次のステップのスキル。

レポートの本文全体をチャットに貼り付けないでください。ファイルが成果物です。

最後に、これを省略しないでください。 概要の後に、読者のブラウザーでブランド化された HTML レポートを開くかどうかを明示的に尋ねます。この案内は、チャット出力の中で最も目立つ行にしてください。読者が見落とさないよう、注意を引く絵文字を 1、2 個先頭に付けます（レンダリングされたレポートが見過ごされやすいため、ここはスイートが意図的に絵文字禁止のルールを緩和している唯一の箇所です）。レポートを開くかどうか、わかりやすい言葉で尋ねてください。読者が「はい」と答えた場合に限り、.html のパスに対して open（macOS）／xdg-open（Linux）／start（Windows）を実行します。確認せずに自動で開いてはいけません。このスキルの要点はブランド化されたレポートです。読者がファイルパスを追いかけるだけで終わらず、実際にレポートを開いて見るようにしてください。

条件付きポインター

「推奨される次のステップ」セクションは、調査結果に応じて記載します。該当しないスキルは決して列挙しないでください。調査結果とポインターの対応は次のとおりです。

評価で見つかった内容	ポインター
Observability に関する調査結果（Weak または Missing）がある、または Observability が存在し、ファネルに誘導したい場合	/ratel-observability-assessment
Ratel に関連する観点が付いた Tool surface の調査結果がある	/ratel-integrate
分解／トポロジーに関する Ratel 関連の調査結果がある	/ratel-integrate（自動分解のサポートはロードマップ上にあり、近日公開予定である旨を記載）
プロンプト分解の調査結果に Weak または Missing の次元がある	/ratel-decompose-prompt
定義品質の調査結果に Weak または Missing の次元がある	/ratel-tune-definitions
上記のいずれにも該当しない	セクション全体を省略する

各ポインターは1行で記載します。スキル名と、このレポートで該当する具体的な調査結果を記載してください。スキルの説明を言い換えないでください。パートナーは説明を読むことができます。

トーンと根拠

• 命令形、二人称を使ってください。「ツール呼び出しを type: tool のオブザベーションとしてラップしてください」とし、「そうするとよいかもしれません」のようには書かないでください。
• 絵文字やマーケティング的な形容詞は使わないでください。「Critical」は、レポートで控えめに使われているからこそ重みがあります。
• 深刻度を曖昧にしないでください。 Critical なら Critical と書いてください。Info を誇張しないでください。
• 調査結果の本文は、まず根拠を示してください。 第1段落では根拠を挙げ、第2段落ではそれが重要な理由を説明し、第3段落では推奨事項を述べてください。Ratel に関連する観点は末尾に1行で記載し、本文に織り込まないでください。
• レポート内で時期を限定しないでください。「直近のスプリントで」や「今朝から」のような表現は避けてください。パートナーは3か月後に読み返すかもしれません。

正直なスキップ方法

ステップ1の後、コードベース内に LLM クライアントのインポート、ツール定義、エージェントフレームワーク、モデル呼び出しのいずれも見つからない場合は、そこで終了してください。レポートは作成しないでください。ユーザーには次のように伝えてください。

エージェントのサーフェスは検出されませんでした — <確認したファイル> を調べました。エージェントが通常とは異なる場所にある場合は、その場所を教えてください。再度実行します。そうでなければ、このコードベースは /ratel-assessment の対象ではありません。

コードベースがエージェントであり、カタログで12の次元すべてにおいて Info より重大な問題が何も見つからなかった場合は、それでもレポートを作成してください。スコアカードはすべて Strong、またはほぼすべて Strong となり、調査結果のセクションは短くなります。結論は「このエージェントは良好な状態であり、Ratel に関連する観点は <0件または1件の項目> です」とします。それ自体が信頼性を高めるレポートです。内容を水増ししないでください。

参照ファイル

• references/assessment-catalog.md — 12 の評価軸、検出ヒューリスティック、重大度の評価基準、推奨事項、Ratel の観点を記載しています。中核となるファイルです。
• references/stack-detection.md — エージェントスタックを分類するためのクイックプレイブックです。より詳しい分析については、スタックごとの詳細を記載した /ratel-observability-assessment への相互リンクがあります。
• references/report-template.md — レポートの標準構成と、作成例です。

同梱アセット（HTML の成果物）：

• assets/report-template.html — {{PLACEHOLDER}} トークンを含む、自己完結型でブランドに忠実な HTML テンプレートです（Ratel の配色、ゲージ／レーダー／スコアバー領域、印刷用スタイルシート）。
• assets/render_report.py — 純粋な標準ライブラリのレンダラーです。チャートのジオメトリを計算し、プレースホルダーを埋めて、.html を書き出します。
• assets/sample-payload.json — 作成例のペイロードです。JSON スキーマのリファレンスとレンダリング用フィクスチャを兼ねています。

読み取り元（複製はしません）：

• ../ratel-observability-assessment/references/semantic-conventions.md — ベンダーに依存しない span/session/tag/attribute の共通語彙
• ../ratel-observability-assessment/references/ratel-value-map.md — Ratel の機能 → 可観測シグナル → バージョンに関する唯一の信頼できる情報源

Ratel の公式ドキュメントをパートナーに案内する場合は、docs.ratel.sh を使用してください。ツール取得の概念については https://docs.ratel.sh/docs/core/tool-retrieval に、ネイティブテレメトリーガイドについては https://docs.ratel.sh/docs/core/telemetry に記載されています。