AlexandrAI AGENTS.md
agents-md

FileGraph Analyzer Fallback Agent Guide

Agent guide for FileGraph Claude CLI analysis, taxonomy guardrails, and heuristic fallback.

AGENTS.md

Guidance for coding agents working on FileGraph Analyzer Fallback in the FileGraph project.

Project overview

This guide covers src/lib/filegraph/analyzer.ts. The analyzer builds a JSON-only prompt, constrains outputs to known candidates and generated taxonomy, calls the local Claude CLI when available, and falls back to deterministic heuristics when the primary analyzer fails. FileGraphService consumes the analyzer through the FileGraphAnalyzer interface.

Primary source files

  • src/lib/filegraph/analyzer.ts defines buildNoteAnalysisPrompt, ClaudeCliAnalyzer, HeuristicAnalyzer, FallbackAnalyzer, and createDefaultAnalyzer.
  • src/lib/filegraph/service.ts builds AnalyzeNoteInput with lexical, same-space, and hinted parent candidates.
  • src/lib/filegraph/types.ts defines AnalyzeNoteInput, AnalyzeNoteResult, CommunitySummaryResult, and relation proposals.
  • src/lib/filegraph/analyzer.test.ts verifies prompt guardrails and taxonomy-constrained heuristic output.
  • src/lib/filegraph/service-instance.ts wires createDefaultAnalyzer into the singleton service.

Setup commands

pnpm install pnpm test pnpm lint pnpm build pnpm dev

Change rules

  • Keep prompts JSON-only and continue telling the model not to reference note ids outside the candidate set.
  • Keep relation limits conservative: parent, child, and related arrays should stay bounded so graph artifacts remain readable.
  • Choose tags, entity types, community hints, and community labels from the generated taxonomy whenever possible.
  • Keep HeuristicAnalyzer deterministic and dependency-light; it is the local fallback when CLI analysis is unavailable.
  • Do not let ClaudeCliAnalyzer become required for tests or for basic local editing.
  • Preserve extractStructuredOutput support for nested result, response, content, message, and raw text shapes.
  • Resolve relation proposals in the service after analysis so invalid note ids are filtered before persistence.
  • When changing analyzer output shape, update zod schema, types, prompt text, heuristic output, and tests in one change.

Testing

Test prompt content, candidate guardrails, taxonomy filtering, fallback behavior after primary failure, structured output extraction shapes, invalid relation filtering through service, and community summary fallback. Prefer fake analyzers for service tests so queue behavior stays deterministic.

PR checklist

  • analyzer.test.ts passes.
  • Service tests pass without a real CLI analyzer.
  • Fallback output never invents unsupported taxonomy values when allowed values exist.
  • Graph relations only reference known notes.