Skip to main content

Development Rules

Naming​

  • Use explicit names that describe the owning domain or responsibility.
  • Avoid generic filenames such as utils.ts, data.ts, myFunctions.ts, or server.ts for real product logic.
  • Prefer names such as access.ts, directory.ts, profile.ts, billing.ts, or supportHandoff.ts.

Route Ownership​

  • Keep route files thin.
  • Keep the page body in page.tsx by default.
  • Keep supporting route-local code under the owning route tree in _components/*, _hooks/*, and _lib/*.
  • Promote code into app-shared folders only when reuse across surfaces is proven.

Surface Boundaries​

  • apps/app owns authenticated product surfaces: org, portal, and platform.
  • apps/marketing owns optional public marketing pages.
  • Different surfaces may intentionally diverge in layout, navigation, theming, density, and UX.
  • Do not flatten those differences into a forced shared structure.

Imports​

  • Use @/ for cross-boundary imports inside apps/app.
  • Use relative imports only for tightly-coupled local files.
  • Do not deep-import another route tree's private internals.
  • Do not use long relative climbs across boundaries.

Convex​

  • Author all backend modules in packages/backend/convex/**.
  • Use @convex/* only from app-side code that consumes generated backend references.
  • apps/app/convex is generated-only and must not become a second backend root.
  • Keep runtime-global Convex root files limited to auth.ts, auth.config.ts, http.ts, crons.ts, and schema.ts.

Shared Code​

  • Start app-local.
  • Promote to packages/* only when reuse is real or the module is clearly repo-wide infrastructure.
  • Use the rule of two for DRY extraction: extract only after duplication exists in active code.

Directory Hygiene​

  • Remove empty folders that no longer carry active responsibility.
  • Keep shared folders small and intentional.
  • Do not leave archived client docs in the live starter folders.

Documentation​

  • docs/app/README.md is the app-docs entrypoint.
  • docs/dev/README.md is the developer-docs entrypoint.
  • docs/app should teach the starter kit, not a client implementation.
  • Client-specific material belongs under docs/app/archive/*.
  • When docs move, update references in the same change.
  • When instructions change under .__ai-rules/*, run pnpm sync:agents in the same change.