chromadb-integration-skills

ChromaDB 統合スキル

目的：このスキルでは、エージェントがあらゆる分野（研究、コード、取引、法律、ドキュメントなど）で、セマンティック検索、永続ストレージ、パターンマッチングに ChromaDB を統合する方法を説明します。

重要なユースケース：大規模なデータセット（1000 件以上）を扱う、セマンティック検索を実行する、永続的なナレッジを維持する、または過去のパターンから学習する必要がある場合、ChromaDB によってトークン制限がなくなり、ベクトルベースの強力な検索が可能になります。

利用者：研究者、開発者、トレーダー、法律アナリスト、ドキュメント作成者、QA テスターなど、あらゆる種類のエージェント

---

ChromaDB 統合を使用する場面

次のような場合に ChromaDB を使用します。

• 大規模なデータセット：1000 件以上の項目（ドキュメント、コードファイル、バグ、取引、契約など）を扱う場合
• セマンティック検索：キーワードだけでなく、意味に基づいて項目を検索する場合
• 永続メモリ：ナレッジをセッション、日、月をまたいで保持する必要がある場合
• パターンマッチング：意思決定のために、過去の類似事例やパターンを特定する場合
• セッションをまたいだ学習：時間をかけて組織のナレッジを構築する場合
• トークン制限：データが大きすぎてコンテキストウィンドウに収まらない場合（100K トークン以上）
• 集約：複数のクエリやソースの結果を組み合わせる場合

---

ChromaDB の基本概念

コレクション

定義：埋め込みとメタデータを含むドキュメントを保存する、名前付きのベクトルデータベースです。

命名戦略：

• ドメインベース：{domain}_{purpose}_{identifier}
• 例：
  • 研究：research_prior_art_blockchain_2024、research_literature_ml_transformers
  • コード：codebase_api_endpoints、codebase_bug_patterns_auth
  • 取引：backtest_results_sma_strategy、market_conditions_spy_2024
  • 法律：case_law_patent_eligibility、contracts_saas_clauses
  • ドキュメント：api_docs_v2、architecture_decisions_2024

ドキュメント

定義：セマンティック検索の対象となるテキストコンテンツです。

ベストプラクティス：

• チャンクサイズ：200～500 語が最適です（小さすぎるとコンテキストが失われ、大きすぎると粒度が低下します）
• コンテンツ形式：タイトル + 要約 + 重要な詳細（例："Patent US10123456 - Blockchain Authentication. Abstract: A method for..."））
• 重複排除：一意の ID を使用して重複保存を防ぎます

メタデータ

定義：セマンティック検索ではなく、フィルタリングに使用する構造化データです。

戦略：

{
  // Temporal filters
  "date": "2024-11-14",
  "year": 2024,
  "month": 11,

  // Categorical filters
  "type": "bug_report",
  "category": "authentication",
  "severity": "high",

  // Numeric filters
  "citations": 42,
  "price": 150.25,
  "performance_score": 0.87,

  // Source tracking
  "source": "github_issue",
  "author": "kim-asplund",
  "url": "https://..."
}

埋め込み

定義：意味的な類似性を可能にするベクトル表現です。

仕組み：

• ChromaDB はドキュメントテキストから埋め込みを自動生成します
• 類似した意味 → 類似したベクトル → ベクトル空間内で近い位置
• 距離指標（コサイン距離、ユークリッド距離）で類似性を測定します

---

ChromaDB の汎用ワークフロー

フェーズ 1：コレクションの設計

// Step 1: Design collection strategy based on agent type
const collectionStrategy = {
  research_agent: "One collection per research topic/question",
  code_agent: "Collections by codebase module/feature",
  trading_agent: "Collections by strategy/timeframe/symbol",
  legal_agent: "Collections by practice area/jurisdiction",
  documentation_agent: "Collections by project/version"
};

// Step 2: Create collection with descriptive metadata
mcp__chroma__create_collection({
  collection_name: "{domain}_{purpose}_{identifier}",
  embedding_function_name: "default",  // Uses sentence transformers
  metadata: {
    created_date: "2024-11-14",
    domain: "research|code|trading|legal|docs",
    purpose: "Descriptive purpose",
    total_items: 0,  // Will update
    last_updated: "2024-11-14"
  }
});

フェーズ 2：データの取り込み

// Step 1: Batch data collection (minimize API calls)
const items = collectAllItems();  // From API, files, database, etc.

// Step 2: Transform to ChromaDB format
const documents = items.map(item => formatDocument(item));
const ids = items.map(item => item.id || generateUniqueId());
const metadatas = items.map(item => extractMetadata(item));

// Step 3: Batch insert (ChromaDB handles chunking automatically)
mcp__chroma__add_documents({
  collection_name: collectionName,
  documents: documents,
  ids: ids,
  metadatas: metadatas
});

// Step 4: Update collection metadata
mcp__chroma__modify_collection({
  collection_name: collectionName,
  new_metadata: {
    ...existingMetadata,
    total_items: items.length,
    last_updated: new Date().toISOString()
  }
});

フェーズ 3：セマンティック検索

// Step 1: Formulate semantic query (natural language works!)
const query = "authentication failures in production environment";

// Step 2: Execute semantic search with filters
const results = mcp__chroma__query_documents({
  collection_name: collectionName,
  query_texts: [query],
  n_results: 20,
  where: {
    "$and": [
      { "environment": "production" },
      { "severity": { "$in": ["high", "critical"] } },
      { "date": { "$gte": "2024-01-01" } }
    ]
  },
  include: ["documents", "metadatas", "distances"]
});

// Step 3: Filter by semantic similarity (distance threshold)
const highlyRelevant = results.ids[0].filter((id, idx) =>
  results.distances[0][idx] < 0.3  // Adjust threshold based on use case
);

// Step 4: Retrieve full details if needed
const fullDetails = mcp__chroma__get_documents({
  collection_name: collectionName,
  ids: highlyRelevant,
  include: ["documents", "metadatas"]
});

フェーズ 4：パターンマッチング

// Cross-collection pattern detection
const allCollections = mcp__chroma__list_collections();
const relevantCollections = allCollections.filter(c =>
  c.startsWith(collectionPrefix)
);

const patterns = [];
for (const collection of relevantCollections) {
  const matches = mcp__chroma__query_documents({
    collection_name: collection,
    query_texts: [patternQuery],
    n_results: 10,
    where: { "outcome": "success" }  // Only successful cases
  });

  if (matches.ids[0].length > 0) {
    patterns.push({
      collection: collection,
      matches: matches,
      success_rate: calculateSuccessRate(matches)
    });
  }
}

// Identify best pattern
const bestPattern = patterns.sort((a, b) =>
  b.success_rate - a.success_rate
)[0];

---

ユースケースのテンプレート

テンプレート 1：研究エージェント — 文献レビュー

課題：1000 件以上の研究論文を保存し、意味的に類似する研究を検索する

// Collection: research_literature_{topic}
const papers = fetchPapersFromAPI("machine learning transformers");

mcp__chroma__create_collection({
  collection_name: "research_literature_ml_transformers",
  metadata: { topic: "ML Transformers", papers_count: 0 }
});

// Store papers with rich metadata
papers.forEach(paper => {
  mcp__chroma__add_documents({
    collection_name: "research_literature_ml_transformers",
    documents: [`${paper.title}. ${paper.abstract}`],
    ids: [paper.doi || paper.id],
    metadatas: [{
      title: paper.title,
      authors: paper.authors.join(", "),
      year: paper.year,
      citations: paper.citation_count,
      venue: paper.venue,
      url: paper.url
    }]
  });
});

// Semantic search: "Find papers about attention mechanisms for vision"
const relevant = mcp__chroma__query_documents({
  collection_name: "research_literature_ml_transformers",
  query_texts: ["attention mechanisms computer vision"],
  n_results: 20,
  where: { "year": { "$gte": 2020 }, "citations": { "$gte": 50 } }
});

メリット：トークン制限なし、セマンティックな発見、引用によるフィルタリング、永続的なライブラリ

---

テンプレート 2：コードエージェント — バグパターンの認識

課題：バグレポートを保存し、類似する問題を特定して解決策を提案する

// Collection: codebase_bug_patterns_{module}
const bugs = fetchAllGitHubIssues("is:issue label:bug");

mcp__chroma__create_collection({
  collection_name: "codebase_bug_patterns_auth",
  metadata: { module: "authentication", total_bugs: 0 }
});

// Store bugs with solutions
bugs.forEach(bug => {
  mcp__chroma__add_documents({
    collection_name: "codebase_bug_patterns_auth",
    documents: [`Bug #${bug.number}: ${bug.title}. ${bug.body}`],
    ids: [`bug_${bug.number}`],
    metadatas: [{
      number: bug.number,
      title: bug.title,
      severity: bug.labels.find(l => l.startsWith("severity:"))?.split(":")[1],
      status: bug.state,
      solution: bug.resolution || "No solution yet",
      created_at: bug.created_at,
      resolved_at: bug.closed_at,
      url: bug.html_url
    }]
  });
});

// New bug arrives - find similar historical bugs
const newBugDescription = "User login fails with 401 error after password reset";

const similarBugs = mcp__chroma__query_documents({
  collection_name: "codebase_bug_patterns_auth",
  query_texts: [newBugDescription],
  n_results: 10,
  where: { "status": "closed", "solution": { "$ne": "No solution yet" } }
});

// Extract solution from most similar resolved bug
const suggestedSolution = similarBugs.metadatas[0][0].solution;

メリット：バグパターンの即時マッチング、解決策の再利用、類似する問題の検出

---

テンプレート 3：取引エージェント — バックテスト結果データベース

課題：10,000 件以上のバックテスト結果を保存し、最適なパラメータパターンを特定する

// Collection: backtest_results_{strategy_name}
const backtests = runParameterSweep(strategyCode, parameterRanges);

mcp__chroma__create_collection({
  collection_name: "backtest_results_sma_crossover",
  metadata: { strategy: "SMA Crossover", total_backtests: 0 }
});

// Store each backtest with parameters + results
backtests.forEach(backtest => {
  const description = `
    SMA Crossover strategy with fast=${backtest.params.fast_period},
    slow=${backtest.params.slow_period}, stop_loss=${backtest.params.stop_loss}.
    Market conditions: ${backtest.market_regime}, volatility=${backtest.avg_volatility}.
  `;

  mcp__chroma__add_documents({
    collection_name: "backtest_results_sma_crossover",
    documents: [description],
    ids: [`backtest_${backtest.id}`],
    metadatas: [{
      fast_period: backtest.params.fast_period,
      slow_period: backtest.params.slow_period,
      stop_loss: backtest.params.stop_loss,
      sharpe_ratio: backtest.sharpe_ratio,
      max_drawdown: backtest.max_drawdown,
      win_rate: backtest.win_rate,
      total_return: backtest.total_return,
      market_regime: backtest.market_regime,
      symbol: backtest.symbol,
      timeframe: backtest.timeframe,
      start_date: backtest.start_date,
      end_date: backtest.end_date
    }]
  });
});

// Find optimal parameters for current market conditions
const currentMarket = analyzeCurrentMarket();
const marketDescription = `
  Market regime: ${currentMarket.regime}, volatility: ${currentMarket.volatility},
  trend strength: ${currentMarket.trend_strength}
`;

const optimalBacktests = mcp__chroma__query_documents({
  collection_name: "backtest_results_sma_crossover",
  query_texts: [marketDescription],
  n_results: 20,
  where: {
    "$and": [
      { "sharpe_ratio": { "$gte": 1.5 } },
      { "max_drawdown": { "$lte": -0.15 } },
      { "symbol": currentMarket.symbol }
    ]
  }
});

// Extract best parameter set
const bestParams = optimalBacktests.metadatas[0][0];

メリット：パラメータの最適化、市場レジームのマッチング、パフォーマンスパターンの発見

---

テンプレート 4：ドキュメントエージェント — スタイルガイドの徹底

課題：API ドキュメントの例を保存し、一貫したスタイルを確保する

// Collection: api_docs_{project_version}
const existingDocs = parseAllApiDocs("./docs/api/");

mcp__chroma__create_collection({
  collection_name: "api_docs_v2",
  metadata: { version: "2.0", total_endpoints: 0 }
});

// Store documentation with style metadata
existingDocs.forEach(doc => {
  mcp__chroma__add_documents({
    collection_name: "api_docs_v2",
    documents: [doc.fullContent],
    ids: [doc.endpoint],
    metadatas: [{
      endpoint: doc.endpoint,
      method: doc.method,
      category: doc.category,
      style_score: doc.styleScore,  // Computed during ingestion
      has_examples: doc.examples.length > 0,
      has_error_codes: doc.errorCodes.length > 0,
      last_updated: doc.lastModified
    }]
  });
});

// New endpoint documented - find similar endpoints for style consistency
const newEndpoint = "POST /api/v2/users/{id}/preferences";

const similarEndpoints = mcp__chroma__query_documents({
  collection_name: "api_docs_v2",
  query_texts: [`${newEndpoint} user preferences update`],
  n_results: 5,
  where: {
    "$and": [
      { "method": "POST" },
      { "style_score": { "$gte": 0.9 } },
      { "has_examples": true }
    ]
  }
});

// Use similar endpoint as template
const template = similarEndpoints.documents[0][0];

メリット：スタイルの一貫性、テンプレートの発見、自動化された品質チェック

---

テンプレート 5：QA テストエージェント — テストパターンライブラリ

課題：テストケースを保存し、抜け漏れを特定して新しいテストを提案する

// Collection: test_cases_{module}
const existingTests = parseTestFiles("./tests/");

mcp__chroma__create_collection({
  collection_name: "test_cases_authentication",
  metadata: { module: "authentication", total_tests: 0 }
});

// Store test cases with coverage metadata
existingTests.forEach(test => {
  mcp__chroma__add_documents({
    collection_name: "test_cases_authentication",
    documents: [`${test.description}. Covers: ${test.coveredScenarios.join(", ")}`],
    ids: [test.id],
    metadatas: [{
      test_type: test.type,  // "unit", "integration", "e2e"
      file_path: test.filePath,
      line_number: test.lineNumber,
      last_run: test.lastRun,
      status: test.lastStatus,
      execution_time_ms: test.executionTime,
      assertions: test.assertionCount
    }]
  });
});

// New feature added - identify missing test coverage
const newFeature = "Password reset with 2FA verification";

const existingCoverage = mcp__chroma__query_documents({
  collection_name: "test_cases_authentication",
  query_texts: [newFeature],
  n_results: 10
});

// If distance > 0.5, probably not covered
const isCovered = existingCoverage.distances[0][0] < 0.5;

if (!isCovered) {
  // Suggest test cases based on similar features
  const similarFeatures = mcp__chroma__query_documents({
    collection_name: "test_cases_authentication",
    query_texts: ["password reset", "2FA verification"],
    n_results: 5
  });

  // Use similar tests as templates
  const testTemplates = similarFeatures.documents[0];
}

メリット：カバレッジの抜け漏れの検出、テストテンプレートの発見、パターンに基づくテスト生成

---

高度なパターン

パターン 1：複数コレクションの集約

ユースケース：関連する複数のコレクションを同時に検索します

// Example: Search all research topics for a cross-cutting concept
const researchCollections = mcp__chroma__list_collections();
const topicCollections = researchCollections.filter(c =>
  c.startsWith("research_literature_")
);

const crossTopicResults = [];
for (const collection of topicCollections) {
  const results = mcp__chroma__query_documents({
    collection_name: collection,
    query_texts: ["transfer learning"],
    n_results: 10
  });

  crossTopicResults.push({
    topic: collection.replace("research_literature_", ""),
    papers: results
  });
}

// Aggregate and rank by relevance across topics
const allPapers = crossTopicResults.flatMap(r =>
  r.papers.ids[0].map((id, idx) => ({
    id: id,
    topic: r.topic,
    distance: r.papers.distances[0][idx],
    metadata: r.papers.metadatas[0][idx]
  }))
);

const rankedPapers = allPapers.sort((a, b) => a.distance - b.distance);

パターン 2：階層型コレクション

ユースケース：コレクション間の親子関係です

// Parent: codebase_architecture_decisions
// Children: codebase_architecture_decisions_{year}

// Create parent collection with aggregated data
mcp__chroma__create_collection({
  collection_name: "codebase_architecture_decisions",
  metadata: { type: "parent", child_collections: [] }
});

// Create child collections by year
[2022, 2023, 2024].forEach(year => {
  mcp__chroma__create_collection({
    collection_name: `codebase_architecture_decisions_${year}`,
    metadata: { type: "child", parent: "codebase_architecture_decisions", year }
  });
});

// Query strategy: Try child first (faster), fallback to parent
const queryYear = 2024;
let results = mcp__chroma__query_documents({
  collection_name: `codebase_architecture_decisions_${queryYear}`,
  query_texts: [query],
  n_results: 10
});

if (results.ids[0].length < 5) {
  // Not enough results in child, query parent
  results = mcp__chroma__query_documents({
    collection_name: "codebase_architecture_decisions",
    query_texts: [query],
    n_results: 10
  });
}

パターン 3：時間減衰

ユースケース：過去のコンテキストを維持しながら、最近の項目を優先します

// Store items with temporal metadata
mcp__chroma__add_documents({
  collection_name: collectionName,
  documents: documents,
  ids: ids,
  metadatas: metadatas.map(m => ({
    ...m,
    timestamp: Date.now(),
    age_days: 0  // Will be updated
  }))
});

// Query with temporal boost
const results = mcp__chroma__query_documents({
  collection_name: collectionName,
  query_texts: [query],
  n_results: 50  // Get more results for re-ranking
});

// Re-rank with temporal decay
const now = Date.now();
const rankedResults = results.ids[0].map((id, idx) => {
  const ageDays = (now - results.metadatas[0][idx].timestamp) / (1000 * 60 * 60 * 24);
  const decayFactor = Math.exp(-ageDays / 30);  // Half-life ~30 days
  const semanticScore = 1 - results.distances[0][idx];
  const combinedScore = semanticScore * 0.7 + decayFactor * 0.3;

  return {
    id: id,
    semantic_score: semanticScore,
    decay_factor: decayFactor,
    combined_score: combinedScore,
    metadata: results.metadatas[0][idx]
  };
}).sort((a, b) => b.combined_score - a.combined_score);

---

パフォーマンスの最適化

バッチ処理戦略

// BAD: One document at a time (slow)
for (const item of items) {
  mcp__chroma__add_documents({
    collection_name: collectionName,
    documents: [item.document],
    ids: [item.id],
    metadatas: [item.metadata]
  });
}

// GOOD: Batch insert (100x faster)
const BATCH_SIZE = 100;
for (let i = 0; i < items.length; i += BATCH_SIZE) {
  const batch = items.slice(i, i + BATCH_SIZE);
  mcp__chroma__add_documents({
    collection_name: collectionName,
    documents: batch.map(item => item.document),
    ids: batch.map(item => item.id),
    metadatas: batch.map(item => item.metadata)
  });
}

キャッシュ戦略

// Check collection exists before creating
const existingCollections = mcp__chroma__list_collections();
if (!existingCollections.includes(collectionName)) {
  mcp__chroma__create_collection({ collection_name: collectionName });
}

// Check document exists before adding
const existing = mcp__chroma__get_documents({
  collection_name: collectionName,
  ids: [documentId]
});

if (!existing.ids || existing.ids.length === 0) {
  // Document doesn't exist, add it
  mcp__chroma__add_documents({ ... });
} else {
  // Document exists, update instead
  mcp__chroma__update_documents({ ... });
}

クエリの最適化

// Use metadata filters to reduce search space
const results = mcp__chroma__query_documents({
  collection_name: collectionName,
  query_texts: [query],
  n_results: 20,
  where: {
    // Pre-filter with metadata (faster than post-filtering semantic results)
    "date": { "$gte": "2024-01-01" },
    "category": { "$in": ["high_priority", "critical"] }
  }
});

// Only include what you need
const minimalResults = mcp__chroma__query_documents({
  collection_name: collectionName,
  query_texts: [query],
  n_results: 10,
  include: ["metadatas", "distances"]  // Exclude documents if not needed
});

---

成功基準

次の条件を満たす場合、ChromaDB の統合は成功です。

• ✅ コレクションの作成：意味のある名前と適切なメタデータを設定します
• ✅ データの取り込み：効率的にバッチ処理し、重複を排除します
• ✅ セマンティック検索の動作：関連性の高い結果を返します（距離 < 0.4）
• ✅ メタデータフィルターの適用：検索範囲を正しく絞り込みます
• ✅ パフォーマンスの最適化：バッチ処理、キャッシュ、最小限のクエリを活用します
• ✅ コレクション横断クエリ：ユースケースに適している場合に実行します
• ✅ 永続的なナレッジ：データがセッションをまたいで保持されます
• ✅ パターンマッチング：類似する過去のケースを特定します
• ✅ トークン制限の解消：コンテキストがあふれることなく、1000 件以上の項目を処理します

---

スキルのバージョン：1.0 作成日：2025-11-14 目的：あらゆる種類のエージェントに対応する、汎用的な ChromaDB 統合パターンを学習させます 目標品質：65/70 依存関係：ChromaDB MCP（mcp__chroma__*） 汎用性：調査、コード、トレーディング、法律、ドキュメント作成、QA、その他すべての分野に対応します

---

🔴 エラー処理と耐障害性（優先度 1）

本番環境で重要：データ損失を防ぎ、障害を適切に処理します

指数バックオフを使用したリトライ

async function retryWithBackoff(operation, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      const delay = Math.pow(2, attempt) * 1000;  // 1s, 2s, 4s
      await sleep(delay);
    }
  }
}

取得または作成のパターン

function getOrCreateCollection(collectionName, metadata = {}) {
  const collections = mcp__chroma__list_collections();

  if (collections.includes(collectionName)) {
    return { created: false, collection_name: collectionName };
  }

  mcp__chroma__create_collection({
    collection_name: collectionName,
    embedding_function_name: "default",
    metadata: metadata
  });

  return { created: true, collection_name: collectionName };
}

ドキュメントの検証

function validateDocument(document, id, metadata) {
  if (!document || typeof document !== 'string') {
    throw new Error(`Document must be non-empty string`);
  }
  if (!id || id.includes(' ')) {
    throw new Error(`ID must be non-empty string without spaces`);
  }
  if (metadata && typeof metadata !== 'object') {
    throw new Error(`Metadata must be object`);
  }
}

詳細なパターン：chromadb-error-handling サブスキルを読み込みます

---

🧪 テストパターン（優先度 1）

品質のために必須：ChromaDB の統合が正しく動作することを確認します

単体テスト（ChromaDB をモック）

// Mock ChromaDB for fast unit tests
class MockChromaDB {
  constructor() {
    this.collections = {};
  }

  create_collection({ collection_name, metadata }) {
    this.collections[collection_name] = {
      documents: [], ids: [], metadatas: [], metadata
    };
  }

  query_documents({ collection_name, query_texts, n_results }) {
    const collection = this.collections[collection_name];
    return {
      ids: [collection.ids.slice(0, n_results)],
      distances: [collection.ids.slice(0, n_results).map(() => 0.2)]
    };
  }
}

統合テスト（実際の ChromaDB）

describe('Semantic Search Integration', () => {
  test('returns relevant documents', async () => {
    await chromaClient.add({
      collection_name: testCollection,
      documents: [
        'Machine learning uses neural networks',
        'Python is a programming language'
      ],
      ids: ['doc1', 'doc2']
    });

    const results = await chromaClient.query({
      collection_name: testCollection,
      query_texts: ['neural networks deep learning'],
      n_results: 2
    });

    expect(results.ids[0]).toContain('doc1');
    expect(results.distances[0][0]).toBeLessThan(0.4);
  });
});

詳細なパターン：chromadb-testing-patterns サブスキルを読み込みます

---

🔐 セキュリティとプライバシー（優先度 2）

コンプライアンスのために重要：PII を保護し、データをサニタイズします

PII の秘匿化

function redactPII(text) {
  let redacted = text;

  // Email redaction
  redacted = redacted.replace(
    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
    '[EMAIL_REDACTED]'
  );

  // Phone redaction
  redacted = redacted.replace(/\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g, '[PHONE_REDACTED]');

  // SSN redaction
  redacted = redacted.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[SSN_REDACTED]');

  return redacted;
}

シークレットのサニタイズ

function redactSecrets(text) {
  let redacted = text;

  // GitHub tokens
  redacted = redacted.replace(/ghp_[a-zA-Z0-9]{36}/g, '[GITHUB_TOKEN]');

  // AWS keys
  redacted = redacted.replace(/AKIA[0-9A-Z]{16}/g, '[AWS_KEY]');

  // API keys
  redacted = redacted.replace(
    /api[_-]?key['\"]?\s*[:=]\s*['\"]?([a-zA-Z0-9_-]{20,})/gi,
    'api_key: [REDACTED]'
  );

  return redacted;
}

アクセス制御

const collectionPermissions = {
  'research_confidential': ['research_team', 'admin'],
  'customer_pii': ['support_team', 'admin']
};

function checkAccess(collectionName, userRole) {
  const allowedRoles = collectionPermissions[collectionName] || ['admin'];

  if (!allowedRoles.includes(userRole)) {
    throw new Error(`Access denied for role '${userRole}'`);
  }
}

詳細なパターン：chromadb-security-patterns サブスキルを読み込みます

---

🗄️ データライフサイクル管理（優先度 2）

本番環境を維持：コレクションをバージョン管理し、古いデータをアーカイブします

スキーマのバージョン管理

// Semantic versioning for collections
function createVersionedCollection(domain, purpose, version = 'v1') {
  const collectionName = `${domain}_${purpose}_${version}`;

  mcp__chroma__create_collection({
    collection_name: collectionName,
    metadata: {
      version: version,
      created_at: new Date().toISOString(),
      schema_version: '1.0',
      retention_days: 730,  // 2 years
      lifecycle_stage: 'active'
    }
  });

  return collectionName;
}

スキーマの移行

async function migrateCollectionSchema(oldCollection, newVersion) {
  const newCollection = `${oldCollection}_v${newVersion}`;

  // Create new collection
  await mcp__chroma__create_collection({
    collection_name: newCollection,
    metadata: { migrated_from: oldCollection, version: newVersion }
  });

  // Copy all documents with transformed metadata
  const allDocs = await mcp__chroma__get_documents({
    collection_name: oldCollection,
    limit: 100000
  });

  const transformedMetadatas = allDocs.metadatas.map(transformMetadata);

  await mcp__chroma__add_documents({
    collection_name: newCollection,
    documents: allDocs.documents,
    ids: allDocs.ids,
    metadatas: transformedMetadatas
  });

  // Mark old as deprecated
  await mcp__chroma__modify_collection({
    collection_name: oldCollection,
    new_metadata: { lifecycle_stage: 'deprecated', replacement: newCollection }
  });
}

保持期間の適用

async function enforceRetentionPolicies() {
  const collections = await mcp__chroma__list_collections();

  for (const collectionName of collections) {
    const info = await mcp__chroma__get_collection_info({ collection_name });
    const retentionDays = info.metadata.retention_days || 730;
    const ageDays = calculateAgeDays(info.metadata.created_at);

    if (ageDays > retentionDays) {
      await archiveCollection(collectionName);  // Backup first
      await mcp__chroma__delete_collection({ collection_name: collectionName });
    }
  }
}

詳細なパターン：chromadb-lifecycle-management サブスキルを読み込みます

---

🐛 デバッグとトラブルシューティング（優先度 1）

よくある問題

問題：結果が返されない

• 原因：距離のしきい値が厳しすぎるか、コレクションが間違っています
• 対処法：しきい値を上げ（0.3 → 0.5）、コレクション名を確認します
• デバッグ：results.distances[0] の値を確認します

問題：セマンティックマッチの精度が低い

• 原因：ドキュメントのチャンク分割が大きすぎるか、小さすぎます
• 対処法：最適なチャンクサイズは 200～500 語です
• デバッグ：ドキュメントの長さを確認し、長いドキュメントを分割します

問題：クエリが遅い

• 原因：メタデータフィルターを使わずに大規模なコレクションを検索しています
• 対処法：メタデータの事前フィルター（where 句）を追加します
• デバッグ：コレクションのサイズを確認し、フィルターを追加します

距離のしきい値ガイド

距離	類似度	ユースケース
< 0.2	ほぼ完全一致	重複の検出
0.2-0.3	非常に類似	高精度検索
0.3-0.5	中程度に類似	バランスの取れた検索
0.5-0.7	わずかに類似	広範な探索
> 0.7	異なるトピック	関連性なし

避けるべきアンチパターン

❌ ファイル全体を単一のドキュメントとして保存する

• 粒度が失われ、検索の関連性が低くなります
• ✅ 対処法：200～500 語のセクションに分割します

❌ 大規模なコレクションでメタデータフィルターを使用しない

• クエリが遅くなり、レイテンシーが増大します
• ✅ 対処法：常に日付、カテゴリ、タイプでフィルタリングします

❌ ドキュメントの重複を排除しない

• ストレージの無駄遣い、重複した結果
• ✅ 対処法：追加する前に存在を確認します

❌ 接続エラーを無視する

• データ損失、サイレントエラー
• ✅ 対処法：再試行ロジックとフォールバックを実装します

---

📚 サブスキルのリファレンス

詳細を確認するには、対象を絞ったサブスキルを読み込みます。

• chromadb-error-handling：再試行パターン、検証、サーキットブレーカー（約150行）
• chromadb-testing-patterns：単体テスト／統合テスト、モック、フィクスチャ（約120行）
• chromadb-security-patterns：PII のマスキング、アクセス制御、GDPR 準拠（約90行）
• chromadb-lifecycle-management：バージョン管理、移行、アーカイブ、保持（約100行）

使用方法：Skill({ skill: "chromadb-error-handling" })

---

更新された成功基準

ChromaDB 統合は、次の条件を満たすと本番環境に対応します。

コア機能（従来）：

• ✅ 意味のある名前でコレクションが作成されている
• ✅ データが効率的に取り込まれている（一括処理）
• ✅ セマンティック検索で関連性の高い結果が返される
• ✅ メタデータフィルターが正しく適用されている
• ✅ パフォーマンスが最適化されている

本番環境への対応（新規）：

• ✅ エラー処理：再試行ロジック、検証、グレースフルデグラデーション
• ✅ テスト：単体テスト（モック使用）、統合テスト（実際の ChromaDB を使用）
• ✅ セキュリティ：PII のマスキング、シークレットのサニタイズ、アクセス制御
• ✅ ライフサイクル：バージョン管理戦略、保持ポリシー、アーカイブ

品質スコア：65/70 → 85/100（すべての拡張を適用した場合）

---

スキルバージョン：2.0 更新日：2025-11-14 拡張内容：エラー処理、テスト、セキュリティ、ライフサイクル管理 品質スコア：85/100（本番環境に対応） 依存関係：ChromaDB MCP (mcp__chroma__*) サブスキル：対象を絞って読み込める4つのモジュール型サブスキル