| name | rate-limit-this |
| description | Audit a JavaScript or TypeScript web app, especially Next.js, for abuse and rate-limit surfaces, ask the human only material policy questions, write a root RATE_LIMITS.md for review, and implement the approved limits in the same context or a fresh agent. Invoke manually to design fair usage policies, choose protections suited to the existing stack, or implement a reviewed rate-limit contract. |
Rate Limit This
Three steps: audit the app and agree on what should and should not be rate
limited, get explicit human approval of the policy, then implement and verify
the approved limits. Write the agreed policy as a durable RATE_LIMITS.md
before changing code.
Read repository instructions such as AGENTS.md or CLAUDE.md, then read
the root RATE_LIMITS.md when it exists. Its status tells you where to resume:
- no spec: start the audit.
draft: present the draft and resolve feedback. Do not implement.approved: implement and verify only the approved policy.done: treat a new invocation as a request to audit or revise the limits.
Only explicit human approval of the whole contract changes status to
approved. Approval of one limiter, silence, or "continue" does not approve the
contract. If repository reality makes an approved decision unsafe or
impossible, stop and reset to draft instead of silently substituting a
different identity, limit, backend, or behavior.
1. Audit and agree on the limits
Read references/detection-playbook.md.
Inspect the request and work-triggering surface, existing authentication,
external services, costly operations, persistence, deployment runtime, and
current limiters. Start with JavaScript/TypeScript and Next.js conventions, but
follow the repository's actual architecture.
Identify candidate limits and explain each in product language: what resource or
experience it protects, who can trigger it, the likely cost or abuse mode,
existing identity and backend, confidence, and remaining policy questions. Rank
candidates. Do not recommend limits for harmless routes merely because they are
public. Complete the audit only after every public write, expensive external
call, security-sensitive action, upload, generation workflow, and background-job
trigger has been recorded as limit, no limit, or defer with a reason.
Ask one question at a time, only when the answer could materially change
protection, user experience, operational risk, or verification. Give one
recommended default based on repository evidence and explain why in one
sentence. Do not make the human choose an algorithm or provider when the
behavior and existing stack determine it. If no material gaps remain, draft
without inventing questions.
Translate answers into algorithms and infrastructure, resolving: allowance and
window; whether short bursts are acceptable; identity (authenticated user,
account, hashed API identity, IP, or an approved combination); paid, anonymous,
admin, internal, and BYOK exemptions; global cost circuit breakers; the
blocked-user experience; backend outage behavior; and Simple or Thorough
verification. Offer browser fingerprinting only as advanced opt-in after ordinary
server-verified identities are insufficient, explain its privacy and spoofing
tradeoffs, and require explicit approval. Never use it as sole protection and
never store a raw API key as an identifier.
Read references/spec-template.md. Create or
update one root-level RATE_LIMITS.md; do not create a competing JSON or YAML
spec. Give every limiter a stable ID. Set status: draft. Present the draft,
call out recommendations and open questions, and stop. Application code,
dependencies, schemas, external resources, credentials, and deployment
configuration must remain unchanged.
2. Approve the policy
Only explicit human approval of the whole current contract changes status to
approved. Before recording approval, require an empty Open questions
section and record who approved and when. Increment the revision whenever a
shared draft's policy changes.
3. Implement and verify the approved limits
Read references/provider-routing.md. Choose
one suitable primary enforcement backend or platform control based on the
existing stack. Verify current official provider documentation before changing
dependencies, schemas, or platform configuration.
By default, implement in the same context after re-reading the approved
RATE_LIMITS.md. For sensitive apps, you may instead route implementation to a
fresh subagent whose prompt explicitly identifies it as the implementation agent
for the approved contract, giving it the approved RATE_LIMITS.md, repository
instructions, and codebase, not the planning conversation. If the host cannot
create subagents and the human wants the fresh-agent path, stop and ask them to
begin a fresh implementation task with that explicit role and the approved
contract. Creating an account, database, credential, OAuth grant, or deployment
secret requires action-time human confirmation even when the provider is
approved in the spec.
Guardrails while implementing: enforce at the shared boundary so a second route
cannot bypass the policy; keep check-and-consume atomic; hash or map raw API
keys, tokens, and emails, never use them as identifiers or in keys; include a
namespace per application and action; make retries and multi-step workflows
consume exactly what the approved counting point says; and define backend
outage behavior explicitly.
Use the verification depth approved in the spec.
- Simple: reuse existing checks and perform a focused smoke check showing
allowed traffic, the blocked request, and the expected recovery/reset path.
Add a small test only when the repository already has a suitable seam.
- Thorough: extend existing automated tests for identities, exemptions,
headers, reset behavior, and backend failure modes, plus a safe provider
smoke test when credentials exist.
When the contract says malformed requests do not consume capacity, validate
required fields and types before admission. Successful JSON parsing alone does
not make a request valid. Test valid JSON with an invalid shape as well as JSON
parse failures. Do not introduce a test framework solely for rate limiting.
Document checks that could not run rather than pretending they passed.
When implementation and verification are complete, set status: done, present
the diff, verification evidence, deviations, and remaining operational steps,
and stop before merge, deployment, publication, or announcement unless the
human explicitly asks for that action after reviewing the output.
For the optional strict four-state contract with revision metadata and a
mandatory fresh-agent handoff, see
references/contract-states.md.
