The agent working regimen: MCP, AGENTS.md and typical scenarios

23 MCP tools, agent modes, the "ask the index, not grep" regimen, and three working scenarios with real call counts.

本文尚未翻译成当前语言——正在显示 English.

The MCP server: 23 tools over stdio #

tools/ragraf-mcp.py is launched by the agent as a child process (JSON-RPC over stdio) and exposes 23 ragraf_* tools: the 22 facade operations + ragraf_list_capabilities (reveals the corpus mode and available operations). Tool arguments mirror the CLI flags; answers are the same envelopes.

Shell

python tools/ragraf-mcp.py \
  --project config/mycorpus.yaml \
  --agent my-agent --agent-kind external

--agent-kind: autoclaw — the author's environment (extended telemetry attribution), external — a third-party agent, internal — internal scenarios. Telemetry (usage_call) records: who, which operation, how many facts/spans/tokens (estimate) — the basis of usage_stats and the panel's Usage tab.

Known tool-filtering gap (documented honestly in the defect register, C-02): the substring tool-name filter can false-positive on similar prefixes — workaround: exact names in agent configs; the fix is on the roadmap.

AGENTS.md: a regimen instead of freedom #

RAGRAF ships a regimen for the agent — not "here are tools, improvise", but a fixed order of work:

Ask the index, not grep. Any navigation starts with ragraf_symbol/ragraf_search, not rg. Full file reads — only via ragraf_live_read and only for a fact found in the index.
Check the envelope, not just result. Non-empty stale_warnings → re-read the affected via live_read; capability=degraded → do not plan tasks requiring slice.
Before any DB write — write_check. Always, no exceptions: 3 ms versus a runtime SQLSTATE[42S22].
impact before an edit. Depth 3, --mode hard for the plan, all when the list of places for manual verification of derived edges is needed.
An honest "not found" is a valid answer. Do not invent; report the envelope's limits.

The full regimen text lives in the repository (AGENTS.md — the README row describes its purpose; as of v0.1.0 the file is marked as not shipped — the divergence is documented in the defect register and closes with the release).

Scenario 1 — a subsystem feature increment (real measurement) #

Task: add payment/contract/vacation journals to the /agreements/ section of the pilot PHP portal. Result per the telemetry journal:

Metric	Value
Operation calls	46 (for the whole increment)
Full file reads	0 (everything — `live_read` on facts found in the index)
Runtime errors	0
`write_check` calls	14 — each one before an SQL write
Defects prevented before code	4
Token savings (estimate)	~5,200 per session vs the grep approach

The dominant class caught: "works, but not the way it should" (8 of 16 pilot defects) — the page opens, no exceptions, yet a rejected document is a dead end: the approval route breaks. Neither a compiler nor a "page opens" test catches that; policy_trace + routes + checks under a real role do.

Scenario 2 — an edit with impact assessment #

Text

1. ragraf_symbol --name PaymentService::markPaid      → definition file:line
2. ragraf_callers --name markPaid --mode hard          → 7 stated calls in 4 files
3. ragraf_callers --mode all                           → +2 derived (call_user_func) — open via live_read
4. ragraf_impact --depth 3                             → transitive cone: 12 symbols
5. ragraf_write_check --table z_agr_payments --columns … → schema agrees
6. edit → ragraf_reindex → drift_report: what changed in the knowledge

Compared with the grep approach: rg markPaid gives 28 matches, of which 9 are calls, and the provably affected set is unknown; the agent reads 3–4 files wholesale (~2,800 tokens) and still misses dynamics. Measured on the pilot's navigation tasks: 14 operation calls vs 28 (realistically 43) grep calls and 0 vs 14 full file reads.

Scenario 3 — incident investigation #

Text

policy_trace --route /agreements/payments/mark-paid   → route→middleware→role check
schema --table z_agr_payments                          → actual columns
table_usage --table z_agr_payments                     → who read/wrote
search "mark payment as paid" --with-text              → the function's docblock contract

Four calls instead of hours of grep archaeology; every answer carries path:line and provenance — usable in an incident report as is.

What telemetry says about the agent's work #

usage_stats (and the panel's Usage tab) shows the distribution across operations: a healthy profile is dominated by symbol/search/write_check with zero whole-file live_grep reads. An anomaly (the agent ignores the index and greps) is visible immediately — a signal to fix the regimen, not the model.