docs: add Coding Standards & Banned Patterns to AGENTS.md

[leoisadev1]

Summary

Adds a prominent Coding Standards & Banned Patterns section to the root AGENTS.md for all AI agents and contributors.

Contents

• Choose Your Bug framing: why useEffect misuse trades one class of bugs for another
• Rules 1–6: ban direct useEffect (use useMountEffect() only where justified), ban as any, derive state without effect sync, use data-fetching libraries instead of fetch-in-effect, use event handlers instead of effect-driven “action flags”, reset via key instead of dependency choreography
• Cross-reference from ANTI-PATTERNS (THIS PROJECT) so the standards are discoverable from the existing policy list

Notes

• Rule 4 references TanStack Query useQuery; Convex and other vetted useQuery-style APIs remain valid under “equivalent data-fetching library” as used elsewhere in the repo.

  

Note

Add Coding Standards & Banned Patterns section to AGENTS.md

Adds a new Coding Standards & Banned Patterns section to AGENTS.md with six explicit rules for AI agents and contributors working in this codebase.

• Bans direct useEffect in favor of useMountEffect for rare external side-effects with required justification
• Bans as any TypeScript casts in favor of proper typing or unknown with narrowing
• Requires deriving state inline or via useMemo rather than syncing with effects
• Requires data-fetching libraries (e.g., useQuery) instead of fetch-in-effect patterns
• Requires user actions to be handled in event handlers, not effect-driven flags; component resets should use React keys
• Updates the existing ANTI-PATTERNS section to reference and enforce these new standards

^{Macroscope summarized 45dc8ca.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
osschat-web	Ignored		Mar 20, 2026 5:16am

[github-actions]

🚀 Preview Deployment Ready

Vercel is rebuilding the frontend with the new Convex backend URL.

Vercel will post the preview URL automatically.

Convex Preview Backend

• Cloud URL: https://elated-peacock-136.convex.cloud
• Site URL: https://elated-peacock-136.convex.site

ℹ️ Preview deployments support email/password auth only (GitHub/Vercel OAuth disabled).

---

_{🤖 Deployed automatically by GitHub Actions}

[cursor]

You have used all of your free Bugbot PR reviews.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[greptile-apps]

Greptile Summary

This PR adds a Coding Standards & Banned Patterns section to the root AGENTS.md, introducing six explicit rules targeting common useEffect misuse patterns and TypeScript as any casts. The intent is sound and well-structured, and the rules align with established React best practices. However, there are two notable issues that reduce the section's usefulness as written:

• useMountEffect is undefined in the codebase — Rule 1 prescribes useMountEffect() as the one approved hook, but a repository-wide search confirms it exists nowhere: no custom hook file, no matching library import. Contributors and AI agents are told to use a hook they cannot import, making Rule 1 unenforceable until the hook is created or the rule is reworded.
• Rule 4 ambiguously excludes Convex's useQuery — The rule attributes useQuery exclusively to TanStack Query, but this project's primary data-fetching mechanism is Convex's reactive useQuery (convex/react). An AI agent reading the rule strictly may flag Convex queries as non-compliant.
• apps/web/AGENTS.md not cross-referenced — The most React-heavy child knowledge base (apps/web/AGENTS.md) was not updated to point to the new standards, reducing discoverability for agents scoped to that workspace.

Confidence Score: 3/5

• Safe to merge after fixing the undefined useMountEffect reference and clarifying Convex useQuery in Rule 4.
• The PR is documentation-only with no runtime risk, but Rule 1 references a hook (useMountEffect) that does not exist in the codebase, making it actively misleading for AI agents that follow these instructions literally. Rule 4 also has an ambiguity that could cause AI agents to incorrectly flag the project's primary data-fetching pattern (Convex's useQuery) as a violation. These are doc-quality issues rather than code breakage, hence a mid-range score rather than 0.
• AGENTS.md — specifically lines 66 (useMountEffect reference) and 78 (Convex useQuery ambiguity).

Important Files Changed

Filename	Overview
AGENTS.md	Adds a "Coding Standards & Banned Patterns" section with 6 React/TypeScript rules; Rule 1 references useMountEffect() which does not exist anywhere in the codebase, and Rule 4's useQuery attribution may ambiguously exclude Convex's useQuery.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Need a side effect or async op?] --> B{What kind?}

    B --> C[SDK / third-party init\non mount only]
    B --> D[Fetch / load server data]
    B --> E[Sync / transform\nexisting state]
    B --> F[React to user action]
    B --> G[Reset component state\nwhen prop changes]

    C --> C1["useMountEffect()\n⚠️ Rule 1 — must be justified\n& documented\n\nNote: useMountEffect not yet\ndefined in codebase"]
    D --> D1["useQuery — TanStack Query\nor Convex useQuery\n✅ Rule 4"]
    E --> E1["Derive inline or useMemo\n✅ Rule 3\n❌ No useEffect + useState"]
    F --> F1["Handle in event handler\n✅ Rule 5\n❌ No effect flag watching"]
    G --> G1["Pass value as key prop\nReact will remount\n✅ Rule 6\n❌ No dep array choreography"]

    style C1 fill:#fff3cd,stroke:#ffc107
    style D1 fill:#d4edda,stroke:#28a745
    style E1 fill:#d4edda,stroke:#28a745
    style F1 fill:#d4edda,stroke:#28a745
    style G1 fill:#d4edda,stroke:#28a745

Loading

_{Last reviewed commit: "docs(AGENTS): add Co..."}

[greptile-apps]

useMountEffect has no defined source or import path

Rule 1 instructs contributors to "Use useMountEffect()", but this hook does not exist in React's core API, and a project-wide search confirms it appears nowhere else in the codebase — no custom hook file, no react-use import, no @react-hookz/web dependency. An AI agent or human contributor following this rule literally has no way to know where to import it from, making the rule unenforceable as written.

You should either:

• Create and export a useMountEffect utility hook (e.g. apps/web/src/hooks/useMountEffect.ts) and reference its import path here, or
• Replace the reference with an existing, well-known alternative like useEffect with [] (alongside a clear explanation of the constraints), or reference a specific library (e.g. useEffectOnce from react-use) that is already in package.json.

Confidence this is correct: 5/5 — confirmed by grep across the entire repository.

[greptile-apps]

Rule 4 ambiguously excludes Convex's useQuery

The rule currently reads: "Use useQuery (TanStack Query) or an equivalent data-fetching library." However, this project's backend is Convex, and practically all server-state queries are performed via Convex's useQuery (imported from convex/react) — not TanStack Query. An AI agent reading this strictly might flag or avoid Convex's useQuery as non-compliant.

The PR description clarifies this intent, but the actual rule text in AGENTS.md does not. Consider making this explicit in the rule itself:

Suggested change

	Do not fetch data inside `useEffect`. Use `useQuery` (TanStack Query) or an equivalent data-fetching library. These libraries handle caching, deduplication, background refetching, loading states, and error states correctly. Effect-based fetching is a manual reimplementation of these features, done worse.
	Do not fetch data inside `useEffect`. Use `useQuery` (TanStack Query), Convex's `useQuery` (`convex/react`), or an equivalent data-fetching library. These libraries handle caching, deduplication, background refetching, loading states, and error states correctly. Effect-based fetching is a manual reimplementation of these features, done worse.

Confidence this is correct: 4/5 — the current wording creates genuine ambiguity for a codebase that relies heavily on Convex's reactive queries.

[greptile-apps]

apps/web/AGENTS.md ANTI-PATTERNS not cross-referenced

The cross-reference to Coding Standards & Banned Patterns was added to the root AGENTS.md's ANTI-PATTERNS section, but apps/web/AGENTS.md — the most relevant child file since it governs all React/UI code — has its own ANTI-PATTERNS section that was not updated. AI agents working exclusively in apps/web/ will load the child AGENTS.md first, and may miss the new coding standards entirely.

Consider adding a pointer in apps/web/AGENTS.md's ANTI-PATTERNS section, e.g.:

- Follow **Coding Standards & Banned Patterns** in root `AGENTS.md` for all React and TypeScript rules (`useEffect` misuse, `as any`, etc.).

Confidence this is correct: 3/5 — the root policy technically applies globally, but discoverability from the child file is meaningfully lower without an explicit reference.