Additional instructions for AGENTS.md focusing on token optimization

A developer introduced a set of guidelines for an AI agent's AGENTS.md file to optimize token usage. The instructions prioritize using a pre-computed AST knowledge graph (graph.json) and the rtk CLI proxy to reduce token consumption by 60-90%. The workflow emphasizes retrieving minimal information, using ast-grep for code searches, and avoiding full directory reads.

Always retrieve the smallest amount of information necessary. Escalate only when necessary. Stop escalating as soon as sufficient information has been obtained. Preferred order: - Need code structure? graph.json . - Need symbols? ast-grep . - Need repository metadata? rtk . - Need implementation? Source files. - Use repository-wide search as last resort Avoid reading entire directories or the whole repository unless explicitly requested. rtk is a CLI proxy that filters and compresses command outputs, saving 60-90% tokens. Use rtk whenever possible because it preserves the relevant information while reducing LLM token consumption. Always prefix shell commands with rtk : Instead of: Use: ls -la rtk ls -la git status rtk git status git log -10 rtk git log -10 docker ps rtk docker ps Other examples where you can use rtk : Other examples where you can use rtk : rtk tree rtk read rtk cat rtk git diff rtk diff rtk npm run test rtk curl <url rtk pytest rtk jest rtk vitest rtk playwright test rtk lint rtk prettier --check . A pre-computed AST knowledge graph graph.json is available at: graphify-out/graph.json Use graph.json before searching or reading multiple source files. Workflow: - Read graph.json . - Identify the relevant symbols, files, and dependency paths. - Read only the source files required for the task. - Avoid scanning unrelated files. Use the graph for: - dependency tracing - call-path discovery - identifying high-centrality modules - impact analysis before refactoring - locating symbol definitions Never read an entire directory simply to locate a symbol. Use graph.json to locate the symbol first, then read only the relevant files. The graph is generated from AST extraction and represents extracted structural relationships only. Treat graph edges as authoritative for structural relationships. Do not infer dependencies that are absent from the graph. Prefer ast-grep over grep whenever searching source code. Use ast-grep for: - locating function definitions - locating class definitions - locating method implementations - finding imports - matching AST patterns - performing structural search Use grep only for: - Markdown - JSON - YAML - log files - generated text - plain-text configuration Avoid using grep to search programming language source code when ast-grep can answer the query.