netra-best-practices

Netra のベストプラクティス

Netra を使用した AI システムの統合、運用、改善をエンドツーエンドで進めるためのガイドとして、このスキルを使用してください。

ステップ 1 — プロジェクトの言語を検出する

何よりも先に、プロジェクトが Python または TypeScript/JavaScript のどちらであるかを判断してください。次の順序でプロジェクトのルートを確認します。

シグナルファイル	言語
pyproject.toml、setup.py、requirements.txt、Pipfile	Python
package.json、tsconfig.json、bun.lockb	TypeScript / JavaScript

両方が存在する場合（モノレポの場合）は、どのサブプロジェクトで作業しているかをユーザーに確認してください。どちらも見つからない場合は、ユーザーに確認してください。

以降は、検出した言語向けのリファレンスのみを使用してください。Python と TypeScript のパターンを決して混在させないでください。

ステップ 2 — インストール

netra-sdk をインストールする前に、パッケージマネージャーを検出してください。次の優先順位で確認します。

優先度	シグナルファイル	コマンド
1	uv.lock	uv add netra-sdk
2	poetry.lock	poetry add netra-sdk
3	pyproject.toml（上記のロックファイルがない場合）	pip install netra-sdk
4	requirements.txt（上記の Python を示すファイルがない場合）	pip install netra-sdk
5	yarn.lock	yarn add netra-sdk
6	pnpm-lock.yaml	pnpm add netra-sdk
7	package-lock.json	npm install netra-sdk
8	bun.lockb	bun add netra-sdk
9	見つからない	続行する前に、ユーザーに確認する

インストールコマンドを複数実行したり、グローバルにインストールしたりしないでください。

ステップ 3 — 適切なリファレンスを読み込む

検出した言語とユーザーのユースケースに基づいて、適切なリファレンスファイルを読んでください。

Python のリファレンス（references/python/ 内）

ユースケース	リファレンスファイル
LLM アプリケーションの計装	python/instrumentation.md
評価／テストスイートの実行	python/evaluation.md
複数ターンのシミュレーションの実行	python/simulation.md
カスタムメトリクス（カウンター、ヒストグラム、ゲージ）	python/custom-metrics.md

TypeScript のリファレンス（references/typescript/ 内）

ユースケース	リファレンスファイル
LLM アプリケーションの計装	typescript/instrumentation.md
評価／テストスイートの実行	typescript/evaluation.md
複数ターンのシミュレーションの実行	typescript/simulation.md
カスタムメトリクス（現在、TS ではサポートされていません）	typescript/custom-metrics.md

ステップ 4 — ハルシネーション防止ルール

Netra コードを生成する際は、以下のルールを厳守してください。

1. Netra の公式ドキュメントに記載されていない列挙型の値は絶対に使用しないでください。推測しないでください。

2. Python と TypeScript の規約を絶対に混在させないでください。具体的には、以下のとおりです。

   • Python のパラメーターには snake_case を使用します（as_type、module_name、app_name）
   • TypeScript のパラメーターには camelCase を使用します（asType、moduleName、appName）
   • Python のインストゥルメントセット：{InstrumentSet.OPENAI}（通常のセットリテラル）
   • TypeScript のインストゥルメントセット：new Set([NetraInstruments.OPENAI])（Set コンストラクター）

3. ライフサイクルの違いを守ってください。

   • Python：Netra.init(...) は同期処理です
   • TypeScript：await Netra.init(...) は非同期処理です。必ず await してください
   • Python：with Netra.start_span(...) as span: は自動的にクローズします
   • TypeScript：finally 内で span.end() を手動で呼び出す必要があります

4. API が不明な場合は、推測せず、以下のドキュメント取得手順に従ってください。

ステップ 5 — ドキュメント取得の代替手順

ユースケースが参照ファイルで扱われていない場合：

1. ドキュメントのインデックスを取得します：https://docs.getnetra.ai/llms.txt
2. インデックスから関連するドキュメントページを特定します。
3. そのページを取得し、詳細なガイドを確認します。

フィードバック

結果に満足できない場合は、https://github.com/KeyValueSoftwareSystems/netra-skills/issues/new で issue を作成するよう案内してください。