Skip to content

AGENTS.md

Latest commit

 

History

History
81 lines (64 loc) · 5.17 KB

AGENTS.md

File metadata and controls

81 lines (64 loc) · 5.17 KB
Raw

Code Exploration Policy

Always use jCodemunch-MCP tools for code navigation. Never fall back to Read, Grep, Glob, or Bash for code exploration. Exception: Use Read when you need to edit a file — the agent harness requires a Read before Edit/Write will succeed. Use jCodemunch tools to find and understand code, then Read only the specific file you're about to modify.

Start any session:

  1. resolve_repo { "path": "." } — confirm the project is indexed. If not: index_folder { "path": "." }
  2. suggest_queries — when the repo is unfamiliar

Finding code:

  • symbol by name → search_symbols (add kind=, language=, file_pattern=, decorator= to narrow)
  • decorator-aware queries → search_symbols(decorator="X") to find symbols with a specific decorator (e.g. @property, @route); combine with set-difference to find symbols lacking a decorator (e.g. "which endpoints lack CSRF protection?")
  • string, comment, config value → search_text (supports regex, context_lines)
  • database columns (dbt/SQLMesh) → search_columns

Reading code:

  • before opening any file → get_file_outline first
  • one or more symbols → get_symbol_source (single ID → flat object; array → batch)
  • symbol + its imports → get_context_bundle
  • specific line range only → get_file_content (last resort)

Repo structure:

  • get_repo_outline → dirs, languages, symbol counts
  • get_file_tree → file layout, filter with path_prefix

Relationships & impact:

  • what imports this file → find_importers
  • where is this name used → find_references
  • is this identifier used anywhere → check_references
  • file dependency graph → get_dependency_graph
  • what breaks if I change X → get_blast_radius
  • what symbols actually changed since last commit → get_changed_symbols
  • find unreachable/dead code → find_dead_code
  • class hierarchy → get_class_hierarchy

Session-Aware Routing

Opening move for any task:

  1. plan_turn { "repo": "...", "query": "your task description", "model": "<your-model-id>" } — get confidence + recommended files; the model parameter narrows the exposed tool list to match your capabilities at zero extra requests.
  2. Obey the confidence level:
    • high → go directly to recommended symbols, max 2 supplementary reads
    • medium → explore recommended files, max 5 supplementary reads
    • low → the feature likely doesn't exist. Report the gap to the user. Do NOT search further hoping to find it.

Interpreting search results:

  • If search_symbols returns negative_evidence with verdict: "no_implementation_found":
    • Do NOT re-search with different terms hoping to find it
    • Do NOT assume a related file (e.g. auth middleware) implements the missing feature (e.g. CSRF)
    • DO report: "No existing implementation found for X. This would need to be created."
    • DO check related_existing files — they show what's nearby, not what exists
  • If verdict: "low_confidence_matches": examine the matches critically before assuming they implement the feature

After editing files:

  • If PostToolUse hooks are installed (Claude Code only), edited files are auto-reindexed
  • Otherwise, call register_edit with edited file paths to invalidate caches and keep the index fresh
  • For bulk edits (5+ files), always use register_edit with all paths to batch-invalidate

Token efficiency:

  • If _meta contains budget_warning: stop exploring and work with what you have
  • If auto_compacted: true appears: results were automatically compressed due to turn budget
  • Use get_session_context to check what you've already read — avoid re-reading the same files

Reading the response envelope (v1.74.0+):

  • _meta.confidence (0–1) — calibrated retrieval-quality score on search_symbols / plan_turn / get_ranked_context. ≥ 0.8 → trust the top result; ≤ 0.4 → widen the search or report a gap
  • _meta.freshness — {fresh, edited_uncommitted, stale_index} counts plus repo_is_stale flag. Per-result _freshness field on each symbol entry
  • If repo_is_stale=true, suggest index_folder before claiming current behaviour
  • For latency / cache health: analyze_perf (in-memory by default; window=1h|24h|7d|all reads ~/.code-index/telemetry.db when perf_telemetry_enabled is on)
  • After a representative workload on a new repo, run tune_weights to learn per-repo retrieval weights from the ranking ledger

Model-Driven Tool Tiering

Your jcodemunch-mcp server narrows the exposed tool list based on the model you are running as. To avoid wasting requests on primitives when a composite would do, always include model="<your-model-id>" in your opening plan_turn call.

Replace <your-model-id> with your active model:

  • Claude Opus variants → claude-opus-4-7 (or any claude-opus-*)
  • Claude Sonnet variants → claude-sonnet-4-6
  • Claude Haiku variants → claude-haiku-4-5
  • GPT-4o / GPT-5 / o1 / Llama → use the model id as printed by your runner

The model= parameter rides on the existing plan_turn call — it does not add a separate tool invocation. If plan_turn is not appropriate for a non-code task, call announce_model(model="...") once instead.