[infra] agentic tool-use and token-efficiency guidance

[pq]

Using the estimate-conversation-tokens tool I've been noodling on, Gemini did some analysis and came up with some opportunities for improvement. The analysis is below but the TL;DR is with a little guidance we might enjoy something like a 60% to 80% reduction in total token consumption per session and get better results generally by making sure we're leveraging "smarter" tools such as the Dart MCP Server.

See: #503 .

---

📊 Agentic Token Efficiency & Savings Analysis

To make agentic programming in this repository as cost-effective and responsive as possible, we have analyzed the token overhead in our development sessions using the estimate-conversation-tokens tool.

The Context Overhead Problem (Our Baseline)

In a typical long-running session (spanning ~395 model invocations), the total token footprint can exceed 27 Million tokens (without caching).

• System & History Overhead: Accounts for 95.3% of all tokens consumed.
• Why? Any large file dump or command output read by the agent gets stored in the conversation history and re-sent to the model on every subsequent turn.

---

Estimated Savings from Proposed Optimizations

Optimization	Traditional Pattern	Proposed Pattern	Estimated Token Savings
Line-by-Line File Views	Reading a whole 1,000-line file (~10,000 tokens)	Targeted view_file with StartLine/EndLine (~200 tokens)	99.2%
Domain MCP Tools vs Shell	Running ./gradlew build or flutter analyze to check types (~20,000 tokens of logs)	Static check via analyze_files / lsp MCP tools (~500 tokens of clean JSON)	97.5%
Research Subagents	Performing codebase scans and multiple file reads directly in the main conversation history	Spawning a research subagent and returning a concise summary	99.3%

Expected Impact

By implementing strict ignore_patterns (to filter build cache and IDE garbage files), enforcing line limits on file reads, and prioritizing language-server MCP tools over subprocess runs, we project a 60% to 80% reduction in total token consumption per session, while keeping the agent's context window highly stable.

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our [contributor guide](https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Dart contributions to our repos should follow the Dart style guide and use dart format.
• Java and Kotlin contributions should strive to follow Java and Kotlin best practices (discussion).

[gemini-code-assist]

Code Review

This pull request adds configuration files for AI coding assistants, including custom rules in .agents/AGENTS.md, ignore patterns in .geminiignore and .claudeignore, and updates to .gitignore for IDE, Gradle, and Dart/Flutter files. Feedback was provided on .claudeignore because simply listing .geminiignore inside it does not inherit the ignore patterns; the patterns should be copied directly to prevent token bloat.