Claude Code in Practice (1): Context is Everything

// Doesn't know where to put it
// src/login.ts? pages/login.tsx? auth/index.js?
// Generates code that doesn't match existing style
// Rewrites utility functions that already exist

// Creates in src/features/auth/ (follows existing structure)
// Applies project's error handling patterns
// Extends existing useAuth hook
// Uses team naming conventions

project/
├── CLAUDE.md              # Root (entire project)
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md      # Frontend-specific
│   └── backend/
│       └── CLAUDE.md      # Backend-specific
└── .claude/
    └── settings.json      # Claude Code settings

# Project: E-commerce Platform

## Tech Stack
- Frontend: Next.js 14 (App Router), TypeScript, Tailwind
- Backend: Node.js, Prisma, PostgreSQL
- Infra: Vercel, AWS RDS

## Architecture
Monorepo structure. Frontend and backend are separated.
Shared types are managed in `packages/shared`.

## Folder Structure

src/
├── app/           # Next.js App Router pages
├── components/
│   ├── ui/        # Reusable UI components (Button, Input, etc.)
│   └── features/  # Feature-specific components (ProductCard, CartItem)
├── hooks/         # Custom hooks
├── lib/           # Utilities, API client
├── stores/        # Zustand stores
└── types/         # TypeScript type definitions

## Coding Conventions

### Naming
- Components: PascalCase (ProductCard.tsx)
- Hooks: camelCase with "use" prefix (useAuth.ts)
- Utilities: camelCase (formatPrice.ts)
- Constants: SCREAMING_SNAKE_CASE

### Component Guidelines
- Define Props as interface with ComponentNameProps pattern
- Use 'use client' only when truly necessary
- Use Tailwind only (no CSS file creation)

### Error Handling
- All API calls must use try-catch
- Use AppError class from lib/errors.ts
- User messages come from constants/messages.ts

## ⛔ Forbidden

### Never Do This
- No `any` type (use unknown instead)
- No console.log commits (use logger utility)
- No inline styles
- Never modify node_modules or .env files

### Caution
- DB schema changes require migration files
- Discuss new dependencies with team (PNPM only)
- Update OpenAPI spec when adding API endpoints

## Development Commands

monorepo/
├── apps/
│   ├── web/           # Next.js
│   ├── mobile/        # React Native
│   └── admin/         # Admin dashboard
├── packages/
│   ├── ui/            # Shared UI
│   ├── api-client/    # API client
│   └── shared/        # Shared types/utils
└── services/
    ├── auth/          # Auth service
    ├── payment/       # Payment service
    └── notification/  # Notification service

# apps/web/CLAUDE.md

## What is this package?
Next.js 14 main web application.
B2C customer-facing e-commerce frontend.

## Dependencies
- @monorepo/ui: Shared UI components
- @monorepo/api-client: API calls
- @monorepo/shared: Type definitions

## When working in this package
- Modify UI components in packages/ui
- Add new API types to packages/shared
- Only create local components within this package

❌ "Add login feature"

✅ "Add a login page to apps/web.
   Use authApi from @monorepo/api-client,
   and use Button, Input components from @monorepo/ui."

"Improve the useAuth hook.
 Reference: @src/hooks/useAuth.ts @src/lib/api/auth.ts"

// pages/product/[id].js (Uses Pages Router - but project uses App Router!)
import React from 'react';
import axios from 'axios';  // Project uses fetch!

export default function ProductPage({ product }) {
  return (
    <div style={{ padding: '20px' }}>  {/* Inline styles! */}
      <h1>{product.name}</h1>
      <p>${product.price}</p>  {/* formatPrice util exists! */}
    </div>
  );
}

export async function getServerSideProps({ params }) {  // SSR not SSG */
  const res = await axios.get(`/api/products/${params.id}`);
  return { props: { product: res.data } };
}

// app/products/[id]/page.tsx
import { getProduct } from '@/lib/api/products';
import { formatPrice } from '@/lib/utils/format';
import { ProductImage } from '@/components/features/ProductImage';
import { AddToCartButton } from '@/components/features/AddToCartButton';

interface Props {
  params: { id: string };
}

export default async function ProductPage({ params }: Props) {
  const product = await getProduct(params.id);

  return (
    <div className="container mx-auto px-4 py-8">
      <div className="grid grid-cols-1 md:grid-cols-2 gap-8">
        <ProductImage src={product.imageUrl} alt={product.name} />
        <div className="space-y-4">
          <h1 className="text-3xl font-bold">{product.name}</h1>
          <p className="text-2xl text-primary">
            {formatPrice(product.price)}
          </p>
          <p className="text-gray-600">{product.description}</p>
          <AddToCartButton productId={product.id} />
        </div>
      </div>
    </div>
  );
}

# [Project Name]

## Overview
[One-line project description]

## Tech Stack
- Language:
- Framework:
- Database:
- Infrastructure:

## Folder Structure

## Coding Conventions

### Naming
- Components:
- Functions:
- Constants:

### Styling
- [Specify styling approach]

### Error Handling
- [Specify error handling patterns]

## ⛔ Forbidden
-
-
-

## Common Commands

## Reference Docs
- [Links]