mod

Author: yunbow

03_guidelines/common/ai-coding.md

@@ -57,7 +57,7 @@ The static context (8-10 guideline files referenced in CLAUDE.md) typically adds
 ## 2.2 Task Scoping
 * MUST break large tasks into small, focused requests (one file or one function per request)
 * MUST specify the exact file path and function name when requesting changes to existing code
-* SHOULD provide a Before/After example when explaining a pattern you want the AI to follow
+* SHOULD keep code examples minimal (1-3 lines inline ❌/✅). Avoid adding large Before/After sections — benchmark data shows they cause attention dilution without improving compliance
 
 ## 2.3 Effective Prompting Patterns
 * **Do**: "Add auth check using the ActionResult pattern defined in server-actions.md"
@@ -159,9 +159,10 @@ After every code review where AI-generated code was corrected:
 
 ## 5.3 When AI Cannot Follow a Rule
 If AI consistently fails to follow a specific guideline:
-1. Add a concrete code example (Before/After) to the guideline
-2. Add the rule to the project's checklist template
-3. If still failing, consider adding a pre-commit hook or linter rule for automated enforcement
+1. Clarify the rule wording — make it more specific and actionable
+2. Add a minimal inline code example (❌/✅, 1-3 lines) if the rule is ambiguous
+3. Add the rule to the project's checklist template
+4. If still failing, consider adding a pre-commit hook or linter rule for automated enforcement
 
 ## 5.4 Rule Suppression (Escape Hatch)
 When a specific guideline rule is not applicable to a particular module or file, suppress it explicitly rather than ignoring it silently:

03_guidelines/common/code.md

@@ -42,14 +42,51 @@ saveOrder()      // Has side effects - "save" signals persistence
 buildQuery()     // Pure function - "build" signals construction
 ```
 
-## 2.3 Prohibit Enum → Use Union Literals
+## 2.3 Minimize Type Assertions (`as`)
+
+MUST NOT use `as string`, `as any`, or `as unknown as T` unless absolutely necessary. Common violations:
+
+```ts
+// ❌ formData.get() returns FormDataEntryValue | null — don't cast
+const name = formData.get("name") as string;
+
+// ✅ Use Zod to parse and type-narrow
+const parsed = schema.safeParse(Object.fromEntries(formData));
+if (!parsed.success) return { success: false, error: parsed.error.flatten() };
+const { name } = parsed.data; // already typed
+```
+
+Acceptable uses of `as`: `as const` for literal types, Prisma's `globalThis as unknown as` singleton pattern.
+
+## 2.4 Prohibit Enum → Use Union Literals
 
 ```ts
 type Theme = 'dark' | 'light'
 ```
 
 Use Enum **only when external API compatibility is required**.
 
+## 2.4 Exhaustive Checks on Union Types
+
+MUST add exhaustive checks when switching on union types or Prisma enums. Use the `never` type to ensure all cases are handled at compile time:
+
+```ts
+// ✅ Exhaustive check — compiler error if a new status is added
+function getStatusLabel(status: TaskStatus): string {
+  switch (status) {
+    case "TODO": return "To Do";
+    case "IN_PROGRESS": return "In Progress";
+    case "DONE": return "Done";
+    default: {
+      const _exhaustive: never = status;
+      throw new Error(`Unhandled status: ${_exhaustive}`);
+    }
+  }
+}
+```
+
+This applies to all discriminated unions, Prisma enums (`TaskStatus`, `TeamRole`, `Priority`), and action type dispatchers.
+
 # 3. Lint Standards
 
 ## 3.1 Rule Sets

03_guidelines/common/error-handling.md

@@ -273,6 +273,23 @@ class DomainError extends Error {
 
 * Simulate API failures / latency
 
+## 13. MUST: Error and Not-Found Boundaries (Next.js)
+
+MUST place `error.tsx` in each route group and `not-found.tsx` at the app root:
+
+```
+app/
+├── error.tsx           ← MUST: root fallback
+├── not-found.tsx       ← MUST: custom 404
+├── global-error.tsx    ← MUST: catches root layout errors
+├── (auth)/
+│   └── error.tsx       ← MUST: auth errors
+└── (protected)/
+    ├── error.tsx       ← MUST: protected area fallback
+    ├── tasks/error.tsx ← SHOULD: task-specific
+    └── teams/error.tsx ← SHOULD: team-specific
+```
+
 ## Before/After Example
 
 ```typescript

03_guidelines/common/naming.md

@@ -163,14 +163,23 @@ form-schema.ts
 
 ---
 
-# 8. Forms (React Hook Form)
+# 8. Event Handlers and Callbacks
+
+* MUST use `handle` + noun + verb pattern: `handleTaskDelete`, `handleFormSubmit`, `handleStatusToggle`
+* ❌ `handleDelete`, `handleSubmit`, `onSubmit` — missing noun, unclear what is being acted on
+* ✅ `handleTaskDelete`, `handleProfileUpdate`, `handleInvitationAccept`
+* Props passed to child components use `on` prefix: `onTaskDelete`, `onStatusChange`
+
+---
+
+# 9. Forms (React Hook Form)
 
 * `[Domain]Form.tsx`
 * `use[Domain]Form.ts`
 
 ---
 
-# 9. WebSocket / Realtime Names
+# 10. WebSocket / Realtime Names
 
 * Event names: **snake_case**
 * Channel names: **plural**
@@ -188,7 +197,7 @@ form-schema.ts
 | DB column | snake_case (singular) |
 | URL path | kebab-case (plural) |
 | API path | REST / plural |
-| React component | PascalCase (file name also PascalCase) |
+| React component | PascalCase export, **kebab-case file name** (`task-card.tsx` exports `TaskCard`) |
 | Other files/directories | kebab-case |
 | Type / Enum | PascalCase |
 | Zod schema | PascalCase / file name is kebab-case (-schema.ts) |

03_guidelines/common/performance.md

@@ -26,11 +26,33 @@ Decision rule for where to place the RSC/CC boundary:
 ---
 
 ## 2. Client Bundle Optimization (Client Components)
-### Dynamic Import of Dependencies
+### Dynamic Import of Heavy Components
+
+SHOULD use `next/dynamic` for client components that are heavy, below the fold, or conditionally rendered:
+
 ```ts
-const Editor = dynamic(() => import('./Editor'), { ssr: false });
+import dynamic from "next/dynamic";
+
+// ✅ Heavy editor loaded only when needed
+const RichTextEditor = dynamic(() => import("./RichTextEditor"), {
+  ssr: false,
+  loading: () => <div className="h-64 animate-pulse bg-muted rounded" />,
+});
+
+// ✅ Modal/dialog loaded on demand
+const CreateTaskDialog = dynamic(() => import("./CreateTaskDialog"));
+
+// ✅ Chart component (large dependency) deferred
+const AnalyticsChart = dynamic(() => import("./AnalyticsChart"), { ssr: false });
 ```
 
+Candidates for dynamic import:
+* Rich text editors, code editors, markdown renderers
+* Chart/graph components (recharts, chart.js)
+* Modal/dialog content that is not visible on initial load
+* Admin-only components on pages accessible to all users
+* Any component importing a dependency > 50KB
+
 ### Use Tree-Shakable Imports Consistently
 * `import { X } from 'lodash'` — avoid (imports entire library)
 * `import debounce from 'lodash/debounce'` — preferred (imports only the function)

03_guidelines/common/security.md

@@ -159,6 +159,21 @@ export async function getUserProjects(): Promise<ActionResult<Project[]>> {
 - **Production / multiple instances**: Redis (Upstash)
 - **Standard headers**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`
 
+## MUST: Apply Rate Limiting to Auth Server Actions
+
+MUST apply rate limiting to ALL Server Actions that handle authentication — not just API routes. Server Actions for `register`, `login`, `requestPasswordReset`, and `resetPassword` MUST check rate limits per IP before processing:
+
+```ts
+"use server";
+export async function registerUser(formData: FormData): Promise<ActionResult> {
+  // ✅ MUST: Rate limit before any auth processing
+  const ip = (await headers()).get("x-forwarded-for") ?? "unknown";
+  const { success } = await checkRateLimit(`auth:register:${ip}`, { maxRequests: 5, windowMs: 60_000 });
+  if (!success) return { success: false, error: "Too many attempts. Try again later." };
+  // ... rest of registration logic
+}
+```
+
 ---
 
 # 3.3 Webhook Security

03_guidelines/common/validation.md

@@ -6,14 +6,15 @@ This document outlines how to manage **Types** and **Validation** in a unified m
 # 1. Core Policy
 * Build a structure where types naturally synchronize in the order **Zod → Prisma → TypeScript**.
 * API schemas can be converted from **Zod → JSON Schema (for AI APIs, etc.)** for external sharing.
+* MUST validate on BOTH client and server using the SAME Zod schema. Use `zodResolver` from `@hookform/resolvers/zod` for client-side form validation with react-hook-form. Never rely on server-side validation alone.
 
 ---
 
 # 2. Business Logic Rules in Zod Schemas
 
 Business logic rules that belong in Zod schemas (not just format validation):
 
-* **Cross-field constraints**: e.g., `endDate` must be after `startDate`, `maxPrice` >= `minPrice`
+* **Date range constraints**: MUST validate that future-facing dates (e.g., `dueDate`, `expiresAt`) are in the future using `.refine()`. MUST validate that `endDate` is after `startDate`
 * **Domain value boundaries**: e.g., quantity must be 1-999, discount percentage 0-100
 * **Conditional required fields**: e.g., if `paymentMethod` is "card", `cardNumber` is required
 * **Enumerated state transitions**: e.g., order status can only move from "pending" → "confirmed" → "shipped"

03_guidelines/frameworks/nextjs/project-structure.md

@@ -194,7 +194,30 @@ settings/
 
 ---
 
-# 9. Guidelines Summary
+# 9. Dynamic Import for Heavy Components
+
+SHOULD use `next/dynamic` for client components that are heavy, conditionally rendered, or below the fold:
+
+```ts
+import dynamic from "next/dynamic";
+const RichTextEditor = dynamic(() => import("./RichTextEditor"), { ssr: false });
+const CreateTaskDialog = dynamic(() => import("./CreateTaskDialog"));
+const AnalyticsChart = dynamic(() => import("./AnalyticsChart"), { ssr: false });
+```
+
+Candidates: rich text editors, chart components (recharts, chart.js), modal/dialog content, any component with dependencies > 50KB.
+
+# 10. Accessibility: Icon Buttons
+
+MUST add `aria-label` to every `<Button>` without visible text. Every icon-only button, toggle, or close button MUST describe its action:
+
+```tsx
+<Button variant="ghost" size="icon" aria-label="Delete task">
+  <TrashIcon />
+</Button>
+```
+
+# 11. Guidelines Summary
 
 - **Vertical slice structure is the default**
 - **Business logic must always be contained within features**

03_guidelines/frameworks/nextjs/routing.md

@@ -112,9 +112,36 @@ Benefits:
 
 ---
 
-# 5. Summary (Routing / Metadata / Data Fetching)
+# 5. Error and Not-Found Boundaries
+
+## MUST: Place error.tsx in Every Route Group
+
+MUST create `error.tsx` in each route group and high-risk route segment — not just the root:
+
+```
+app/
+├── error.tsx               ← root fallback (MUST)
+├── not-found.tsx           ← custom 404 (MUST)
+├── global-error.tsx        ← catches root layout errors (MUST)
+├── (auth)/
+│   └── error.tsx           ← auth-specific errors (MUST)
+├── (protected)/
+│   ├── error.tsx           ← protected area fallback (MUST)
+│   ├── tasks/
+│   │   └── error.tsx       ← task-specific errors (SHOULD)
+│   └── teams/
+│       └── error.tsx       ← team-specific errors (SHOULD)
+```
+
+## MUST: Place not-found.tsx at Root
+
+MUST create `app/not-found.tsx` with a user-friendly 404 page. Pages that call `notFound()` (e.g., task detail, team detail) will render this component.
+
+---
+
+# 6. Summary (Routing / Metadata / Data Fetching)
 * Organize hierarchy with App Router and separate concerns at the layout level.
-* Unify UX with per-page `loading.tsx` / `error.tsx`.
+* MUST place `error.tsx` in each route group and `not-found.tsx` at root.
 * Public pages use SSG/ISR; user-specific data uses SSR + Server Actions + custom hooks.
 * Flexibly and dynamically control SEO/OG/Twitter via the Metadata API.
 * Achieve DB access that balances security and performance through Server Components.

03_guidelines/frameworks/nextjs/ui.md

@@ -157,7 +157,7 @@ const buttonVariants = cva(
 
 | Element | Required Action |
 |---------|----------------|
-| Icon button | aria-label or sr-only text |
+| Icon button | MUST have `aria-label` describing the action (e.g., `aria-label="Delete task"`, `aria-label="Open menu"`). Every `<Button>` without visible text MUST have an aria-label. |
 | Badge / Counter | Explain meaning with aria-label |
 | Dynamically updated content | aria-live="polite" |
 | Progress bar | role="progressbar" + aria-value* |