Example of instructions for claude code in a nextjs codebase

CLAUDE.md

Arcavel Project Guidelines

Commands

• pnpm dev - Start dev server with Turbopack
• pnpm build - Build for production
• pnpm start - Run production build
• pnpm lint - Run ESLint

Code Style

• Imports: Group imports: 1) React, 2) third-party, 3) local (@/*)
• Naming: Use PascalCase for components, camelCase for functions/variables
• Types: Use TypeScript strictly (strict: true), prefer explicit types
• Components: Use functional components with React hooks
• CSS: Use Tailwind with class-variance-authority for variants
• Error handling: Use try/catch blocks with specific error messages
• Formatting: Use double quotes for JSX, single quotes for regular strings
• Paths: Use absolute imports with @/* aliases unless the module to import is the same directory
• State: Prefer React hooks like useState, useReducer for state management
• Comments: Don't comment on what the code does, make the code self-documenting and only use comments to explain why something is done a certain way. Document APIs, complex algorithms, and non-obvious side effects
• Functions: Prefer functional approach over classes

Architecture

• Next.js 15 app router
• React 19
• Tailwind CSS v4
• Shadcn/UI - Radix UI components customized with Tailwind

Routing

• When receiving URL params in pages, remember they are a promise and must be awaited: https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes

Localization

• All the user-facing content (labels, text, etc..) should be in Spanish

File Organization & Colocation

Principles

• Colocate over centralize: Components used by a single page should live next to that page
• Proximity-based: Group related files by feature/usage, not file type
• Shared sparingly: Only truly reusable components go in central components/ directories
• Flat lib structure: Keep single files in lib/ (e.g., storage.ts, utils.ts) unless logical grouping requires folders (e.g., db/)
• Mixed file types: hooks, utils, and components can live together in the same folder until it becomes too large, only then create internal /hooks and /components directories

Structure Pattern

feature-directory/
├── page.tsx                 # Page component
├── component-name.tsx       # Feature-specific components
├── use-feature-hook.ts      # Feature-specific hooks
├── feature-utils.ts         # Feature-specific utilities
├── actions.ts              # Server actions for this feature
└── types.ts                # Feature-specific types

Decision Rules

Component Usage	Location	Import Style
Single page only	Colocate with page	./component-name
2-3 related pages	Nearest common parent	../component-name
Multiple features	Central components/	@/components/...

Example

src/app/app/
├── components/              # Shared only
│   ├── header.tsx
│   └── media-file-uploader.tsx  # Used by multiple forms
├── new/                     # Organization creation
│   ├── organization-form.tsx    # Colocated
│   ├── actions.ts
│   └── page.tsx
└── [teamSlug]/new/          # Project creation
    ├── project-form.tsx         # Colocated
    ├── actions.ts
    └── page.tsx

# When a folder becomes too large:
feature-directory/
├── components/              # Internal organization
│   ├── form.tsx
│   └── modal.tsx
├── hooks/
│   ├── use-feature.ts
│   └── use-validation.ts
├── page.tsx
└── actions.ts

lib/
├── storage.ts               # Single utility file
├── auth.ts                  # Single utility file
└── db/                      # Folder when logical grouping exists
    ├── schema.ts
    ├── mutations.ts
    └── queries.ts

Implementation Guidelines

• Use early returns whenever possible to make the code more readable.
• Always try to use existing shadcn/ui components and tailwind for styling HTML elements; avoid using CSS or tags.
• Use descriptive variable and function/const names. Also, event functions should be named with a “handle” prefix, like “handleClick” for onClick and “handleKeyDown” for onKeyDown.
• Use consts instead of functions, for example, “const toggle = () =>”. Also, define a type if possible.