Задача

Вы запускаете новый проект и хотите работать с Claude Code, Cursor, Windsurf или другим AI-агентом. Но вместо умного коллеги получаете незнакомца, который не знает ваш стек, игнорирует архитектурные решения и нарушает соглашения о коде.

Причина одна: агент не прошёл онбординг.

CLAUDE.md (или .cursorrules, AGENTS.md — зависит от инструмента) — это файл, который агент читает перед каждой задачей. Он заменяет недели совместной работы. Правильно составленный CLAUDE.md превращает AI-кодера из стажёра в опытного тимлида, знающего каждый уголок вашего проекта.

Проблема: написать хороший CLAUDE.md с нуля — задача на 2–3 часа вдумчивой работы. Этот промпт делает её за 10 минут.

Для кого

  • Разработчики, практикующие вайб-кодинг с Claude Code, Cursor, Windsurf, Aider
  • Технические основатели стартапов, которые пишут код с AI и хотят получать стабильный результат
  • Тимлиды, стандартизирующие работу команды с AI-агентами
  • Фрилансеры, которые быстро переключаются между проектами

Промпт

Ты — опытный тимлид и архитектор программного обеспечения. Твоя задача — создать CLAUDE.md (онбординг-файл для AI-агентов) для нового проекта на основе моих ответов.

Задай мне следующие вопросы по одному, дожидаясь моего ответа:

1. Как называется проект и в чём его суть (2–3 предложения)?
2. Какой технологический стек используется (языки, фреймворки, база данных, инфраструктура)?
3. Какова структура директорий проекта? (можешь запросить вывод `tree -L 3`)
4. Какие команды для разработки, тестирования и деплоя нужно знать агенту?
5. Какие архитектурные решения уже приняты и почему (важные паттерны, что нельзя менять)?
6. Какие соглашения о коде соблюдаются (именование, форматирование, линтеры)?
7. Что агент должен делать ВСЕГДА (e.g. писать тесты, обновлять документацию)?
8. Что агент должен НИКОГДА не делать (e.g. не изменять схему БД без явного разрешения)?
9. Есть ли чувствительные файлы или области кода, которые нельзя трогать?
10. Какой стиль взаимодействия предпочтителен (краткие ответы vs подробные объяснения)?

После получения всех ответов сгенерируй CLAUDE.md в формате markdown, структурированный по разделам:
- Project Overview
- Tech Stack
- Commands (dev, test, build, deploy)
- Architecture & Key Decisions
- Code Conventions
- Always / Never rules
- Sensitive Areas

Файл должен быть написан на том же языке, что мои ответы. Будь конкретным, избегай воды. Каждое правило — одна строка. Предпочитай bullet-списки прозе.
💡 Один промпт — два режима
Если хотите ускорить процесс — вставьте сразу все ответы одним блоком текста. Агент сам разберёт структуру. Диалоговый режим удобен для рефлексии над проектом, batch-режим — когда архитектура уже в голове.

Пример результата

Вот фрагмент CLAUDE.md, сгенерированного промптом для SaaS-стартапа на Next.js + Supabase:

# Project Overview
**Taskflow** — B2B SaaS для управления задачами команд. MVP для 10–50 пользователей.
Монорепо: фронтенд (Next.js 15 App Router) + Edge Functions (Supabase).

# Tech Stack
- Frontend: Next.js 15 (App Router), TypeScript 5, Tailwind CSS 4, shadcn/ui
- Backend: Supabase (Postgres + Auth + Realtime + Edge Functions)
- State: Zustand + React Query (TanStack v5)
- Tests: Vitest + Playwright
- Deploy: Vercel (prod), Railway (staging)

# Commands
```bash
npm run dev          # Dev server :3000
npm run test         # Vitest unit tests
npm run test:e2e     # Playwright (requires running dev)
npm run db:migrate   # Apply Supabase migrations
npm run db:reset     # Reset local DB (DESTRUCTIVE)

Always

  • Write Vitest unit tests for every utility function
  • Use server components by default; client components only when needed
  • Run npm run lint before reporting task complete
  • Check RLS policies when touching Supabase queries

Never

  • Never use any TypeScript type without a TODO comment explaining why
  • Never modify /supabase/migrations/ — create new migration files instead
  • Never store secrets in code — use .env.local and Vercel env vars
  • Never use useEffect for data fetching — use React Query

> Хорошо составленный CLAUDE.md сокращает количество итераций с агентом в 2–3 раза. Агент перестаёт переспрашивать и начинает принимать решения в рамках ваших правил.

---

## Как это работает: схема процесса



graph TD
    A[Запускаешь промпт] --> B{Режим}
    B -->|Диалог| C[Агент задаёт 10 вопросов]
    B -->|Batch| D[Передаёшь описание проекта сразу]
    C --> E[Отвечаешь по одному]
    D --> F[Агент анализирует текст]
    E --> G[Агент генерирует CLAUDE.md]
    F --> G
    G --> H[Ревью: убираешь лишнее, добавляешь специфику]
    H --> I[Помещаешь в корень проекта]
    I --> J[AI-агент читает файл автоматически]
    J --> K[Работает как опытный тимлид]
    K --> L{Проект меняется?}
    L -->|Да| M[Обновляешь CLAUDE.md]
    M --> J
    L -->|Нет| K


---
## Вариации и настройки
### Версии под разные инструменты
| Инструмент | Файл | Особенности |
|------------|------|-------------|
| Claude Code | `CLAUDE.md` | Поддерживает иерархию: `~/.claude/CLAUDE.md` → проект → директория |
| Cursor | `.cursorrules` | Один файл, без иерархии; поддерживает `@docs` ссылки |
| Windsurf | `.windsurfrules` | Аналогично Cursor; хорошо работает с `@codebase` |
| Aider | `CONVENTIONS.md` | Можно передавать через `--read` флаг |
| GitHub Copilot | `.github/copilot-instructions.md` | Workspace-уровень; доступен через VS Code |
| OpenHands | `AGENTS.md` | Специфичный формат с секцией `[AGENT]` |
### Специализированные версии промпта
**Для легаси-проекта** — добавьте в начало:

Перед вопросами проанализируй структуру проекта (я предоставлю вывод tree и ключевые файлы) и выдели технический долг, о котором агент должен знать.


**Для команды** — добавьте в конец:

Добавь раздел “Team Conventions” с правилами: ветки Git, формат коммитов, процесс code review, кто reviewer по каким областям кода.


**Для монорепо** — добавьте:

Создай отдельный CLAUDE.md для каждого пакета/приложения плюс корневой файл с общими правилами.







  
ℹ Иерархия файлов в Claude Code

  
Claude Code читает CLAUDE.md в порядке: ~/.claude/CLAUDE.md (глобальные предпочтения) → {project}/CLAUDE.md (проект) → {subdirectory}/CLAUDE.md (поддиректория). Используйте это для разных правил в frontend/ и backend/.





---

## Советы по улучшению

### 1. Начинайте с команд, а не с описания

Раздел `Commands` — самый ценный. Агент должен знать, как запустить тесты, как применить миграции, как собрать проект. Без этого он будет угадывать.

### 2. Правило "Always / Never" важнее архитектуры

Длинные описания архитектуры агент забывает в середине задачи. Но короткие правила `NEVER modify migrations` или `ALWAYS run lint before done` — соблюдает стабильно.

### 3. Обновляйте файл как код

CLAUDE.md — живой документ. Заведите привычку: после каждого инцидента ("агент снова нарушил это правило") — добавляйте явный запрет в файл. Через месяц работы ваш CLAUDE.md станет точным слепком вашей инженерной культуры.

### 4. Проверяйте через "новичка"

Дайте готовый CLAUDE.md свежей сессии агента и попросите: "Расскажи, что ты узнал о проекте из этого файла". Пробелы в понимании — пробелы в файле.






  
⚠ Не переусердствуйте

  
CLAUDE.md длиннее 500 строк снижает эффективность — агент тратит слишком много контекстного окна на чтение правил. Оптимальный объём: 100–200 строк. Всё остальное — в отдельные файлы (ARCHITECTURE.md, API_DOCS.md) с ссылками из CLAUDE.md.





### 5. Используйте `@`-ссылки в Cursor

В `.cursorrules` можно ссылаться на документацию: `@docs https://nextjs.org/docs`. Cursor подгрузит актуальные доки прямо в контекст агента — это снижает галлюцинации при работе с быстро меняющимися API.

---

## Сравнение: с CLAUDE.md и без

| Ситуация | Без CLAUDE.md | С CLAUDE.md |
|----------|---------------|-------------|
| Агент выбирает библиотеку | Случайный выбор | Всегда ваш стек |
| Именование переменных | Смешанный стиль | Соответствует конвенциям |
| Работа с БД | Может изменить схему | Знает про миграции |
| Завершение задачи | Без проверок | Запускает линтер и тесты |
| Количество итераций | 5–8 правок | 1–2 правки |
| Контекстные вопросы | Постоянно переспрашивает | Принимает решения сам |

---