[Rule]: ai-agent-specialist.mdc

[vinniefalco]

Request type

New Cursor rule

Existing rule path or proposed topic

rules/ai-agent-specialist.mdc

Cursor workflow this improves

I'm generally disappointed with the quality of the rules in this repository. The basic instruction, "are these clear, unambiguous rules or are they aspirational?" was never performed. For example this is what is said about ai-agent-specialist.mdc and it is the first and last file I tried:

Proposed rule content or expected change

Mixed. Some are hard rules, some are aspirational. Here's the breakdown:

Genuinely clear and enforceable

• Never use any - binary, lintable
• Naming conventions - well-defined, lintable
• React Query / Zustand / No Redux - binary technology choice
• Never call ORM directly from business logic - clear boundary
• Validate all input with Zod at API boundaries - specific tool, specific location
• Max 400 lines per PR - measurable threshold
• Conventional commits - references an external spec
• Use factory functions for test data - clear pattern
• Structured logging with Winston - specific tool choice

Aspirational or ambiguous

Rule	Problem
Max 20 lines per function	Does this include blank lines? Signatures? Closing braces? A formatter could disagree with a reviewer.
"Prefer interfaces over type aliases"	"Prefer" is not a rule. When is the exception? Discriminated unions? Mapped types?
"Clean Architecture with dependency inversion"	A philosophy, not a constraint. Doesn't define layer boundaries or what "framework-agnostic" means in practice.
"Throw for exceptional, return Result for expected"	The boundary between exceptional and expected is subjective. A 404 - exceptional or expected?
"80% unit coverage, 100% critical paths"	80% is measurable. "Critical paths" is undefined - who decides?
"Mock only external dependencies"	What about a service that wraps three other internal services? Is that "internal logic"?
"Never log sensitive data (passwords, tokens, PII)"	The parenthetical helps but PII is a spectrum. Is a user ID PII? An email?
"Rate limit all public endpoints"	At what threshold? 100/min? 10/sec? Per-user or global?

What would make the aspirational ones enforceable

Turn "prefer X" into "use X unless Y." Turn philosophies into file-structure constraints. Turn coverage goals into CI gates with explicit path globs. Example rewrites:

- Use interfaces for object shapes. Use type aliases only for unions, intersections, or mapped types.
- Domain layer lives in src/domain/. It may not import from src/infra/ or src/api/.
- "Expected failure" = any error the caller is designed to handle (validation, not-found, conflict). Everything else throws.
- Rate limit: 100 req/min per authenticated user, 20 req/min per IP for unauthenticated.

Verdict: About 60% hard rules, 40% aspirational. The aspirational ones aren't bad guidance - they just won't produce consistent AI behavior because there's room for interpretation. If the goal is to constrain an AI agent, tighten the ambiguous ones into if/then boundaries. Confidence: high - the distinction between "testable constraint" and "good advice" is structural.

Scope acknowledgement

• I am not asking for third-party tool support, account sharing, or license bypass help.