qe-code-intelligence

QE コードインテリジェンス

目的

知識グラフの構築、セマンティックコード検索、依存関係マッピング、コンテキストを考慮したコード理解など、トークンを大幅に削減できる v3 のコードインテリジェンス機能の使用方法を説明します。

有効化

• 不慣れなコードを理解するとき
• コードをセマンティック検索するとき
• 依存関係を分析するとき
• コードの知識グラフを構築するとき
• AI 操作でコンテキストを削減するとき

クイックスタート

# Index codebase into knowledge graph
aqe code index src/ --incremental

# Semantic code search
aqe code search "authentication middleware"

# Analyze change impact
aqe code impact src/services/UserService.ts --depth 3

# Map dependencies
aqe code deps src/

# Analyze complexity and find hotspots
aqe code complexity src/

# Generate C4 architecture diagrams (Mermaid) with a confidence score
aqe code c4 .

エージェントのワークフロー

// Build knowledge graph
Task("Index codebase", `
  Build knowledge graph for the project:
  - Parse all TypeScript files in src/
  - Extract entities (classes, functions, types)
  - Map relationships (imports, calls, inheritance)
  - Generate embeddings for semantic search
  Store in AgentDB vector database.
`, "qe-kg-builder")

// Semantic search
Task("Find relevant code", `
  Search for code related to "user authentication flow":
  - Use semantic similarity (not just keyword)
  - Include related functions and types
  - Rank by relevance score
  - Return with minimal context (80% token reduction)
`, "qe-code-intelligence")

知識グラフの操作

1. コードベースのインデックス作成

await knowledgeGraph.index({
  source: 'src/**/*.ts',
  extraction: {
    entities: ['class', 'function', 'interface', 'type', 'variable'],
    relationships: ['imports', 'calls', 'extends', 'implements', 'uses'],
    metadata: ['jsdoc', 'complexity', 'lines']
  },
  embeddings: {
    model: 'code-embedding',
    dimensions: 384,
    normalize: true
  },
  incremental: true  // Only index changed files
});

2. セマンティック検索

await semanticSearcher.search({
  query: 'payment processing with stripe',
  options: {
    similarity: 'cosine',
    threshold: 0.7,
    limit: 20,
    includeContext: true
  },
  filters: {
    fileTypes: ['.ts', '.tsx'],
    excludePaths: ['node_modules', 'dist']
  }
});

3. 依存関係の分析

await dependencyMapper.analyze({
  entry: 'src/services/OrderService.ts',
  depth: 3,
  direction: 'both',  // imports and importedBy
  output: {
    graph: true,
    metrics: {
      afferentCoupling: true,
      efferentCoupling: true,
      instability: true
    }
  }
});

トークン削減戦略

// Get context with 80% token reduction
const context = await codeIntelligence.getOptimizedContext({
  query: 'implement user registration',
  budget: 4000,  // max tokens
  strategy: {
    relevanceRanking: true,
    summarization: true,
    codeCompression: true,
    deduplication: true
  },
  include: {
    signatures: true,
    implementations: 'relevant-only',
    comments: 'essential',
    examples: 'top-3'
  }
});

知識グラフのスキーマ

interface KnowledgeGraph {
  entities: {
    id: string;
    type: 'class' | 'function' | 'interface' | 'type' | 'file';
    name: string;
    file: string;
    line: number;
    embedding: number[];
    metadata: Record<string, any>;
  }[];
  relationships: {
    source: string;
    target: string;
    type: 'imports' | 'calls' | 'extends' | 'implements' | 'uses';
    weight: number;
  }[];
  indexes: {
    byName: Map<string, string[]>;
    byFile: Map<string, string[]>;
    byType: Map<string, string[]>;
  };
}

検索結果

interface SearchResult {
  entity: {
    name: string;
    type: string;
    file: string;
    line: number;
  };
  relevance: number;
  snippet: string;
  context: {
    before: string[];
    after: string[];
    related: string[];
  };
  explanation: string;
}

CLI の例

# Full reindex
aqe code index src/

# Incremental index (changed files only)
aqe code index src/ --incremental

# Index only files changed since a git ref
aqe code index . --git-since HEAD~5

# Semantic code search
aqe code search "database connection"

# Change impact analysis
aqe code impact src/services/UserService.ts

# Dependency mapping
aqe code deps src/ --depth 5

# Complexity metrics and hotspots
aqe code complexity src/ --format json

注意事項

• 警告：code-intelligence ドメインの成功率は 18% です。単純なクエリでは、エージェントベースのコード検索よりも直接 grep/glob を使うことをおすすめします
• 5 万 LOC を超えるリポジトリでは知識グラフの構築に失敗します。特定のモジュールに範囲を絞ってください
• ドメイン固有の埋め込みがない場合、セマンティック検索は無関係な結果を返します。検索結果は必ず手動で確認してください
• エージェントは「トークンを 80% 削減」と主張しますが、重要なコンテキストが省略される場合があります。主要なファイルが結果に含まれていることを確認してください
• 使用前に Fleet を初期化する必要があります。aqe health を実行して診断するか、初期化エラーが発生した場合は aqe init を実行して再初期化してください

連携

主要なエージェント：qe-kg-builder、qe-dependency-mapper、qe-impact-analyzer、qe-code-complexity コーディネーター：qe-code-intelligence 関連スキル：qe-test-generation、qe-defect-intelligence