Урок 3: CLAUDE.md — специфика для Claude

Чему вы научитесь

• Отличие CLAUDE.md от AGENTS.md и когда использовать каждый
• Оптимальный размер и структуру CLAUDE.md
• Как работает иерархия CLAUDE.md файлов (корень, поддиректории, глобальный)
• Стратегию итеративного улучшения на основе ошибок агента

CLAUDE.md vs AGENTS.md

Когда что использовать?

graph TD
    A["У тебя есть проект"] --> B{Есть много<br/>разработчиков?}

    B -->|ДА| C["AGENTS.md"]
    C --> C1["Один файл<br/>для всей команды"]
    C --> C2["Используется<br/>IDE, Copilot,<br/>другими инструментами"]

    B -->|НЕТ| D{Основной<br/>инструмент Claude?}

    D -->|ДА| E["CLAUDE.md"]
    E --> E1["До 300 строк<br/>Быстро читается"]
    E --> E2["Итеративно<br/>улучшается"]

    D -->|НЕТ| F["Можно оба<br/>или только<br/>AGENTS.md"]

    style C fill:#c8e6c9
    style E fill:#fff9c4
    style F fill:#ffccbc

Структура CLAUDE.md

Рекомендуемая структура (гибче, чем AGENTS.md):

# Project Description

# Technology Stack

# Code Style & Conventions

# Key Commands

# Important Rules

# Examples

Полный пример CLAUDE.md для React + TypeScript проекта

# CLAUDE.md

## Project Description

Real-time collaboration app for designers. Users can create projects,
share designs, comment in real-time, and manage versions.

## Technology Stack

- **Frontend:** React 18, TypeScript, Vite, Tailwind CSS
- **State management:** Zustand
- **API client:** axios with interceptors
- **Real-time:** Socket.io client
- **Testing:** Vitest, React Testing Library
- **Build:** Vite
- **Node:** 18+

## Code Style & Conventions

### General
- Language: TypeScript (strict mode)
- Framework: React 18+ with hooks
- Components: Functional components only
- Naming: Components are `PascalCase`, functions are `camelCase`

### Styling
- Framework: Tailwind CSS
- No inline styles
- No CSS files (pure Tailwind)
- Responsive: mobile-first

### File Organization

src/ ├── components/ # React components ├── hooks/ # Custom hooks ├── stores/ # Zustand stores ├── services/ # API calls & utilities ├── types/ # TypeScript types ├── styles/ # Global styles only └── tests/ # Tests mirror src structure

### Imports
- Use absolute imports: `import X from '@/components'`
- Order: React → third-party → local → styles
- Be specific: `import { Button }` not `import *`

### Error Handling
- Always wrap async operations in try-catch
- Return user-friendly error messages
- Log technical errors with context
- Handle network timeouts (30s max)

## Key Commands

```bash
# Development
npm run dev          # Start dev server

# Testing
npm test            # Run tests
npm test -- --ui   # UI mode

# Building
npm run build       # Production build
npm run preview     # Preview build locally

# Quality
npm run lint        # Check TypeScript & ESLint
npm run type-check  # Type checking

Important Rules

DO:

• [+] Use TypeScript strictly (no any)
• [+] Handle errors explicitly
• [+] Test components with React Testing Library
• [+] Use hooks for side effects (useEffect, useCallback)
• [+] Keep components small and focused
• [+] Use Zustand stores for global state
• [+] Add types to all function parameters
• [+] Document complex components

DON’T:

• [-] Don’t use class components
• [-] Don’t hardcode values (use env vars)
• [-] Don’t use inline styles or CSS-in-JS
• [-] Don’t skip error handling
• [-] Don’t log sensitive data to console
• [-] Don’t use setTimeout for logic (use hooks)
• [-] Don’t mutate state directly
• [-] Don’t import from index.ts (import specific files)
• [-] Don’t commit .env or sensitive files

Examples

Good Component with Hook

import { useCallback, useEffect } from 'react';
import { useStore } from '@/stores';
import { Button } from '@/components/ui';

interface DesignPreviewProps {
  designId: string;
}

export function DesignPreview({ designId }: DesignPreviewProps) {
  const design = useStore(state => state.getDesign(designId));
  const updateDesign = useStore(state => state.updateDesign);
  const [isSaving, setIsSaving] = useState(false);

  const handleSave = useCallback(async () => {
    try {
      setIsSaving(true);
      await updateDesign(designId, design);
    } catch (error) {
      console.error('Failed to save design:', error);
      // Show error to user
    } finally {
      setIsSaving(false);
    }
  }, [designId, design, updateDesign]);

  if (!design) return <div>Loading...</div>;

  return (
    <div className="space-y-4">
      <img src={design.preview} alt={design.name} />
      <Button onClick={handleSave} disabled={isSaving}>
        {isSaving ? 'Saving...' : 'Save'}
      </Button>
    </div>
  );
}

Good Service Function

import axios from '@/lib/axios';

export async function fetchDesigns(projectId: string) {
  try {
    const response = await axios.get(`/api/projects/${projectId}/designs`);
    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      throw new Error(error.response?.data?.message || 'Failed to fetch designs');
    }
    throw error;
  }
}

## Иерархия CLAUDE.md файлов

Claude Code читает инструкции из нескольких источников в иерархии (от общего к специфичному):

```mermaid
flowchart LR
  A["~/.claude/CLAUDE.md\n(user-level)"] -->|"конкатенируется"| B["проект/CLAUDE.md\n(project)"]
  B -->|"конкатенируется"| C["папка/CLAUDE.md\n(on-demand)"]
  B --> D[".claude/rules/\n(path-scoped)"]

~/.claude/CLAUDE.md          ← user-level (глобальные инструкции)
~/.claude/rules/             ← глобальные правила с path-scoping
        ↓ конкатенируются
project/
├── CLAUDE.md или ./.claude/CLAUDE.md  ← project-level
├── .claude/rules/                     ← проектные правила (YAML frontmatter)
└── src/
    ├── components/
    │   └── CLAUDE.md  ← подгружается on-demand при работе с файлами папки
    └── services/
        └── CLAUDE.md  ← аналогично, on-demand

Как это работает?

Claude Code конкатенирует инструкции из всех применимых источников:

1. User-level: ~/.claude/CLAUDE.md и ~/.claude/rules/ — глобальные инструкции и правила с path-scoping.
2. Project-level: ./CLAUDE.md или ./.claude/CLAUDE.md + ./.claude/rules/ — проектные инструкции.
3. Subdirectory: src/components/CLAUDE.md — подгружается on-demand, когда Claude работает с файлами этой папки.

Более специфичные инструкции обычно имеют больший вес, но файлы не переопределяют друг друга — они суммируются.

Практика: как итеративно улучшать CLAUDE.md

Сценарий: Claude делает ошибку

Итерация 1:

Запрос: "Создай новый API endpoint для получения пользователя"

Результат:
[-] TypeScript с `any` типами
[-] Без error handling

Действие: Добавьте в CLAUDE.md:

## Important Rules

### DON'T:
- [-] Don't use `any` types (use strict TypeScript)
- [-] Don't skip error handling (always use try-catch)

Итерация 2:

Запрос: "Добавь форму логина"

Результат:
[-] localStorage без проверки SSR

Действие: Добавьте правило:

## Important Rules

### DON'T:
- [-] Don't use localStorage directly (might break SSR)

Процесс улучшения

1. Claude делает ошибку
2. Понимаю проблему
3. Добавляю правило в CLAUDE.md
4. Пробую снова с тем же запросом
5. Проверяю результат
6. Если лучше → готово, если нет → уточняю правило

Ключевые выводы

1. CLAUDE.md специфичен для Claude Code — это инструкции именно для Claude, не для других AI-инструментов.

2. Размер <200 строк критичен — большие файлы потребляют много контекста и снижают точность соблюдения правил. Разбивайте на .claude/rules/ и используйте @imports.

3. Иерархия файлов позволяет иметь глобальные правила (user-level), проектные (project-level) и локальные (subdirectory, on-demand). Файлы конкатенируются, более специфичные инструкции имеют приоритет.

4. Итеративное улучшение — основной способ развития. После каждой ошибки Claude добавьте правило.

5. Примеры важнее описаний — Claude учится на примерах кода быстрее.

6. Начните с малого — даже 50 строк CLAUDE.md лучше его отсутствия.

Следующий урок

Урок 4: GEMINI.md и .cursorrules