Best Practices und Empfehlungen

You: Install dependencies with pnpm
Claude: Okay, running npm install...
You: Not npm, pnpm!
Claude: Sorry, running pnpm install...

# My Project Name

## Overview
This is an e-commerce backend management system based on Next.js 15, written in TypeScript.

## Tech Stack

- Runtime: Node.js 22 LTS
- Framework: Next.js 15 (App Router)
- Styling: Tailwind CSS v4
- Database: PostgreSQL 16 + Prisma ORM
- Package Manager: pnpm 9
- Testing Framework: Vitest + Playwright

## Common Commands

- Install dependencies: `pnpm install`
- Development server: `pnpm dev` (port 3000)
- Run tests: `pnpm test`
- Lint code: `pnpm lint`
- Database migration: `pnpm prisma migrate dev`
- Production build: `pnpm build`

## Coding Standards

- Strictly use TypeScript, no `any` allowed
- React components use functional style with hooks
- Styles only use Tailwind, no inline styles or CSS files
- All API routes return `{ success: boolean, data?: T, error?: string }`
- Database queries go through the service layer, don't call Prisma directly in routes
- Commit message format: `feat:` / `fix:` / `docs:` / `refactor:` prefixes

## Project Structure

- `src/app/` — Pages and API routes (App Router)
- `src/components/` — Reusable UI components
- `src/components/ui/` — Base components (Button, Input, etc.)
- `src/services/` — Business logic layer
- `src/lib/` — Utility functions and configuration
- `prisma/` — Database schema and migration files

## Notes

- Don't manually modify files under `prisma/migrations/`
- Environment variables are in `.env.local` (not committed to Git)
- API authentication middleware is in `src/middleware.ts`
- Image assets go in `public/images/`, use next/image component for loading

/init

# .claudeignore

# Dependency directories
node_modules/
vendor/
.venv/

# Build outputs
dist/
build/
.next/
out/

# Large data files
*.sql
*.csv
*.sqlite
data/

# Binary and media files
*.jpg
*.png
*.mp4
*.zip

# Auto-generated code
generated/
*.gen.ts
prisma/migrations/

# Logs
logs/
*.log

## Project Structure
src/
├── app/                 # Next.js App Router
│   ├── (auth)/          # Pages requiring authentication
│   ├── (public)/        # Public pages
│   └── api/             # API routes
├── components/
│   ├── ui/              # Base UI components (shadcn/ui)
│   ├── forms/           # Form components
│   └── layouts/         # Layout components
├── services/            # Business logic (one file per module)
├── hooks/               # Custom React hooks
├── lib/                 # Utility functions
│   ├── auth.ts          # Authentication related
│   ├── db.ts            # Database connection
│   └── validators.ts    # Zod schema definitions
└── types/               # TypeScript type definitions

Look at @src/services/order-service.ts and @src/types/order.ts,
then add a cancel order method to order-service, checking if the order status allows cancellation.

@src/services/auth.ts       # Reference a single file
@src/components/            # Reference an entire directory
@package.json               # Reference a config file
@https://nextjs.org/docs    # Reference online docs (will fetch content)

# Not recommended: asking for too much at once
"Add avatar upload to the user module, and while you're at it tweak the login page styles,
also add debounce to that search box, and oh, update the password reset email template too."

# Recommended: do it step by step
Step 1: "Add avatar upload to UserProfile component, use S3 for storage"
Step 2: "Update login page styles, refer to @docs/design-spec.md for the design"
Step 3: "Add 300ms debounce to the search box using a custom hook"
Step 4: "Update password reset email template, match the style of @src/templates/welcome.html"

# Step 1: Understand first
"Read @src/services/payment-service.ts and explain the current payment flow processing logic,
especially error handling and retry mechanisms. Don't modify any code."

# Step 2: Plan next
"Based on your understanding, I want to add WeChat Pay as a payment channel.
Please create a modification plan, listing what needs to be changed."

# Step 3: Execute modifications
"The plan looks good, let's start. Modify payment-service.ts first."

[Plan Mode]
I need to add an RBAC (Role-Based Access Control) permission system to the existing system.
Currently users only have admin and user roles. I need to support custom roles and fine-grained permissions.
Please analyze the existing code first and create a detailed implementation plan.

/compact    # Compress current conversation history, keeping key information, freeing up context space
/clear      # Completely clear conversation history, start fresh

# When to use:
# - Switching to a completely different task → /clear
# - Same task but conversation is too long → /compact
# - Feeling Claude's responses are getting worse (context overload) → /compact
# - Just finished one feature, starting the next → /clear

/review

I just modified the cancel order logic in @src/services/order-service.ts.
Please write unit tests for this method, covering the following scenarios:
1. Normal cancellation of an unshipped order
2. Attempt to cancel a shipped order (should fail)
3. Cancel a non-existent order
4. Concurrent cancellation of the same order

# Round 1: Overall review
"Review the latest changes to @src/services/payment-service.ts,
focusing on security and error handling."

# After making changes based on feedback, round 2:
"Please review the modified code again, this time focusing on performance and edge cases."

# Round 3 (optional): Comparison review
"Compare the code before and after changes to confirm all issues are fixed and no new problems were introduced."

Got an error when running pnpm build, full error log below:

This error occurs in @src/app/api/user/route.ts.
I suspect it's a session type definition issue, please check.

# Step 1: Diagnose
"Users report that they occasionally get redirected to a 404 page after logging in.
Please check @src/middleware.ts and @src/app/(auth)/layout.tsx,
and analyze what might be causing this issue. Don't modify code yet."

# Step 2: Confirm the cause, then fix
"Your analysis makes sense—it's indeed a redirect logic issue when the session expires.
Please fix this issue and add appropriate error logging to help with future troubleshooting."

Look at this screenshot @screenshot.png—the last column text in the table is being cut off.
Please check the styles in @src/components/DataTable.tsx and fix this issue.

/commit

/commit
# Claude's generated message not good enough?
"Please make the commit message more detailed, explaining why this logic was changed"

# 1. Create feature branch
git checkout -b feature/order-cancel

# 2. Start Claude Code development
claude

# 3. Multiple small commits during development
> "Implement basic order cancellation logic"
> /commit

> "Add cancel reason field and validation"
> /commit

> "Add unit tests for order cancellation"
> /commit

# 4. Finish development, create PR
> Create a Pull Request for the current branch, summarize all commit changes, generate a standardized PR description

# Add this rule in CLAUDE.md:
## Git Standards

- All modifications must be done on feature branches, don't modify main branch directly
- Branch naming: feature/xxx, fix/xxx, refactor/xxx
- Run `pnpm lint && pnpm test` before committing to ensure everything is fine

# CLAUDE.md in project root → commit to Git
git add CLAUDE.md
git commit -m "docs: add CLAUDE.md project configuration"

# Personal preference configs → put in .claude/CLAUDE.md, add to .gitignore
echo ".claude/CLAUDE.md" >> .gitignore

## PR Review Standards
When reviewing code, check the following aspects:
1. **Functional correctness**: Does it fully implement the requirements?
2. **Error handling**: Are edge cases covered?
3. **Security**: Any risks of SQL injection, XSS, permission bypass?
4. **Performance**: Any unnecessary database queries or memory leaks?
5. **Test coverage**: Do new code changes have corresponding tests?
6. **Code style**: Does it conform to project standards?
7. **Documentation**: Do public APIs have JSDoc comments?

## Code Style

- Naming: Components use PascalCase, functions/variables use camelCase, constants use UPPER_SNAKE_CASE
- File names: Component files use PascalCase (e.g., UserAvatar.tsx), others use kebab-case
- Import order: React → third-party libraries → internal modules → types → styles
- Maximum function length: 50 lines, split if exceeded
- Define interface when component props exceed 3

# .claude/commands/review-security.md
Please conduct a security review of the following code, focusing on:
1. SQL injection risks
2. XSS attack surface
3. CSRF protection
4. Completeness of permission checks
5. Whether sensitive data is encrypted
6. Whether sensitive information is leaked in logs

Review scope: $ARGUMENTS

/review-security @src/app/api/

I need to add a coupon feature to the order system, involving the following files:

- @src/types/coupon.ts — new, define coupon types
- @src/services/coupon-service.ts — new, coupon business logic
- @src/services/order-service.ts — modify, apply coupon during checkout
- @src/app/api/coupons/route.ts — new, coupon API
- @prisma/schema.prisma — modify, add Coupon model

Please handle them in the order above, and tell me after completing each file.

[Using Opus model]
I'm considering migrating the current REST API to GraphQL.
Please analyze the pros and cons in depth, considering the following factors:
1. Migration cost for existing 50+ API endpoints
2. Benefits of frontend query optimization
3. Changes in caching strategy
4. Team learning curve
5. Integration plan with existing React Query

No need to write code, give me a detailed technical analysis report.

After completing the modifications, please:
1. Run pnpm lint to check for formatting issues
2. Run pnpm test to confirm existing tests still pass
3. If there are type errors, fix them yourself