adilallo
92 lines
4.0 KiB
Markdown
92 lines
4.0 KiB
Markdown
# Agent guide
|
|
|
|
Orientation for AI coding agents working in this repo. Per-file conventions
|
|
live in `.cursor/rules/*.mdc` (auto-loaded by Cursor; other agents should
|
|
read them on demand). This file is the **map** — load it first, then load
|
|
the rule(s) matching the file you're editing.
|
|
|
|
## What this is
|
|
|
|
Next.js 16 / React 19 app for community decision-making and governance.
|
|
Single-locale (English) today; designed for i18n via `messages/`.
|
|
|
|
## Read before editing
|
|
|
|
| If you're touching… | Load this rule |
|
|
| --- | --- |
|
|
| `app/components/**` | `component-structure.mdc`, `component-props.mdc`, `tailwind-styling.mdc` |
|
|
| `Alert`, or user-visible notifications / shell errors / success banners | `alerts.mdc` (and `localization.mdc` for copy) |
|
|
| `app/(app)/create/**` | `create-flow.mdc` (+ component rules) |
|
|
| `app/api/**` | `api-routes.mdc` |
|
|
| `app/hooks/**` | `hooks.mdc` |
|
|
| `app/**/page.tsx` or `app/**/layout.tsx` | `routes.mdc` |
|
|
| `messages/**` or any user-visible string | `localization.mdc` |
|
|
| `tests/**` | `testing.mdc` |
|
|
| `stories/**` | `storybook.mdc` |
|
|
|
|
When in doubt about file structure or naming, the rules win over your
|
|
priors — they reflect deliberate decisions.
|
|
|
|
## Cross-cutting principles (no single rule owns these)
|
|
|
|
1. **Figma is the source of truth for design.** Container files carry a
|
|
`Figma: "<Path>" (<node-id>)` docstring; views render Figma intent.
|
|
Codebase naming uses lowercase conventions (see `component-props.mdc`)
|
|
even when Figma uses PascalCase enum values.
|
|
2. **Container / view split is the component pattern.** Never put state
|
|
or side effects in a `*.view.tsx`. Hooks belong in containers.
|
|
3. **All user-visible text lives in `messages/`.** Hardcoded strings in
|
|
components are a bug — even for placeholders.
|
|
4. **Tests live in `tests/`, not co-located.** Mirror the source path
|
|
(`app/components/Foo` → `tests/components/Foo.test.tsx`).
|
|
5. **Routes live inside groups** — `(marketing)`, `(app)`, `(admin)`,
|
|
`(dev)`. Don't drop a new route folder loose at the top of `app/`.
|
|
**Admin-only widgets** may live in **`app/(admin)/<route>/_components/`**
|
|
when only that route uses them (e.g. **`WebVitalsDashboard`** on **`/monitor`**).
|
|
6. **No new pathname-sniffing chrome.** Compose chrome via group/nested
|
|
layouts, not `usePathname()` checks. (`ConditionalNavigation` is the
|
|
sole tolerated exception — it carries SSR session state.)
|
|
|
|
## Legacy / scaffolding
|
|
|
|
Some code exists temporarily while backend services are stood up:
|
|
|
|
- `NEXT_PUBLIC_ENABLE_BACKEND_SYNC` gating
|
|
- `migrateLegacyCreateFlowState`, `LEGACY_LIVE_KEY`, `LEGACY_DRAFT_KEY`
|
|
- `/create/right-rail` redirect
|
|
- `docs/guides/backend-roadmap.md`, `backend-linear-tickets.md`,
|
|
`template-recommendation-matrix.md`
|
|
|
|
**Do not delete** without an explicit ask. Do not add new code in this
|
|
shape — when adding scaffolding, leave a `// TODO(legacy): …` with the
|
|
removal trigger.
|
|
|
|
## Verification recipe
|
|
|
|
Run these (in order) before declaring a change done:
|
|
|
|
```bash
|
|
rm -rf .next # only if you moved/renamed routes or layouts
|
|
npx tsc --noEmit # type check
|
|
npm run knip # unused files / exports (local; no remote CI)
|
|
npx vitest run # unit + component (~185 test files)
|
|
npx next build # production build + route manifest
|
|
```
|
|
|
|
For UI-only changes, also: `npm run storybook` and visually confirm.
|
|
For E2E-relevant changes: `npm run e2e`.
|
|
For changes under `prisma/`: `npm run migrate:smoke` (see
|
|
[docs/testing-guide.md](docs/testing-guide.md) § *Running tests*).
|
|
|
|
## Where else to look
|
|
|
|
- [README.md](README.md) — human onboarding, scripts, project layout.
|
|
- [CONTRIBUTING.md](CONTRIBUTING.md) — local Postgres + Prisma + magic-link
|
|
setup, PR workflow.
|
|
- [docs/README.md](docs/README.md) — index of user-facing docs.
|
|
- [docs/create-flow.md](docs/create-flow.md) — wizard URL/persistence canon
|
|
(read alongside `create-flow.mdc`).
|
|
- [docs/figma-component-registry.md](docs/figma-component-registry.md) —
|
|
Figma ↔ component bucket map after refactors (Type, Sections, admin
|
|
`_components/`, etc.).
|