agentleFS
Sign inStart free
narenaryannarenaryan/agent-skills/skills/engineering/ai-bug-patterns/SKILL.md

ai-bug-patterns

Skill0 starsChanged 39 days agoMITView on GitHub

Use when writing or reviewing AI-assisted code, PRs, tests, or QA plans that may fail silently - turns common AI-generated bug clusters into checks for broken auth, race conditions, stale state, validation drift, idempotency, swallowed errors, and incomplete refactors

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when AI-assisted code passes happy-path tests but could be silently wrong.

    line 8
  2. Distinctive:

    Check whether omission fails closed.

    line 18
  3. Distinctive:

    Ask for pre-production evidence: negative, cross-tenant, concurrent, retry, cache-invalidation, or startup checks.

    line 20
  4. Distinctive:

    Prefer designs where omission fails loudly:

    line 46
  5. Distinctive:

    Use database constraints, transactions, unique keys, and idempotency keys.

    line 50
  6. Distinctive:

    Treat caches and derived state as dependencies with owners and invalidators.

    line 51

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

AI Bug Patterns

Use this skill when AI-assisted code passes happy-path tests but could be silently wrong. These bugs return clean responses with the wrong access, state, timing, or data source.

Working rule

Review the negative space, not just the feature path:

  1. Name who must be denied, what state must stay synchronized, and which operations must be atomic, cancel-safe, or idempotent.
  2. Check whether omission fails closed. Missing auth, scope, config, or validation should block work, not allow it.
  3. Ask for pre-production evidence: negative, cross-tenant, concurrent, retry, cache-invalidation, or startup checks.

Scan these clusters

ClusterAsk
Authorization, access control, query scope, credentials, tokensCan one user, tenant, org, role, or token see or mutate another context's data? Is scope enforced at the backend boundary?
TOCTOU, partial updates, async completion, cancellation, non-atomic operationsCan state change between check and use? Can a late response, failed second step, or cancellation leave inconsistent state?
Webhook, retry, dedup, and idempotency failuresCan duplicate delivery or retry charge, send, grant, import, or mutate twice? Is uniqueness enforced by storage?
Stale derived state, stale cache, unsynced code paths, inconsistent data sourceAfter a mutation, do API, worker, admin, UI, cache, and reporting paths agree on the source of truth?
Startup/config validation, input validation, validation drift, fuzzy matching, boundary errorsCan bad config boot? Can one path accept what another rejects? Are limits, rounding, normalization, and matching explicit?
Swallowed errors, incomplete refactors, stale constants, null dereferences, UI/accessibility gapsDoes failure become success, empty data, wrong status, unreachable UI, or old behavior that survived a rename?

Evidence to request

  • Auth: denied-user, cross-tenant, wrong-audience, expired-token, and missing-scope tests.
  • Races: transaction, rollback, out-of-order completion, and replay-the-same- event-twice tests.
  • State: mutate, then read through every cache, derived state, and data source.
  • Validation/refactor: fails-fast startup, boundary inputs, shared validator, and old-name search evidence.

Make bugs legible

Prefer designs where omission fails loudly:

  • Deny by default; require explicit grants.
  • Centralize scope filters and validation at trust boundaries.
  • Use database constraints, transactions, unique keys, and idempotency keys.
  • Treat caches and derived state as dependencies with owners and invalidators.
  • Log and propagate unexpected errors; ignore only named, safe cases.

Pitfalls

  • Reviewing only the generated diff; inspect adjacent endpoints, jobs, and alternate callers that share the invariant.
  • Accepting a passing happy-path test as evidence for authorization, retries, concurrency, or cache behavior.
  • Treating null dereferences as the main AI risk. They are visible; silent access, race, state, and validation bugs are more likely to escape.

Source: Detail blog.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free