faq_usage

A quick reference for choosing between DESIGN_FAQ.md and DX_FAQ.md in an entity-component-system codebase. One explains why the system was designed a certain way, while the other explains how to use its programming interface.

In plain words
What is it for?
Use it when deciding where to document or find explanations about design choices, performance trade-offs, internal behavior, systems, entities, queries, and schedules.
Why use it?
It prevents developers from looking in the wrong document when they need architectural reasoning or usage instructions.

Cursor rule for Cursor

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add rules/arenukvern/mcp_flutter/faq_usage
Clone the repo
git clone --depth 1 https://github.com/Arenukvern/mcp_flutter

Made for: Cursor.

Per session 430 This file is loaded in full into every session.
When invoked 430 The same file — it is already loaded in full.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00430 $0.00430
Opus 5 $0.00215 $0.00215
Sonnet 5 $0.00086 $0.00086
Haiku 4.5 $0.00043 $0.00043

Measured 2d ago against content hash e25096d5f8a8, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

faq_usage scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.cursor/rules/faq_usage.mdc · 39 lines

What it actually says

FAQ Documentation Usage Guide

Quick reference for when to use DESIGN_FAQ.md vs DX_FAQ.md.

Q: What is DESIGN_FAQ.md for? A: Explains WHY design decisions were made. Use when maintaining the ECS codebase, understanding architectural choices, or making changes that affect core systems. Answers questions like "Why do we use archetypes?" or "Why is flush order important?"

Q: What is DX_FAQ.md for? A: Explains HOW to use the ECS API. Use when writing application code, creating systems, or learning the API. Answers questions like "How do I query entities?" or "How do I create a schedule?"

Q: What format should DX_FAQ.md use? A: Memory Palace Format - Spatial organization with mental "locations" (🏠 World Hub, 🏭 Entity Factory, etc.) containing embedded code patterns. This format is optimized for AI agent memory retention through spatial associations and instant recall.

Q: When should I reference DESIGN_FAQ.md? A: When you need to understand:

  • Architectural rationale (why archetypes, why SoA, why generational IDs)
  • Performance trade-offs (why auto-flush, why column abstraction)
  • Internal design decisions (why flush order, why command queue)
  • Making changes to core ECS systems

Q: When should I reference DX_FAQ.md? A: When you need to know:

  • How to use the API (queries, schedules, entity access)
  • Code examples for common tasks
  • Practical usage patterns
  • Writing application code (not maintaining ECS itself)

Q: Can I use both FAQs together? A: Yes. DESIGN_FAQ explains why WorldEntity vs WorldEntityMut exist, while DX_FAQ shows how to use them. They complement each other - no duplication.

Q: Which FAQ should I update? A: Update DESIGN_FAQ.md when making architectural changes or design decisions. Update DX_FAQ.md when adding new API features or improving developer experience examples.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 39 lines · 430 tokens per session scan A e25096d5f8a8

Subscribe to this mod's changes

faq_usage is a cursor rule published in the GitHub repository Arenukvern/mcp_flutter (372 stars, last pushed 7d ago), licensed MIT. It adds 430 tokens to every session, about $0.0022 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.