菜单
Deep project discovery and architecture planning. Use when starting a new project, when user says "new project", "let's build", or asks for help architecting/planning a non-trivial application.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Automated browser testing of UI flows via Playwright MCP + agent-browser. Use when user says "browser qa", "test the flow", "verify the UI", "test this page", "check if it works", "end-to-end check", or after completing code changes that affect UI and need manual verification replaced by automation. NOT for conversational bug-reporting sessions — that's /qa.
Use when a GitHub ticket/issue bundles multiple sub-tasks or fixes that will take hours, span context compactions, and ship as one reviewed PR — or when the user asks for subagent-driven execution, "the 4875 workflow", or proper progress tracking in the ticket.
Pre-code quality gate that runs /review-pr's anti-slop lens against a written plan BEFORE any code is written. Grounds the plan against the real codebase, runs 11 category checks (security, concurrency, round-trip, control-flow, error-handling, pattern-consistency, plus /review-pr's Q1-Q6), then grills the user one question at a time until the plan is hardened. Use when the user says "harden my plan", "check my plan", "grill my plan before I code", "lint this plan", or invokes `/harden-plan` explicitly. Also invoke proactively after `/grill-me` or `/grilling` completes with a written plan and before any implementation begins. Do NOT invoke after coding has started — redirect to `/review-pr` / `/fix-pr-review` in that case.
The disciplined root-cause loop to follow once you are already IN a debugging session — four phases (root-cause investigation, pattern analysis, hypothesis testing, implementation), no fix without an understood cause, evidence discipline at every component boundary, and a hard stop after repeated failed fixes. Use when about to propose or apply a fix for a bug or test failure, when a previous fix didn't work, when tempted to patch a symptom (add a null check, wrap in try-catch, bump a timeout, add a retry), or when you catch yourself guessing instead of tracing. Pairs with /diagnosing-bugs (repro + feedback-loop construction) — this skill governs fix discipline once the session is underway.
Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping
Use when you need to resolve an in-progress git merge/rebase conflict.
| name | project-discovery |
| description | Deep project discovery and architecture planning. Use when starting a new project, when user says "new project", "let's build", or asks for help architecting/planning a non-trivial application. |
A structured framework for deeply understanding a project before writing any code. Use this when starting a new project or when the user asks to architect/plan something.
Don't just accept answers — interrogate them.
Bad: "What database do you want?" → "PostgreSQL" → "OK"
Good: "What database?" → "PostgreSQL" → "Self-hosted or managed? What's your expected data volume? Any compliance requirements that affect where data lives? Given you're deploying on Coolify, have you considered the backup story?"
Don't read questions like a form. React to answers, build on them, challenge assumptions.
❌ "What's your tech stack? What's your database? What's your auth?"
✅ "Tell me what you're building and who it's for...
Interesting, so doctors need to see patient schedules — that suggests real-time updates might matter.
Are you thinking WebSockets or polling? Actually, before that — what's your team's comfort level with different stacks?"
If choices don't fit constraints, say so.
User: "I want microservices"
You: "What problem does microservices solve for you right now? You mentioned it's just you building this with a 3-month timeline. Microservices add operational complexity — deployment, networking, distributed tracing. A well-structured monolith might get you to market faster. What's driving the microservices thinking?"
Tailor recommendations to their situation.
Solo dev + tight timeline → Simpler stack, managed services
Team + enterprise client → More structure, better patterns
Healthcare/finance → Security-first, compliance awareness
Never just recommend — explain why and what you're giving up.
"I'd suggest Drizzle over Prisma here. Trade-off: Drizzle has a smaller ecosystem and fewer tutorials, but it's faster, has better TypeScript inference, and doesn't need a separate generate step. Given you're comfortable with SQL, you'll appreciate the query builder being closer to actual SQL."
Work through these categories naturally in conversation. You don't need to cover every question — adapt to the project.
Understand the what and why before the how.
| Question | Why It Matters |
|---|---|
| What does this project do? Who is it for? | Frames all technical decisions |
| What problem are we solving? What's painful now? | Ensures we're solving real problems |
| How will we know if it's successful? | Defines done, prevents scope creep |
| What's the timeline? MVP vs full launch? | Determines build vs buy, complexity tolerance |
| Who's building this? Solo, small team, org? | Affects architecture, tooling choices |
| What's the budget for infrastructure/services? | Managed vs self-hosted decisions |
Don't just ask — suggest based on their context.
Frontend Framework
Questions to ask:
Backend Framework
Questions to ask:
Language
This decision affects everything downstream.
Options
Critical questions:
ORM/Query Builder
Questions:
Caching
Get this wrong and you're rebuilding later.
Auth Method
Auth Library
Questions:
Authorization
Critical questions:
Compliance
If any apply:
How frontend talks to backend.
Style
Validation
Error Handling
Questions:
Styling
UI Components
State Management
Forms
Questions:
Hosting
Questions:
CI/CD
Monitoring
Domains
Payments
Other common needs:
Establish conventions early.
Folder Structure
Feature-based (recommended):
src/
features/
auth/
components/
api/
hooks/
patients/
...
Layer-based:
src/
components/
services/
api/
hooks/
Naming Conventions
user-service.ts) or match export (UserService.ts)PatientCard.tsx)getPatientById)MAX_RETRY_COUNT)Imports
import { Button } from '@/components/ui/button'@/ for src rootError Handling Pattern
// Result pattern - explicit success/failure
type Result<T, E = Error> =
| { ok: true; value: T }
| { ok: false; error: E };
// Usage
const result = await createUser(data);
if (!result.ok) {
return handleError(result.error);
}
return result.value;
Git Workflow
feat:, fix:, chore:feature/add-authStrategy
Frameworks
This is critical. Establish these patterns BEFORE writing code. These become the project's "laws" that Claude follows in every session.
DRY — Don't Repeat Yourself
// ❌ Repeated logic
function getPatientFullName(patient: Patient) {
return `${patient.firstName} ${patient.lastName}`;
}
function getDoctorFullName(doctor: Doctor) {
return `${doctor.firstName} ${doctor.lastName}`;
}
// ✅ Single reusable function
function getFullName(person: { firstName: string; lastName: string }) {
return `${person.firstName} ${person.lastName}`;
}
If you write the same logic twice, extract it. This applies to:
Use type over interface
// ❌ Avoid interface
interface User {
id: string;
name: string;
}
// ✅ Use type
type User = {
id: string;
name: string;
};
// ✅ Type works better for unions, intersections, mapped types
type Status = 'pending' | 'active' | 'cancelled';
type UserWithPosts = User & { posts: Post[] };
type Nullable<T> = T | null;
Use function keyword, not arrow functions
// ❌ Avoid arrow functions for declarations
const getUser = async (id: string) => {
return db.users.find(id);
};
const UserCard = ({ user }: UserCardProps) => {
return <div>{user.name}</div>;
};
// ✅ Use function keyword
async function getUser(id: string) {
return db.users.find(id);
}
function UserCard({ user }: UserCardProps) {
return <div>{user.name}</div>;
}
Why function keyword:
this binding is explicitArrow functions are OK for:
items.map(item => item.id)onClick={() => setOpen(true)}These rules apply to ALL code written. No exceptions.
No non-null assertions (!.)
// ❌ Never do this
const name = user!.name;
const first = items[0]!;
// ✅ Handle the null case properly
const name = user?.name ?? 'Unknown';
// ✅ Use type narrowing
if (!user) {
throw new Error('User not found');
}
const name = user.name; // TypeScript knows it's defined
// ✅ Use early return
function getDisplayName(user: User | null): string {
if (!user) return 'Guest';
return user.name;
}
No any type — define proper types, use unknown and narrow if types can't be defined
// ❌ Avoid any
function processData(data: any) {}
const result: any = fetchSomething();
// ✅ Define proper types first
type ApiResponse = {
data: User[];
meta: { total: number };
};
function processData(data: ApiResponse) {}
// ✅ Use unknown and narrow if types can't be defined
function processUnknownData(data: unknown) {
if (typeof data === 'string') {
// TypeScript knows it's string here
}
if (isUser(data)) {
// Use type guard for complex types
}
}
// ✅ Use generics for flexible typing
function processData<T>(data: T): T {}
Check IDE for TypeScript errors after changes
tsc or typecheck commandstypecheck command if present in projectNo comments unless logic is complex
// ❌ Useless comments
// Get user by ID
function getUserById(id: string) {}
// Increment counter
counter++;
// ✅ Only comment WHY, not WHAT
// Retry 3 times because payment gateway has intermittent 503s
const MAX_RETRIES = 3;
// Using Monday as start because Swiss hospitals use ISO week
const weekStart = startOfISOWeek(date);
No emoji in logs or code
// ❌ No emoji
console.log('✅ User created successfully');
logger.info('🚀 Server started');
// ✅ Clean logs
console.log('User created successfully');
logger.info({ port: 3000 }, 'Server started');
Review code after making changes
/code-review command after completing tasksUse Drizzle query builder, not raw SQL
// ❌ Avoid raw SQL
const users = await db.execute(
sql`SELECT * FROM users WHERE clinic_id = ${clinicId}`
);
// ✅ Use Drizzle functions for type safety
const users = await db.query.users.findMany({
where: eq(users.clinicId, clinicId),
with: { appointments: true },
});
// ✅ Raw SQL only when Drizzle can't do it
const result = await db.execute(
sql`SELECT complex_aggregate_function(...)`
);
Never run migrations without explicit permission
db:pushdb:migratedb:generatePrefer early returns over nesting
// ❌ Deeply nested
function processUser(user: User | null) {
if (user) {
if (user.isActive) {
if (user.hasPermission) {
return doSomething(user);
}
}
}
return null;
}
// ✅ Early returns
function processUser(user: User | null) {
if (!user) return null;
if (!user.isActive) return null;
if (!user.hasPermission) return null;
return doSomething(user);
}
No magic numbers or strings
// ❌ Magic values
if (status === 1) {}
setTimeout(fn, 86400000);
if (role === 'admin') {}
// ✅ Named constants
const STATUS_ACTIVE = 1;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;
const ROLES = { ADMIN: 'admin', USER: 'user' } as const;
if (status === STATUS_ACTIVE) {}
setTimeout(fn, ONE_DAY_MS);
if (role === ROLES.ADMIN) {}
Use optional chaining and nullish coalescing
// ❌ Verbose null checks
const street = user && user.address && user.address.street;
const name = user.name || 'Unknown'; // Bug: empty string becomes 'Unknown'
// ✅ Modern operators
const street = user?.address?.street;
const name = user.name ?? 'Unknown'; // Only null/undefined trigger fallback
Prefer const over let
// ❌ Using let when value doesn't change
let user = await getUser(id);
let total = items.reduce((sum, i) => sum + i.price, 0);
// ✅ Use const
const user = await getUser(id);
const total = items.reduce((sum, i) => sum + i.price, 0);
// let only when reassignment is needed
let attempts = 0;
while (attempts < 3) {
attempts++;
}
Prefer async/await over .then()
// ❌ Promise chains
function getData() {
return fetch('/api/data')
.then(res => res.json())
.then(data => processData(data))
.catch(err => handleError(err));
}
// ✅ async/await
async function getData() {
const { data, error } = await tryCatch(fetch('/api/data').then(r => r.json()));
if (error) return handleError(error);
return processData(data);
}
Use tryCatch utility instead of try-catch blocks
Always use the tryCatch utility for async error handling. No raw try-catch blocks.
// lib/try-catch.ts — Add this to every project
type Success<T> = {
data: T;
error: null;
};
type Failure<E> = {
data: null;
error: E;
};
type Result<T, E = Error> = Success<T> | Failure<E>;
// Main async wrapper
export async function tryCatch<T, E = Error>(
promise: Promise<T>,
): Promise<Result<T, E>> {
try {
const data = await promise;
return { data, error: null };
} catch (error) {
return { data: null, error: error as E };
}
}
// Sync version for non-async functions that might throw
export function tryCatchSync<T, E = Error>(
fn: () => T,
): Result<T, E> {
try {
const data = fn();
return { data, error: null };
} catch (error) {
return { data: null, error: error as E };
}
}
// Wrapper for functions — returns a safe version that never throws
export function withTryCatch<TArgs extends unknown[], TReturn, E = Error>(
fn: (...args: TArgs) => Promise<TReturn>,
): (...args: TArgs) => Promise<Result<TReturn, E>> {
return async (...args: TArgs) => {
return tryCatch<TReturn, E>(fn(...args));
};
}
// Retry wrapper with exponential backoff
export async function tryCatchRetry<T, E = Error>(
promise: () => Promise<T>,
options: {
maxRetries?: number;
delayMs?: number;
backoff?: boolean;
} = {},
): Promise<Result<T, E>> {
const { maxRetries = 3, delayMs = 1000, backoff = true } = options;
let lastError: E | null = null;
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const { data, error } = await tryCatch<T, E>(promise());
if (!error) {
return { data, error: null };
}
lastError = error;
if (attempt < maxRetries) {
const delay = backoff ? delayMs * Math.pow(2, attempt) : delayMs;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
return { data: null, error: lastError as E };
}
// Timeout wrapper
export async function tryCatchWithTimeout<T, E = Error>(
promise: Promise<T>,
timeoutMs: number,
timeoutError?: E,
): Promise<Result<T, E>> {
const timeout = new Promise<never>((_, reject) => {
setTimeout(() => {
reject(timeoutError ?? new Error(`Operation timed out after ${timeoutMs}ms`));
}, timeoutMs);
});
return tryCatch<T, E>(Promise.race([promise, timeout]));
}
// ❌ Avoid try-catch blocks
async function getUser(id: string) {
try {
const response = await fetch(`/api/users/${id}`);
const user = await response.json();
return user;
} catch (error) {
console.error('Failed to fetch user:', error);
return null;
}
}
// ✅ Use tryCatch utility
import { tryCatch } from '@/lib/try-catch';
async function getUser(id: string) {
const { data: response, error: fetchError } = await tryCatch(
fetch(`/api/users/${id}`)
);
if (fetchError) {
logger.error({ id, error: fetchError.message }, 'Failed to fetch user');
return null;
}
const { data: user, error: parseError } = await tryCatch(response.json());
if (parseError) {
logger.error({ id, error: parseError.message }, 'Failed to parse user response');
return null;
}
return user;
}
// ✅ Use tryCatchSync for JSON parsing or other sync operations
import { tryCatchSync } from '@/lib/try-catch';
function parseConfig(jsonString: string) {
const { data, error } = tryCatchSync(() => JSON.parse(jsonString));
if (error) {
logger.error('Invalid JSON config');
return null;
}
return data;
}
// ✅ Use withTryCatch to wrap existing functions
import { withTryCatch } from '@/lib/try-catch';
const safeGetUser = withTryCatch(getUser);
const { data: user, error } = await safeGetUser('123');
// ✅ Use tryCatchRetry for flaky operations
import { tryCatchRetry } from '@/lib/try-catch';
const { data, error } = await tryCatchRetry(
() => fetch('https://flaky-api.com/data'),
{ maxRetries: 3, delayMs: 1000, backoff: true }
);
// ✅ Use tryCatchWithTimeout for operations that might hang
import { tryCatchWithTimeout } from '@/lib/try-catch';
const { data, error } = await tryCatchWithTimeout(
fetch('https://slow-api.com/data'),
5000 // 5 second timeout
);
Why tryCatch over try-catch:
{ data, error }// Multiple async operations — clean and flat
async function createOrderWithPayment(orderData: OrderInput) {
const { data: order, error: orderError } = await tryCatch(
orderService.create(orderData)
);
if (orderError) {
return { ok: false, error: { code: 'ORDER_FAILED', cause: orderError } };
}
const { data: payment, error: paymentError } = await tryCatch(
paymentService.charge(order.id, order.total)
);
if (paymentError) {
// Rollback order
await tryCatch(orderService.cancel(order.id));
return { ok: false, error: { code: 'PAYMENT_FAILED', cause: paymentError } };
}
return { ok: true, data: { order, payment } };
}
No nested ternaries
// ❌ Hard to read
const label = status === 'active' ? 'Active' : status === 'pending' ? 'Pending' : status === 'cancelled' ? 'Cancelled' : 'Unknown';
// ✅ Use object lookup or switch
const STATUS_LABELS: Record<string, string> = {
active: 'Active',
pending: 'Pending',
cancelled: 'Cancelled',
};
const label = STATUS_LABELS[status] ?? 'Unknown';
// ✅ Or function with early returns
function getStatusLabel(status: string): string {
if (status === 'active') return 'Active';
if (status === 'pending') return 'Pending';
if (status === 'cancelled') return 'Cancelled';
return 'Unknown';
}
Meaningful variable names
// ❌ Cryptic names
const d = new Date();
const u = await getUser(id);
const arr = items.filter(x => x.active);
// ✅ Descriptive names
const currentDate = new Date();
const authenticatedUser = await getUser(id);
const activeItems = items.filter(item => item.active);
// Single letters OK for: loop indices, callbacks, generics
items.map((item, i) => ({ ...item, index: i }));
function identity<T>(value: T): T { return value; }
Boolean names should read as questions
// ❌ Unclear intent
const loading = true;
const data = false;
const permission = true;
// ✅ is/has/can/should prefixes
const isLoading = true;
const hasData = false;
const canDelete = true;
const shouldRefresh = true;
Keep functions small — one function = one job
Each function should do ONE thing. If a function is too big, divide it into smaller functions and compose them together.
Guidelines:
// ❌ Function doing multiple jobs (too big)
async function handleUserRegistration(data: FormData) {
// Job 1: Validate input (10 lines)
const errors = [];
if (!data.email) errors.push('Email required');
if (!data.password) errors.push('Password required');
if (data.password.length < 8) errors.push('Password too short');
if (errors.length > 0) throw new ValidationError(errors);
// Job 2: Hash password (5 lines)
const salt = await bcrypt.genSalt(10);
const hashedPassword = await bcrypt.hash(data.password, salt);
// Job 3: Create user in DB (8 lines)
const user = await db.insert(users).values({
email: data.email,
password: hashedPassword,
createdAt: new Date(),
}).returning();
// Job 4: Send welcome email (6 lines)
await transporter.sendMail({
to: data.email,
subject: 'Welcome!',
html: renderWelcomeEmail(user),
});
// Job 5: Create audit log (5 lines)
await db.insert(auditLogs).values({
action: 'USER_REGISTERED',
userId: user.id,
timestamp: new Date(),
});
return user;
}
// ✅ Each function does ONE job
function validateRegistration(data: FormData): ValidatedRegistration {
const errors = [];
if (!data.email) errors.push('Email required');
if (!data.password) errors.push('Password required');
if (data.password.length < 8) errors.push('Password too short');
if (errors.length > 0) throw new ValidationError(errors);
return { email: data.email, password: data.password };
}
async function hashPassword(password: string): Promise<string> {
const salt = await bcrypt.genSalt(10);
return bcrypt.hash(password, salt);
}
async function createUserInDb(email: string, hashedPassword: string): Promise<User> {
const [user] = await db.insert(users).values({
email,
password: hashedPassword,
createdAt: new Date(),
}).returning();
return user;
}
async function sendWelcomeEmail(user: User): Promise<void> {
await transporter.sendMail({
to: user.email,
subject: 'Welcome!',
html: renderWelcomeEmail(user),
});
}
async function logUserRegistration(userId: string): Promise<void> {
await db.insert(auditLogs).values({
action: 'USER_REGISTERED',
userId,
timestamp: new Date(),
});
}
// ✅ Compose small functions into larger operation
async function handleUserRegistration(data: FormData): Promise<User> {
const validated = validateRegistration(data);
const hashedPassword = await hashPassword(validated.password);
const user = await createUserInDb(validated.email, hashedPassword);
await sendWelcomeEmail(user);
await logUserRegistration(user.id);
return user;
}
Benefits of small functions:
hashPassword used elsewhere)Keep files small — refactor when too large
When files grow too large, split them. Use these limits as guidelines:
| File Type | Max LOC | When to Split |
|---|---|---|
| React Components | 150-200 | Extract sub-components, hooks, utils |
| Custom Hooks | 80-100 | Split into smaller hooks, extract helpers |
| API Routes/Handlers | 80-100 | Extract to service layer |
| Service files | 200-250 | Split by domain/entity |
| Utility files | 100-150 | Group by functionality |
| Type definition files | 150-200 | Split by domain |
| Config files | 100 | Split by concern |
// ❌ One massive component file (400+ lines)
// user-dashboard.tsx
export function UserDashboard() {
// 50 lines of hooks and state
// 100 lines of helper functions
// 250 lines of JSX with inline logic
}
// ✅ Split into focused files
// user-dashboard/
// index.tsx — Main component (80 lines)
// use-dashboard.ts — Custom hook for state/logic (60 lines)
// stats-card.tsx — Sub-component (40 lines)
// activity-feed.tsx — Sub-component (50 lines)
// utils.ts — Helper functions (30 lines)
// types.ts — Types for this feature (20 lines)
Signs a file needs refactoring:
utils.ts or helpers.tsHow to split:
// Before: services/user-service.ts (400 lines)
// - User CRUD
// - User authentication
// - User permissions
// - User notifications
// After: Split by concern
// services/user/
// user.service.ts — CRUD operations
// auth.service.ts — Authentication logic
// permission.service.ts — Permission checks
// notification.service.ts — User notifications
// index.ts — Re-exports (optional)
// Before: components/form.tsx (300 lines)
// - Form component
// - All field components
// - Validation logic
// - Submit handling
// After: Split by responsibility
// components/form/
// form.tsx — Main form wrapper
// form-field.tsx — Reusable field component
// use-form-validation.ts — Validation hook
// form-actions.tsx — Submit/cancel buttons
// types.ts — Form types
Prefer named exports over default exports
// ❌ Default exports — harder to refactor, inconsistent imports
export default function UserCard() {}
import UserCard from './user-card'; // Can be named anything
// ✅ Named exports — explicit, refactor-friendly
export function UserCard() {}
import { UserCard } from './user-card'; // Must match
Don't mutate function parameters
// ❌ Mutating input
function addTimestamp(obj: Record<string, unknown>) {
obj.timestamp = Date.now(); // Mutates original!
return obj;
}
// ✅ Return new object
function addTimestamp(obj: Record<string, unknown>) {
return { ...obj, timestamp: Date.now() };
}
No unused variables or imports
// ❌ Dead code
import { unused } from 'some-lib';
const temp = calculateValue(); // Never used
// ✅ Clean imports, no dead code
// ESLint will catch these — fix before committing
Use destructuring
// ❌ Repetitive property access
function greet(user: User) {
return `Hello ${user.firstName} ${user.lastName} from ${user.address.city}`;
}
// ✅ Destructure
function greet({ firstName, lastName, address: { city } }: User) {
return `Hello ${firstName} ${lastName} from ${city}`;
}
Use template literals
// ❌ String concatenation
const message = 'Hello ' + firstName + ' ' + lastName + '!';
const url = baseUrl + '/api/' + version + '/users/' + id;
// ✅ Template literals
const greeting = `Hello ${firstName} ${lastName}`;
const apiUrl = `${baseUrl}/api/${version}/users/${id}`;
No console.log in production code
// ❌ Console in production
console.log('User created:', user);
console.error('Something went wrong');
// ✅ Use proper logger
import { logger } from '@/lib/logger';
logger.info({ userId: user.id }, 'User created');
logger.error({ err }, 'Operation failed');
// console.log OK only for:
// - Local debugging (remove before commit)
// - CLI tools
// - Development-only code
Null vs Undefined Convention
Use null for intentional absence, undefined for optional/not set:
type User = {
name: string;
deletedAt: Date | null; // Explicitly set to "nothing"
nickname?: string; // May not exist (undefined)
};
// Return null when "not found" is an expected outcome
async function findUser(id: string): Promise<User | null> {
const user = await db.users.find(id);
return user ?? null;
}
// Use undefined for optional parameters
function greet(name: string, title?: string) {
return title ? `Hello ${title} ${name}` : `Hello ${name}`;
}
// Summary:
// null = "I explicitly set this to nothing"
// undefined = "This was never set" or "This is optional"
Import Type for Type-Only Imports
Use import type for imports that are only used as types — they get erased at compile time:
// ❌ Imports type at runtime (may add to bundle)
import { User, UserService } from './user';
// ✅ Type-only import (erased at compile time)
import type { User, Post } from './types';
import { UserService } from './user';
// ✅ Or inline type imports
import { UserService, type User, type CreateUserInput } from './user';
// Benefits:
// - Smaller bundle (types erased)
// - Clearer intent (this is just a type)
// - Avoids circular dependency issues
Async Patterns — Parallel vs Sequential
Run independent async operations in parallel:
// ❌ Sequential (slow) — each waits for previous
async function loadDashboard(userId: string) {
const user = await getUser(userId); // 100ms
const posts = await getPosts(userId); // 100ms
const notifications = await getNotifications(userId); // 100ms
// Total: 300ms
return { user, posts, notifications };
}
// ✅ Parallel (fast) — all run at once
async function loadDashboard(userId: string) {
const [user, posts, notifications] = await Promise.all([
getUser(userId), // 100ms
getPosts(userId), // 100ms
getNotifications(userId), // 100ms
]);
// Total: ~100ms
return { user, posts, notifications };
}
// ✅ Parallel with tryCatch for error handling
async function loadDashboard(userId: string) {
const [userResult, postsResult, notificationsResult] = await Promise.all([
tryCatch(getUser(userId)),
tryCatch(getPosts(userId)),
tryCatch(getNotifications(userId)),
]);
if (userResult.error) {
// Handle user fetch error
}
return {
user: userResult.data,
posts: postsResult.data ?? [],
notifications: notificationsResult.data ?? [],
};
}
// When to use sequential:
// - When second call depends on first call's result
// - When you need to short-circuit on failure
const user = await getUser(userId);
if (!user) return null;
const posts = await getPostsByAuthor(user.authorId); // Depends on user
Date/Time Handling
Dates are a common source of bugs. Follow these rules:
// RULES:
// 1. Store all dates as UTC in database
// 2. Use ISO strings for API transport
// 3. Convert to local timezone only in UI layer
// 4. Use date-fns or dayjs — not native Date methods for manipulation
// ❌ Ambiguous — what timezone?
const date = new Date('2024-01-15');
const formatted = date.toLocaleDateString();
// ✅ Explicit UTC
const date = new Date('2024-01-15T00:00:00Z');
// ✅ Use date-fns for manipulation
import { addDays, format, parseISO, startOfDay } from 'date-fns';
import { formatInTimeZone } from 'date-fns-tz';
const parsed = parseISO('2024-01-15T10:30:00Z');
const nextWeek = addDays(parsed, 7);
const formatted = format(nextWeek, 'yyyy-MM-dd');
// ✅ API response — always ISO string
return Response.json({
createdAt: user.createdAt.toISOString(),
});
// ✅ Display in UI — convert to local
const localTime = formatInTimeZone(
appointment.startTime,
userTimezone,
'MMM d, yyyy h:mm a'
);
// ✅ Database schema — use timestamptz
const appointments = pgTable('appointments', {
startTime: timestamp('start_time', { withTimezone: true }).notNull(),
});
Standard Error Types
Define consistent error structures across the codebase:
// lib/errors.ts — Standard error structure
type AppError = {
code: string; // Machine-readable: 'USER_NOT_FOUND'
message: string; // Human-readable: 'User not found'
cause?: unknown; // Original error for debugging
meta?: Record<string, unknown>; // Additional context
};
// Domain-specific error codes
export const USER_ERRORS = {
NOT_FOUND: 'USER_NOT_FOUND',
ALREADY_EXISTS: 'USER_ALREADY_EXISTS',
INVALID_CREDENTIALS: 'USER_INVALID_CREDENTIALS',
EMAIL_NOT_VERIFIED: 'USER_EMAIL_NOT_VERIFIED',
} as const;
export const PAYMENT_ERRORS = {
DECLINED: 'PAYMENT_DECLINED',
INSUFFICIENT_FUNDS: 'PAYMENT_INSUFFICIENT_FUNDS',
EXPIRED_CARD: 'PAYMENT_EXPIRED_CARD',
} as const;
// Usage in service
function createUserError(
code: keyof typeof USER_ERRORS,
message: string,
meta?: Record<string, unknown>
): AppError {
return { code: USER_ERRORS[code], message, meta };
}
// Example
return {
ok: false,
error: createUserError('ALREADY_EXISTS', 'A user with this email already exists', { email })
};
Structured Logging (Class-Based Logger)
Use a class-based logger that accumulates context throughout a request lifecycle.
import { Logger, createRequestLogger } from '@/lib/logger';
// ❌ Unstructured — hard to search/parse
console.log('User ' + userId + ' created order ' + orderId);
// ❌ Static context — can't accumulate
logger.info('Order created', { orderId });
// ✅ Class-based — context accumulates as you progress
const log = new Logger({ requestId: crypto.randomUUID() });
// Add context as you go through the function
log.addContext({ userId: session.user.id });
log.info('User authenticated'); // Has requestId + userId
log.addContext({ orderId: order.id });
log.info('Order created'); // Has requestId + userId + orderId
log.addContext({ paymentId: payment.id });
log.info('Payment processed'); // Has ALL previous context + paymentId
Full API Handler Example:
export async function POST(req: Request) {
// 1. Create logger with request ID
const log = createRequestLogger({
requestId: crypto.randomUUID(),
method: 'POST',
path: '/api/orders',
});
// 2. Parse input — add context
const body = await req.json();
log.addContext({ action: 'createOrder', itemCount: body.items.length });
// 3. Auth — add user context
const session = await getSession();
if (!session) {
log.warn('Unauthorized request');
return Response.json({ error: 'Unauthorized' }, { status: 401 });
}
log.addContext({ userId: session.user.id });
// 4. Business logic — pass logger to service
const { data: order, error } = await tryCatch(
orderService.create(body, log) // Logger passed to service
);
if (error) {
log.error('Order creation failed', { error: error.message });
return Response.json({ error: 'Failed' }, { status: 500 });
}
log.addContext({ orderId: order.id });
log.info('Order created successfully');
// Final log has: requestId, method, path, action, itemCount, userId, orderId
return Response.json({ data: order });
}
// In service — receive logger and continue adding context
async function create(data: OrderInput, log: Logger): Promise<Order> {
log.addContext({ step: 'orderService.create' });
// Use timing
const done = log.time('Database insert');
const order = await db.insert(orders).values(data);
done({ rowCount: 1 }); // Logs with duration
return order;
}
Key Logger Methods:
const log = new Logger({ requestId });
// Add to context (accumulates)
log.addContext({ userId, orderId });
// Create independent child (parent unaffected)
const childLog = log.child({ step: 'payment' });
// Timing
const done = log.time('Operation');
await doSomething();
done({ extra: 'context' }); // Logs with duration
// Async timing (auto logs start/end)
const result = await log.timeAsync('Fetch user', () => getUser(id));
// Log and return error (for tryCatch pattern)
if (error) {
return { ok: false, error: log.logError('Failed', error) };
}
// Scoped operation (auto logs start/end with duration)
await log.scope('processPayment', async (scopedLog) => {
scopedLog.addContext({ amount: 100 });
// ...
});
Zod Schema Patterns
Zod schemas should be the source of truth for types:
// 1. Schema is source of truth — derive types from it
const userSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
name: z.string().min(2).max(100),
role: z.enum(['admin', 'user', 'guest']),
createdAt: z.coerce.date(),
});
// Derive type from schema — single source of truth
type User = z.infer<typeof userSchema>;
// 2. Create/Update schemas extend base
const createUserSchema = userSchema.omit({ id: true, createdAt: true }).extend({
password: z.string().min(8),
});
type CreateUserInput = z.infer<typeof createUserSchema>;
const updateUserSchema = userSchema.partial().omit({ id: true, createdAt: true });
type UpdateUserInput = z.infer<typeof updateUserSchema>;
// 3. Co-locate schemas with their usage
// api/users/route.ts
const createUserBodySchema = z.object({
email: z.string().email(),
name: z.string().min(2),
password: z.string().min(8),
});
export async function POST(req: Request) {
const body = await req.json();
const { data: input, error } = tryCatchSync(() => createUserBodySchema.parse(body));
if (error) {
return Response.json({ error: { code: 'VALIDATION_ERROR' } }, { status: 400 });
}
// input is fully typed
}
// 4. Use .transform for data transformation
const apiResponseSchema = z.object({
created_at: z.string(),
}).transform((data) => ({
createdAt: new Date(data.created_at),
}));
React Performance — useMemo/useCallback Rules
Don't over-optimize. Use memo hooks only when needed:
// useMemo — ONLY for expensive computations
// ❌ Don't memo cheap operations (adds overhead)
const fullName = useMemo(() => `${first} ${last}`, [first, last]);
const isAdmin = useMemo(() => user.role === 'admin', [user.role]);
// ✅ Memo expensive operations
const sortedAndFiltered = useMemo(
() => items
.filter(item => item.status === 'active')
.sort((a, b) => complexSortFunction(a, b))
.map(item => transformItem(item)),
[items]
);
// ✅ Memo when creating objects/arrays passed to dependencies
const filters = useMemo(
() => ({ status: activeStatus, search: searchTerm }),
[activeStatus, searchTerm]
);
useEffect(() => {
fetchData(filters);
}, [filters]); // Now stable reference
// useCallback — ONLY when passing to memoized children
// ❌ Don't useCallback if child isn't memoized (useless)
const handleClick = useCallback(() => setOpen(true), []);
<Button onClick={handleClick} /> // Button not memoized, so useless
// ✅ useCallback when child IS memoized
const MemoizedList = memo(ItemList);
function Parent() {
const handleSelect = useCallback((id: string) => {
setSelectedId(id);
}, []);
const handleDelete = useCallback((id: string) => {
deleteItem(id);
}, [deleteItem]);
return <MemoizedList onSelect={handleSelect} onDelete={handleDelete} />;
}
// Summary:
// - Don't useMemo/useCallback by default
// - Profile first, optimize second
// - useMemo for expensive computations or stable references
// - useCallback only when passing to memo() children
API Route Handler Structure
Standard pattern for all API route handlers:
// Standard structure for every API route
export async function POST(req: Request) {
// 1. PARSE & VALIDATE INPUT
const { data: body, error: parseError } = await tryCatch(req.json());
if (parseError) {
return Response.json(
{ error: { code: 'INVALID_JSON', message: 'Invalid request body' } },
{ status: 400 }
);
}
const { data: input, error: validationError } = tryCatchSync(() =>
createUserSchema.parse(body)
);
if (validationError) {
return Response.json(
{ error: { code: 'VALIDATION_ERROR', message: validationError.message } },
{ status: 400 }
);
}
// 2. AUTHENTICATE (if needed)
const session = await getSession();
if (!session) {
return Response.json(
{ error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
{ status: 401 }
);
}
// 3. AUTHORIZE (if needed)
if (!canCreateUser(session.user)) {
return Response.json(
{ error: { code: 'FORBIDDEN', message: 'Insufficient permissions' } },
{ status: 403 }
);
}
// 4. BUSINESS LOGIC (delegate to service)
const { data: user, error: serviceError } = await tryCatch(
userService.create(input)
);
if (serviceError) {
logger.error({ error: serviceError.message, input }, 'Failed to create user');
return Response.json(
{ error: { code: serviceError.code ?? 'CREATE_FAILED', message: serviceError.message } },
{ status: 400 }
);
}
// 5. RETURN SUCCESS
logger.info({ userId: user.id }, 'User created');
return Response.json({ data: user }, { status: 201 });
}
Git Commit Convention
Use conventional commits for clean history:
# Format: type: short description (imperative mood)
# Max 50 chars for subject line
# Types:
feat: add user authentication
fix: resolve payment timeout issue
refactor: extract validation logic into separate module
perf: optimize database queries for dashboard
chore: update dependencies
docs: add API documentation
test: add unit tests for user service
style: format code with prettier
# Examples:
feat: add password reset functionality
fix: prevent duplicate form submissions
refactor: split UserService into smaller modules
perf: add database indexes for common queries
chore: upgrade Next.js to v15
docs: document API rate limits
test: add integration tests for payment flow
# With scope (optional):
feat(auth): add OAuth2 support
fix(api): handle null response from external service
refactor(db): migrate from Prisma to Drizzle
Pick one and stick to it across the entire codebase.
Option A: Result Pattern (Recommended for services)
// Define once, use everywhere
type Result<T, E = Error> =
| { ok: true; data: T }
| { ok: false; error: E };
// Service never throws
async function createUser(data: CreateUserInput): Promise<Result<User, CreateUserError>> {
const existing = await db.user.findByEmail(data.email);
if (existing) {
return { ok: false, error: { code: 'EMAIL_EXISTS', message: 'Email already registered' } };
}
const user = await db.user.create(data);
return { ok: true, data: user };
}
// Caller handles explicitly
const result = await createUser(input);
if (!result.ok) {
return res.status(400).json({ error: result.error });
}
return res.json(result.data);
Option B: Throw + Catch (Simpler, familiar)
// Custom error classes
class AppError extends Error {
constructor(public code: string, message: string, public statusCode = 400) {
super(message);
}
}
// Service throws
async function createUser(data: CreateUserInput): Promise<User> {
const existing = await db.user.findByEmail(data.email);
if (existing) {
throw new AppError('EMAIL_EXISTS', 'Email already registered');
}
return db.user.create(data);
}
// Global error handler catches
app.use((err, req, res, next) => {
if (err instanceof AppError) {
return res.status(err.statusCode).json({ code: err.code, message: err.message });
}
// Unknown error
console.error(err);
return res.status(500).json({ code: 'INTERNAL', message: 'Something went wrong' });
});
Questions to establish:
Strict TypeScript Rules
// tsconfig.json essentials
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true, // array[0] is T | undefined
"noImplicitReturns": true,
"exactOptionalPropertyTypes": true
}
}
Type Organization
// Option A: Co-located with feature
src/features/users/types.ts
src/features/users/user.service.ts
// Option B: Centralized
src/types/user.types.ts
src/types/api.types.ts
// Option C: Inferred from schema (Drizzle/Prisma)
// No separate type files — derive from DB schema
type User = typeof users.$inferSelect;
type NewUser = typeof users.$inferInsert;
Always use type, never interface
// ❌ Don't use interface
interface User {
id: string;
name: string;
}
interface UserCardProps {
user: User;
onEdit: () => void;
}
// ✅ Always use type
type User = {
id: string;
name: string;
};
type UserCardProps = {
user: User;
onEdit: () => void;
};
// Type advantages:
// - Consistent syntax for all type definitions
// - Works with unions: type Status = 'a' | 'b';
// - Works with intersections: type Extended = Base & Extra;
// - Works with mapped types: type Readonly<T> = { readonly [K in keyof T]: T[K] };
// - No declaration merging surprises
Zod + TypeScript Pattern
// Schema is source of truth
const createUserSchema = z.object({
email: z.string().email(),
name: z.string().min(2).max(100),
role: z.enum(['admin', 'user']).default('user'),
});
// Type derived from schema
type CreateUserInput = z.infer<typeof createUserSchema>;
// Validate at boundary
const input = createUserSchema.parse(req.body); // throws ZodError
Questions to establish:
type vs interface? (Prefer type for consistency, or interface for declaration merging)Files
kebab-case.ts ← Recommended (works everywhere)
PascalCase.tsx ← React components (optional)
camelCase.ts ← Also common
Pick one, enforce it.
Functions & Variables
// Functions: camelCase, verb-first
function getUserById(id: string) {}
function createOrder(data: OrderInput) {}
function validateEmail(email: string) {}
// Boolean: is/has/can/should prefix
const isLoading = true;
const hasPermission = false;
const canDelete = user.role === 'admin';
// Constants: SCREAMING_SNAKE for true constants
const MAX_RETRIES = 3;
const API_BASE_URL = process.env.API_URL;
// Env vars: SCREAMING_SNAKE
DATABASE_URL=
NEXT_PUBLIC_API_URL=
Components
// PascalCase, noun-based
function UserCard() {}
function PatientList() {}
function AppointmentModal() {}
// Props: ComponentNameProps
interface UserCardProps {
user: User;
onEdit: () => void;
}
Database
-- Tables: snake_case, plural
users, appointments, medical_records
-- Columns: snake_case
created_at, updated_at, user_id
-- Foreign keys: singular_table_id
user_id (not users_id)
API Routes
REST: /api/v1/users/:id/appointments
kebab-case for multi-word: /api/v1/medical-records
Actions: POST /api/v1/appointments/:id/confirm
POST /api/v1/users/:id/reset-password
Path Aliases (Required)
// tsconfig.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"],
"@/components/*": ["./src/components/*"],
"@/lib/*": ["./src/lib/*"]
}
}
}
// Usage
import { Button } from '@/components/ui/button';
import { db } from '@/lib/db';
Import Order (enforce with ESLint)
// 1. Node built-ins
import path from 'path';
// 2. External packages
import { z } from 'zod';
import { eq } from 'drizzle-orm';
// 3. Internal aliases
import { db } from '@/lib/db';
import { UserCard } from '@/components/user-card';
// 4. Relative imports (same feature)
import { validateUser } from './validation';
import type { UserFormProps } from './types';
// 5. Types last (if separate)
import type { User } from '@/types';
Barrel Exports: Generally Avoid
// ❌ Avoid barrel exports (slower builds, circular deps)
// src/components/index.ts
export * from './Button';
export * from './Card';
// ✅ Direct imports (tree-shakeable)
import { Button } from '@/components/ui/button';
import { Card } from '@/components/ui/card';
Option A: Feature-Based (Recommended)
src/
features/
auth/
components/
login-form.tsx
signup-form.tsx
hooks/
use-auth.ts
api/
login.ts
signup.ts
auth.service.ts
auth.types.ts
patients/
components/
hooks/
api/
patients.service.ts
components/
ui/ ← Shared UI (shadcn)
button.tsx
card.tsx
layout/
header.tsx
sidebar.tsx
lib/
db.ts
auth.ts
utils.ts
types/
index.ts ← Shared types only
Option B: Layer-Based
src/
components/
ui/
forms/
layout/
services/
user.service.ts
auth.service.ts
api/
users/
auth/
hooks/
types/
utils/
Option C: Next.js App Router Convention
app/
(auth)/
login/page.tsx
signup/page.tsx
(dashboard)/
patients/
page.tsx
[id]/page.tsx
appointments/
page.tsx
api/
users/route.ts
appointments/route.ts
src/
components/
lib/
services/
REST Conventions
// Resources are nouns, plural
GET /api/v1/patients // List
POST /api/v1/patients // Create
GET /api/v1/patients/:id // Get one
PATCH /api/v1/patients/:id // Partial update
PUT /api/v1/patients/:id // Full replace
DELETE /api/v1/patients/:id // Delete
// Nested resources
GET /api/v1/patients/:id/appointments
POST /api/v1/patients/:id/appointments
// Actions (when CRUD doesn't fit)
POST /api/v1/appointments/:id/confirm
POST /api/v1/appointments/:id/cancel
POST /api/v1/users/:id/reset-password
Response Format (Consistent)
// Success
{
"data": { ... },
"meta": {
"page": 1,
"total": 100
}
}
// Error
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
}
}
API Handler Pattern
// Consistent structure for all handlers
export async function POST(req: Request) {
// 1. Parse & validate input
const body = await req.json();
const input = createPatientSchema.safeParse(body);
if (!input.success) {
return Response.json(
{ error: { code: 'VALIDATION_ERROR', details: input.error.flatten() } },
{ status: 400 }
);
}
// 2. Auth check
const session = await getSession();
if (!session) {
return Response.json(
{ error: { code: 'UNAUTHORIZED' } },
{ status: 401 }
);
}
// 3. Business logic (delegate to service)
const result = await patientService.create(input.data);
if (!result.ok) {
return Response.json({ error: result.error }, { status: 400 });
}
// 4. Return success
return Response.json({ data: result.data }, { status: 201 });
}
Schema Design Rules
// Every table has these
const baseColumns = {
id: uuid('id').defaultRandom().primaryKey(),
createdAt: timestamp('created_at').defaultNow().notNull(),
updatedAt: timestamp('updated_at').defaultNow().notNull(),
};
// Soft delete pattern (if needed)
const softDelete = {
deletedAt: timestamp('deleted_at'),
};
// Example table
export const patients = pgTable('patients', {
...baseColumns,
...softDelete,
name: varchar('name', { length: 255 }).notNull(),
email: varchar('email', { length: 255 }).unique(),
dateOfBirth: date('date_of_birth'),
// Foreign keys
clinicId: uuid('clinic_id').references(() => clinics.id),
});
Query Patterns
// Repository/Service pattern
class PatientService {
async findById(id: string) {
return db.query.patients.findFirst({
where: eq(patients.id, id),
with: { appointments: true },
});
}
async findByClinic(clinicId: string, opts: { page: number; limit: number }) {
const offset = (opts.page - 1) * opts.limit;
return db.query.patients.findMany({
where: and(
eq(patients.clinicId, clinicId),
isNull(patients.deletedAt) // Soft delete filter
),
limit: opts.limit,
offset,
orderBy: desc(patients.createdAt),
});
}
}
Transaction Pattern
// Wrap related operations
async function createAppointmentWithNotification(data: CreateAppointmentInput) {
return db.transaction(async (tx) => {
const appointment = await tx.insert(appointments).values(data).returning();
await tx.insert(notifications).values({
userId: data.patientId,
type: 'APPOINTMENT_CREATED',
data: { appointmentId: appointment[0].id },
});
return appointment[0];
});
}
Avoid useEffect for State Derivation
useEffect is overused. Most "state sync" can be done without it.
// ❌ BAD: useEffect to derive state
function UserList({ users }: { users: User[] }) {
const [filteredUsers, setFilteredUsers] = useState<User[]>([]);
const [search, setSearch] = useState('');
useEffect(() => {
setFilteredUsers(users.filter(u => u.name.includes(search)));
}, [users, search]);
return <List users={filteredUsers} />;
}
// ✅ GOOD: Derive during render
function UserList({ users }: { users: User[] }) {
const [search, setSearch] = useState('');
// Computed value, no effect needed
const filteredUsers = users.filter(u => u.name.includes(search));
return <List users={filteredUsers} />;
}
// ✅ GOOD: useMemo if expensive
function UserList({ users }: { users: User[] }) {
const [search, setSearch] = useState('');
const filteredUsers = useMemo(
() => users.filter(u => u.name.toLowerCase().includes(search.toLowerCase())),
[users, search]
);
return <List users={filteredUsers} />;
}
When useEffect IS appropriate:
When to AVOID useEffect:
key prop instead// ❌ BAD: Reset state with useEffect
function Form({ userId }: { userId: string }) {
const [formData, setFormData] = useState({});
useEffect(() => {
setFormData({}); // Reset when userId changes
}, [userId]);
}
// ✅ GOOD: Use key to reset
function ParentComponent() {
return <Form key={userId} userId={userId} />;
}
// ❌ BAD: Initialize from props with useEffect
function Editor({ initialContent }: { initialContent: string }) {
const [content, setContent] = useState('');
useEffect(() => {
setContent(initialContent);
}, []);
}
// ✅ GOOD: Initialize in useState
function Editor({ initialContent }: { initialContent: string }) {
const [content, setContent] = useState(initialContent);
}
Component Structure
// Consistent ordering within component files
// 1. Imports
// 2. Types (using type, not interface)
// 3. Component (using function keyword)
// 4. Subcomponents (if small)
// 5. Export
import { useState } from 'react';
import { Button } from '@/components/ui/button';
import type { Patient } from '@/types';
type PatientCardProps = {
patient: Patient;
onEdit: (id: string) => void;
};
export function PatientCard({ patient, onEdit }: PatientCardProps) {
const [isExpanded, setIsExpanded] = useState(false);
return (
<div>
{/* ... */}
</div>
);
}
Prop Patterns
// Destructure with defaults, use function keyword
function Button({
variant = 'primary',
size = 'md',
disabled = false,
children,
...props
}: ButtonProps) {
return <button {...props}>{children}</button>;
}
// Forward ref - exception where arrow is acceptable inside forwardRef
const Input = forwardRef<HTMLInputElement, InputProps>(
function Input({ className, ...props }, ref) {
return <input ref={ref} className={cn(baseStyles, className)} {...props} />;
}
);
// Compound components
function Select({ children }: SelectProps) {
return <div>{children}</div>;
}
Select.Trigger = function SelectTrigger() { /* ... */ };
Select.Content = function SelectContent() { /* ... */ };
Select.Item = function SelectItem() { /* ... */ };
Hook Patterns
// Naming: use + noun/verb
// Always use function keyword
function usePatients(clinicId: string) {
const query = useQuery({ /* ... */ });
return {
patients: query.data ?? [],
isLoading: query.isLoading,
error: query.error,
refetch: query.refetch,
};
}
function useCreateAppointment() {
return useMutation({ /* ... */ });
}
function useDebounce<T>(value: T, delay: number): T {
const [debouncedValue, setDebouncedValue] = useState(value);
useEffect(() => {
const timer = setTimeout(() => setDebouncedValue(value), delay);
return () => clearTimeout(timer);
}, [value, delay]);
return debouncedValue;
}
// Return tuple for simple state
function useToggle(initial = false): [boolean, () => void] {
const [value, setValue] = useState(initial);
const toggle = useCallback(() => setValue(v => !v), []);
return [value, toggle];
}
Server-Side Data Fetching (Next.js)
// Page component fetches data
export default async function PatientsPage() {
const patients = await patientService.findAll();
return <PatientList patients={patients} />;
}
// With error handling
export default async function PatientPage({ params }: { params: { id: string } }) {
const patient = await patientService.findById(params.id);
if (!patient) {
notFound();
}
return <PatientDetail patient={patient} />;
}
Client-Side Data Fetching
// TanStack Query pattern
function usePatients() {
return useQuery({
queryKey: ['patients'],
queryFn: () => fetch('/api/patients').then(r => r.json()),
staleTime: 5 * 60 * 1000, // 5 minutes
});
}
// Mutations
function useCreatePatient() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (data: CreatePatientInput) =>
fetch('/api/patients', {
method: 'POST',
body: JSON.stringify(data),
}).then(r => r.json()),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['patients'] });
},
});
}
Input Validation (Always at boundaries)
// API route entry point
const input = schema.safeParse(body);
if (!input.success) return errorResponse(input.error);
// Never trust client data deeper in the stack
Auth Checks
// Middleware for protected routes
export async function middleware(request: NextRequest) {
const session = await getSession(request);
if (!session && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url));
}
}
// Service-level authorization
async function updatePatient(userId: string, patientId: string, data: UpdatePatientInput) {
const patient = await db.query.patients.findFirst({ where: eq(patients.id, patientId) });
// Check ownership or role
if (patient?.userId !== userId && !await hasRole(userId, 'admin')) {
return { ok: false, error: { code: 'FORBIDDEN' } };
}
// Proceed with update
}
SQL Injection Prevention
// ✅ Parameterized (Drizzle/Prisma do this automatically)
db.query.users.findFirst({ where: eq(users.email, userInput) });
// ❌ Never interpolate user input
db.execute(`SELECT * FROM users WHERE email = '${userInput}'`); // DANGER
Environment Variables
// Validate at startup
import { z } from 'zod';
const envSchema = z.object({
DATABASE_URL: z.string().url(),
JWT_SECRET: z.string().min(32),
NEXT_PUBLIC_API_URL: z.string().url(),
});
export const env = envSchema.parse(process.env);
// Use validated env
import { env } from '@/lib/env';
console.log(env.DATABASE_URL); // Type-safe
Structured Logging (Class-Based Logger)
import { Logger, createRequestLogger } from '@/lib/logger';
// Create logger with request context
const log = createRequestLogger({ requestId: crypto.randomUUID() });
// Add context as you progress (accumulates)
log.addContext({ userId: session.user.id });
log.addContext({ orderId: order.id });
// All logs include accumulated context
log.info('Order created');
// Output: {"level":"info","message":"Order created","requestId":"...","userId":"...","orderId":"...","timestamp":"..."}
log.error('Payment failed', { error: err.message, stack: err.stack });
Request Logging with Accumulating Context
export async function handler(req: Request) {
const log = createRequestLogger({
requestId: crypto.randomUUID(),
method: req.method,
path: new URL(req.url).pathname,
});
// Add user after auth
const session = await getSession();
if (session) log.addContext({ userId: session.userId });
// Time the operation
const done = log.time('Request processed');
const result = await processRequest(req, log);
done({ status: result.status });
return result;
}
Code Comments
// ✅ Explain WHY, not WHAT
// We retry 3 times because the payment gateway has intermittent 503s
const MAX_RETRIES = 3;
// ❌ Useless comment
// Set max retries to 3
const MAX_RETRIES = 3;
// ✅ Document non-obvious behavior
/**
* Returns appointments for the next 7 days.
* Excludes cancelled appointments.
* Results are cached for 5 minutes.
*/
async function getUpcomingAppointments(patientId: string) {}
README per Feature
# features/appointments/README.md
## Overview
Handles appointment scheduling, rescheduling, and cancellation.
## Key Files
- `appointments.service.ts` - Business logic
- `appointments.schema.ts` - Validation schemas
- `components/` - UI components
## Domain Rules
- Appointments must be at least 24h in advance
- Max 3 appointments per patient per day
- Cancellation allowed up to 2h before
## API Endpoints
- POST /api/appointments - Create
- PATCH /api/appointments/:id - Update
- POST /api/appointments/:id/cancel - Cancel
"Before we write any code, I want to understand what we're building and make sure we make good foundational decisions. This might take 15-30 minutes but will save hours later. Let's start with the big picture — what are we building and who is it for?"
"Let me summarize what we've decided:
**Project**: [One sentence]
**Stack**: [Frontend] + [Backend] + [Database]
**Auth**: [Approach]
**Hosting**: [Where]
**Key patterns**: [2-3 important conventions]
**Features for MVP**:
1. [Feature]
2. [Feature]
...
Does this capture it? Anything we should revisit before we start building?"
After discovery, create these in the project:
# Project: [Name]
## Overview
[2-3 sentences on what this is]
## Tech Stack
- Frontend: Next.js 15 (App Router)
- Backend: Next.js API Routes
- Database: PostgreSQL (Supabase)
- ORM: Drizzle
- Auth: Lucia + GitHub OAuth
- Styling: Tailwind + shadcn/ui
- Hosting: Vercel
## Key Decisions
- Using Result<T> pattern, services never throw
- All dates UTC, convert in frontend
- Feature-based folder structure
- Direct imports, no barrel exports
## Code Patterns
[Document specific patterns agreed on]
## Features
- [ ] Auth (GitHub OAuth)
- [ ] User profile
- [ ] ...
# Code Patterns
## Core Rules (Always Follow)
### DRY — Don't Repeat Yourself
If you write the same logic twice, extract it.
### TypeScript
\`\`\`typescript
// Always use type, never interface
type User = {
id: string;
name: string;
};
// Always use function keyword
function getUser(id: string) {
return db.users.find(id);
}
function UserCard({ user }: UserCardProps) {
return <div>{user.name}</div>;
}
// No non-null assertions
// ❌ user!.name
// ✅ user?.name ?? 'Unknown'
// No any type — define proper types, use unknown and narrow if types can't be defined
// ❌ data: any
// ✅ data: ApiResponse (define the type)
// ✅ data: unknown (if types can't be defined, then narrow)
\`\`\`
### React
\`\`\`typescript
// No useEffect for state derivation
// ❌ useEffect(() => setFiltered(items.filter(...)), [items])
// ✅ const filtered = items.filter(...)
// ✅ const filtered = useMemo(() => items.filter(...), [items])
\`\`\`
### Error Handling — Use tryCatch Utility
\`\`\`typescript
// lib/try-catch.ts — Required in every project
type Success<T> = { data: T; error: null };
type Failure<E> = { data: null; error: E };
type Result<T, E = Error> = Success<T> | Failure<E>;
export async function tryCatch<T, E = Error>(
promise: Promise<T>,
): Promise<Result<T, E>> {
try {
const data = await promise;
return { data, error: null };
} catch (error) {
return { data: null, error: error as E };
}
}
// Also has: tryCatchSync, withTryCatch, tryCatchRetry, tryCatchWithTimeout
\`\`\`
\`\`\`typescript
// Usage
const { data: user, error } = await tryCatch(getUser(id));
if (error) {
logger.error({ err: error }, 'Failed');
return null;
}
// Sync: const { data, error } = tryCatchSync(() => JSON.parse(str));
// Retry: await tryCatchRetry(() => fetch(url), { maxRetries: 3 });
// Timeout: await tryCatchWithTimeout(fetch(url), 5000);
\`\`\`
### File Size Limits
| File Type | Max LOC |
|-----------|---------|
| Components | 150-200 |
| Hooks | 80-100 |
| API Routes | 80-100 |
| Services | 200-250 |
| Utils | 100-150 |
| Types | 150-200 |
When file exceeds limit → split into folder with multiple files.
### Code Quality
- No comments unless logic is complex (explain WHY, not WHAT)
- No emoji in logs or code
- Use IDE TypeScript integration to check errors for small changes, use `typecheck` for big changes if present
- Review code after making changes
- Run /code-review after tasks
### Database
- Use Drizzle query builder, not raw SQL
- Never run db:push, db:migrate, db:generate without permission
## Best Practices
\`\`\`typescript
// Small functions — one function = one job
// If too big, divide and compose
async function handleOrder(data) {
const validated = validateOrder(data); // one job
const order = await createOrder(validated); // one job
await sendConfirmation(order); // one job
return order;
}
// Early returns over nesting
if (!user) return null;
if (!user.isActive) return null;
return processUser(user);
// Parallel async when independent
const [user, posts] = await Promise.all([getUser(id), getPosts(id)]);
// No magic numbers
const MAX_RETRIES = 3;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;
// Meaningful names
const activeUsers = users.filter(u => u.isActive); // not "arr" or "data"
// Boolean prefixes
const isLoading = true;
const hasPermission = false;
const canDelete = user.role === 'admin';
// const over let
const user = await getUser(id);
// No nested ternaries — use lookup objects or early returns
// Named exports
export function UserCard() {} // not export default
// Destructuring
function greet({ firstName, lastName }: User) {}
// Template literals
const msg = \`Hello \${name}\`; // not 'Hello ' + name
// Structured logging (pino) — context FIRST, then message
logger.info({ userId, email }, 'User created');
\`\`\`
## Conventions
### Null vs Undefined
- \`null\` = intentional absence ("I set this to nothing")
- \`undefined\` = optional/not set
### Dates
- Store as UTC in database
- Transport as ISO strings in API
- Convert to local only in UI
### Types
- Use \`import type\` for type-only imports
- Zod schema = source of truth, derive types with \`z.infer<>\`
### Git Commits
\`feat:\`, \`fix:\`, \`refactor:\`, \`chore:\`, \`docs:\`, \`test:\`
## Naming
- Files: kebab-case (\`user-service.ts\`)
- Components: PascalCase (\`UserCard.tsx\`)
- Functions: camelCase, verb-first (\`getUserById\`)
- DB tables: snake_case, plural (\`medical_records\`)
- Env vars: SCREAMING_SNAKE (\`DATABASE_URL\`)
## Imports
Order: node → external → @/ aliases → relative → types
\`\`\`typescript
import path from 'path';
import { z } from 'zod';
import { db } from '@/lib/db';
import { validate } from './utils';
import type { User } from '@/types';
\`\`\`
## Service Layer — Result Pattern
\`\`\`typescript
type Result<T, E = AppError> = { ok: true; data: T } | { ok: false; error: E };
async function createUser(data): Promise<Result<User>> {
if (exists) return { ok: false, error: { code: 'EXISTS' } };
return { ok: true, data: user };
}
\`\`\`
## API Responses
\`\`\`typescript
// Success
{ "data": { ... } }
// Error
{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } }
\`\`\`
## Required Files
- \`lib/try-catch.ts\` — tryCatch utilities
- \`lib/errors.ts\` — standard error types
- \`lib/logger.ts\` — class-based Logger with accumulating context
- \`lib/env.ts\` — validated env vars
## After Task Complete
1. Use IDE to check for TS errors in changed files (use \`typecheck\` for big changes if present)
2. Review code logic
3. Run /code-review command
src/
app/
components/
ui/
lib/
db.ts
env.ts
errors.ts ← Standard error types
logger.ts ← pino structured logging
try-catch.ts ← Error handling utility
features/
types/
Create these files in every new project:
lib/try-catch.ts
type Success<T> = { data: T; error: null };
type Failure<E> = { data: null; error: E };
type Result<T, E = Error> = Success<T> | Failure<E>;
// Async operations
export async function tryCatch<T, E = Error>(
promise: Promise<T>,
): Promise<Result<T, E>> {
try {
const data = await promise;
return { data, error: null };
} catch (error) {
return { data: null, error: error as E };
}
}
// Sync operations (JSON.parse, etc.)
export function tryCatchSync<T, E = Error>(
fn: () => T,
): Result<T, E> {
try {
const data = fn();
return { data, error: null };
} catch (error) {
return { data: null, error: error as E };
}
}
// Wrap existing functions to make them safe
export function withTryCatch<TArgs extends unknown[], TReturn, E = Error>(
fn: (...args: TArgs) => Promise<TReturn>,
): (...args: TArgs) => Promise<Result<TReturn, E>> {
return async (...args: TArgs) => tryCatch<TReturn, E>(fn(...args));
}
// Retry with exponential backoff
export async function tryCatchRetry<T, E = Error>(
promise: () => Promise<T>,
options: { maxRetries?: number; delayMs?: number; backoff?: boolean } = {},
): Promise<Result<T, E>> {
const { maxRetries = 3, delayMs = 1000, backoff = true } = options;
let lastError: E | null = null;
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const { data, error } = await tryCatch<T, E>(promise());
if (!error) return { data, error: null };
lastError = error;
if (attempt < maxRetries) {
const delay = backoff ? delayMs * Math.pow(2, attempt) : delayMs;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
return { data: null, error: lastError as E };
}
// With timeout
export async function tryCatchWithTimeout<T, E = Error>(
promise: Promise<T>,
timeoutMs: number,
): Promise<Result<T, E>> {
const timeout = new Promise<never>((_, reject) => {
setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
});
return tryCatch<T, E>(Promise.race([promise, timeout]));
}
lib/env.ts
import { z } from 'zod';
const envSchema = z.object({
DATABASE_URL: z.string().url(),
// Add other required env vars
});
export const env = envSchema.parse(process.env);
lib/errors.ts
// Standard error structure
export type AppError = {
code: string; // Machine-readable: 'USER_NOT_FOUND'
message: string; // Human-readable
cause?: unknown; // Original error
meta?: Record<string, unknown>;
};
// Domain error codes (add per domain)
export const USER_ERRORS = {
NOT_FOUND: 'USER_NOT_FOUND',
ALREADY_EXISTS: 'USER_ALREADY_EXISTS',
INVALID_CREDENTIALS: 'USER_INVALID_CREDENTIALS',
} as const;
// Helper to create errors
export function createError(
code: string,
message: string,
meta?: Record<string, unknown>
): AppError {
return { code, message, meta };
}
lib/logger.ts
// pnpm add pino pino-pretty
// Class-based logger with accumulating context, pino under the hood
import pino from 'pino';
import type { Logger as PinoLogger } from 'pino';
const baseLogger: PinoLogger = pino({
level: process.env.LOG_LEVEL ?? (process.env.NODE_ENV === 'production' ? 'info' : 'debug'),
transport: process.env.NODE_ENV !== 'production'
? { target: 'pino-pretty', options: { colorize: true } }
: undefined,
});
export class Logger {
private context: Record<string, unknown>;
private pino: PinoLogger;
constructor(initialContext = {}, pinoInstance?: PinoLogger) {
this.context = { ...initialContext };
this.pino = pinoInstance ?? baseLogger;
}
addContext(context: Record<string, unknown>): this {
this.context = { ...this.context, ...context };
return this;
}
child(additionalContext = {}): Logger {
return new Logger({ ...this.context, ...additionalContext }, this.pino);
}
info(message: string, context?: Record<string, unknown>): void {
this.pino.info({ ...this.context, ...context }, message);
}
error(message: string, context?: Record<string, unknown>): void {
this.pino.error({ ...this.context, ...context }, message);
}
// Also: warn(), debug(), trace(), fatal(), time(), timeAsync(), scope()
}
export const logger = new Logger();
export function createRequestLogger(ctx = {}) {
return new Logger({ requestId: crypto.randomUUID(), ...ctx });
}
tsconfig.json with strict mode + path aliases.env.example with all required varsdrizzle.config.ts (if using Drizzle).eslintrc with import ordering.prettierrc for formatting