Project Wide Context
# Engineering Principles & AI Context Guardrails
# Technology Stack: Node.js, React, Next.js (App Router), Vite (SPAs), TypeScript, Tailwind CSS
## 1. Core Directives (The Absolute Constraints)
* **Type Safety:** `strict: true` is mandatory in TypeScript. Never use `any`. Use `unknown` or concrete interfaces. Prefer `type` for simple data shapes/props and `interface` for structural object extension.
* **Component Paradigm:** Write semantic, functional components using standard modern React hooks. Class components are strictly prohibited.
* **Style System:** Use utility-first Tailwind CSS. Avoid creating inline styles (`style={{}}`) or separate CSS modules unless absolutely required by a third-party package dependency.
* **Imports Hierarchy:** Group imports by category: (1) React/Next core, (2) External node_modules, (3) Internal aliases (`@/components/*`, `@/hooks/*`), (4) Relative paths.
---
## 2. Architecture & File Conventions
### Full-Stack / Next.js Projects
* **Routing Structure:** Use the App Router convention (`app/`). Keep the UI layer thin. Data fetching, database access, and schema logic belong in Server Components (`page.tsx`, `layout.tsx`) or isolated route handlers (`route.ts`).
* **Component Splitting:** Keep layout files clean. Extract complex sections into local component files within the same directory, or elevate them to the global `@/components` directory if reused.
* **Client Boundary Directive:** Use `"use client"` at the very top of a file *only* when the component requires interactivity hooks (`useState`, `useEffect`, `useContext`) or client-only web APIs. Never mix server-side data fetching logic in client files.
### Client-Only / Vite Projects
* **State Isolation:** Maintain a clean separation between global state management (e.g., Zustand or Context API) and structural visual components.
* **Hook Optimization:** Isolate complex state workflows, event listeners, or continuous side effects into custom hooks (e.g., `useDebounce`, `useAuth`) to maintain scannability.
---
## 3. Testing & Code Quality Assurance
* **Test Tooling:** Use Vitest for unit and integration testing. Do not use Jest.
* **E2E Strategy:** Implement Playwright for cross-browser, critical user flow integration tests.
* **Mocking:** Avoid deep mocking of implementation details. Focus assertions on public behavior, component rendering outcomes, API payloads, or state changes.
* **No Speculative Logic:** Do not generate defensive logic or error handling for theoretical states that cannot naturally happen given our TypeScript types. Keep loops and conditions highly optimized.
---
## 4. Documentation & AI Workflow Conventions
* **Implicit Documentation:** Code must be expressive and self-documenting through highly semantic variable names and clear function definitions.
* **Comment Criteria:** Avoid writing comments that explain *what* the code does. Add concise inline comments only to explain complex business context or non-obvious *why* design decisions.
* **Session Strategy:** When tasked with complex engineering steps, default to **Planning Mode** first. Generate an explicit `PLAN.md` file breakdown outlining the proposed architectural modifications, type shifts, or dependencies. Do not generate code implementation until the user explicitly flags approvals.
* **Dependency Minimization:** Do not introduce external npm dependencies to solve minor tasks. Prefer implementing highly focused helper utilities using the standard native platform tools available in modern Node.js and ES6+.