Шпаргалка: структура проекта для Claude Code

Claude Code читает контекст и правила прямо из вашего репозитория. Чем аккуратнее устроен проект, тем стабильнее и предсказуемее работает агент: он знает команды сборки, ваши конвенции, границы прав и подключённые инструменты. Ниже — практическая шпаргалка: какие файлы и папки завести и что в них класть. Всё сверено с официальной документацией Claude Code.

Общая структура проекта

Минимальный «скелет» проекта под Claude Code выглядит так:

my-project/
├── CLAUDE.md               # правила и контекст проекта (агент читает каждую сессию)
├── CLAUDE.local.md         # личные заметки, НЕ коммитим (в .gitignore)
├── .mcp.json               # MCP-серверы проекта — в КОРНЕ, не в .claude/
├── .worktreeinclude        # какие gitignored-файлы копировать в новый worktree
└── .claude/
    ├── settings.json        # разрешения, хуки, env, модель (командные, коммитим)
    ├── settings.local.json  # личные переопределения (НЕ коммитим)
    ├── rules/               # тематические правила (*.md), грузятся по надобности
    ├── skills/              # скиллы: папка со SKILL.md, вызов /имя-скилла
    ├── commands/            # слэш-команды *.md (устаревают — лучше skills)
    ├── agents/              # субагенты (*.md с frontmatter)
    ├── workflows/           # JS-скрипты оркестрации (из команды /workflows)
    └── output-styles/       # стили вывода (чаще личные, в ~/.claude/)

Есть ещё пользовательский уровень — ~/.claude/ в домашней папке (свои CLAUDE.md, settings.json, скиллы), который применяется ко всем вашим проектам. Проектные файлы имеют приоритет над пользовательскими.

CLAUDE.md — правила проекта

CLAUDE.md — это память проекта: агент подхватывает файл в начале каждой сессии как руководство (не жёсткая конфигурация, а инструкции). Держите его в корне (./CLAUDE.md) или в ./.claude/CLAUDE.md, чтобы не засорять корень.

Что полезно туда класть:

• команды сборки и тестов (npm run build, npm test и т.п.);
• конвенции кода (отступы, именование, стиль экспортов);
• архитектуру и раскладку файлов проекта;
• специфику стека (например, «React 19, TypeScript strict»);
• правила и запреты, которых придерживается команда.

Иерархия (грузится сверху вниз): ~/.claude/CLAUDE.md (пользовательский, для всех проектов) → ./CLAUDE.md или ./.claude/CLAUDE.md (проектный, командный, коммитим) → ./CLAUDE.local.md (личные переопределения для этого проекта, в .gitignore). CLAUDE.local.md актуален — это официальный способ держать личные заметки вне коммитов.

Импорты. Внутри можно подключать другие файлы через @путь: например, See @README and @package.json или отдельной строкой @docs/git-instructions.md. Работают относительные и абсолютные пути, до 4 уровней вложенности. Литеральный @ экранируется обратными кавычками.

Размер. Ориентир — до ~200 строк на файл: длиннее грузится целиком, но агент хуже придерживается.

Каталог .claude/

Здесь живёт всё «настроечное». Основное:

• settings.json — разрешения (permissions), хуки, переменные окружения, модель. Командный файл, коммитим.
• settings.local.json — личные переопределения для этого проекта. Не коммитим (Claude Code сам добавляет его в .gitignore и создаёт при первой записи).
• rules/ — тематические правила (*.md). Можно задать paths: во frontmatter — тогда правило подгружается по надобности, когда агент читает подходящий файл (экономит контекст).
• skills/ — скиллы: каждый скилл это папка с SKILL.md и вспомогательными файлами, вызывается как /имя-скилла.
• commands/ — одиночные слэш-команды (*.md → /команда). Постепенно вытесняются скиллами — для нового лучше сразу skills/.
• agents/ — субагенты: каждый *.md с frontmatter описывает отдельного агента с изолированным контекстом.
• workflows/ — скрипты оркестрации на JavaScript (сохраняются из команды /workflows, не пишутся руками).
• output-styles/ — кастомные стили системного промпта (чаще личные, в ~/.claude/output-styles/).

settings.json и settings.local.json

Оба файла — с одинаковой JSON-схемой (разрешения, хуки, env, модель), разница только в области видимости и приоритете:

• settings.json — проектный, командный, коммитим в git;
• settings.local.json — личный, для этого проекта, не коммитим.

Приоритет (от высшего к низшему): корпоративные managed-политики → аргументы CLI → settings.local.json → settings.json → пользовательский ~/.claude/settings.json.

Хуки: автоматизация на события

Хуки настраиваются внутри settings.json (или settings.local.json) — отдельного файла для них нет. Хук — это команда, которая запускается на событие. Пример: после каждого редактирования файла прогонять Prettier:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write $FILE" }
        ]
      }
    ]
  }
}

Событий много: SessionStart, UserPromptSubmit, PreToolUse (может заблокировать вызов инструмента), PostToolUse, Stop, SubagentStop, PreCompact и другие — от старта сессии до отдельных вызовов инструментов.

MCP-серверы

Подключение внешних инструментов по протоколу MCP описывается в .mcp.json. Важный нюанс: он лежит в корне проекта, а не внутри .claude/. Формат:

{
  "mcpServers": {
    "docs": { "type": "http", "url": "https://example.com/mcp" },
    "notion": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": { "NOTION_TOKEN": "${NOTION_TOKEN}" }
    }
  }
}

Области подключения: проектная (.mcp.json, командная, в git), пользовательская (~/.claude.json, для всех проектов) и локальная (личная, для одного проекта). Управлять удобно из терминала: claude mcp add, claude mcp list, claude mcp remove.

С чего начать: минимальный набор

1. Заведите CLAUDE.md с командами сборки/тестов и ключевыми конвенциями.
2. Добавьте .claude/settings.json с разрешениями под ваш процесс.
3. Личное (ключи, эксперименты) выносите в settings.local.json и CLAUDE.local.md — вне коммитов.
4. Нужны внешние инструменты — заведите .mcp.json в корне.
5. Повторяющиеся действия оформляйте скиллами (.claude/skills/) и хуками.

Вывод

Хорошая структура проекта — это не бюрократия, а способ сделать работу агента прозрачной и воспроизводимой: команда видит правила в CLAUDE.md, права и автоматизацию — в settings.json, инструменты — в .mcp.json, а личное остаётся вне репозитория. Начните с малого (CLAUDE.md + settings.json) и наращивайте скиллы, субагентов и хуки по мере надобности.