Структура .claude/: пять папок, которые делают Claude Code умнее

Claude Code — это терминал-агент, в котором я провожу больше времени чем в любом редакторе. За полгода я заметил одну вещь: агент работает в десять раз лучше когда у него есть структура. Не «лучшие промпты», а правильно организованная папка .claude/ в корне проекта или в домашней директории.

В этой папке живут пять вещей: CLAUDE.md (правила), skills/ (навыки), hooks/ (триггеры), agents/ (делегирование), plugins/ (пакетирование для команды). Каждая закрывает свою болевую точку. Вместе они превращают Claude из «умного чата» в инструмент который помнит твой проект, твой стиль и твои правила.

Гайд из реальной практики. Расскажу что у меня лежит в каждой папке, зачем, и в каком порядке начинать если ты только установил Claude Code.

Карта папки .claude/

Папка живёт в двух местах одновременно:

• ~/.claude/ — глобальная, видна Claude из любой директории. Сюда складываешь всё что должно быть всегда: твой голос, любимые навыки, общие правила.
• .claude/ в корне репозитория — проектная. Видна только когда ты работаешь в этом проекте. Сюда идёт всё что специфично для конкретной кодбазы.

Логика простая: если правило применимо везде — кладёшь в глобальную. Если только в этом репо — в проектную. Claude автоматически загружает обе, проектная имеет приоритет в случае конфликта.

1. CLAUDE.md — конституция агента

Это самый важный файл. Загружается всегда, в каждой сессии, до любого сообщения от тебя. Если ты прописал в нём что-то — Claude уже это знает.

Где живёт: ~/.claude/CLAUDE.md (глобальный) и .claude/CLAUDE.md (проектный).

Что у меня в глобальном

• Язык общения и тон («Общайся на русском, прямо, без воды»)
• Дисциплина редактирования кода («Перед редактированием — прочитай файл», «Перед изменением функции — найди всех вызывающих»)
• Ключевые пути в системе (где Obsidian-vault, где основные проекты)
• Краткое описание меня и моих целей — Claude читает это и понимает контекст моих просьб

Один раз написанный CLAUDE.md экономит ~100 промптов в неделю. Я не повторяю «отвечай по-русски», «не делай лишнего», «прочитай файл перед правкой» каждый раз — это уже встроено.

Что класть в проектный CLAUDE.md

• Архитектура: где какие папки, как устроен модуль, что от чего зависит
• Конвенции: именование файлов, casing, структура коммитов
• Test expectations: когда писать тесты, что считается покрытием
• Что забудет будущий-ты: неочевидные решения, причины «почему так а не иначе»

Совет: проектный CLAUDE.md — это документ который ты обновляешь каждый раз когда ловишь себя на мысли «надо было записать». Не пиши его сразу полным — наращивай по мере того как Claude забывает что-то важное.

Если CLAUDE.md длиннее 200 строк — он работает хуже. Длинный файл значит что Claude перегружен правилами и теряет фокус. Сокращай или переноси детали в skills/ или ссылки на отдельные документы.

2. skills/ — навыки по запросу

Skill — это набор инструкций который Claude подгружает только когда нужно. В отличие от CLAUDE.md, который висит в контексте всегда, skill активируется по описанию: если твой запрос совпадает с тем что умеет skill — он автоматически вызывается.

Это решает проблему «не хочу засорять CLAUDE.md инструкциями для редкой задачи».

Где живёт

• ~/.claude/skills/<имя>/ — глобальные навыки, доступны во всех проектах
• .claude/skills/<имя>/ — проектные, едут вместе с репо

Структура одного skill

skills/my-skill/
├── SKILL.md           # описание для матчинга + инструкции
├── scripts/           # bash/python скрипты которые skill вызывает
├── templates/         # шаблоны для копирования в проект
└── references/        # справочные файлы (примеры, спецификации)

Главное — это SKILL.md. Первые 100 слов в нём — это «описание», по которому Claude решает запускать skill или нет. Если описание точное и узкое — skill срабатывает только когда правда нужен.

Мои восемь skills

• excalidraw-diagram — рисует схемы в Excalidraw из текстового описания. Использую для постов и техдока.
• /post — пишет пост для Telegram-канала с учётом моего голоса (анализирует прошлые посты).
• /week — собирает Weekly Review за неделю из Daily Notes в Obsidian.
• /pulse — пульс vault-а: что добавлено, что изменено, на что обратить внимание.
• /log — записывает итог сессии в Build Log проекта.
• slop-check — проверяет текст на AI-слоп (типичные паттерны генерации).
• nakodil-article — публикует статью на nakodil.site со всеми правилами формата (HTML, обложка, slug).
• skill-creator — создаёт новые skills (мета-навык, его установил первым).

Каждый из них я бы делал руками 5-10 минут — а так одна команда и готово.

Как создать свой skill

Самый быстрый путь — установить skill-creator:

claude install-skill https://github.com/anthropics/skills/tree/main/skills/skill-creator

После установки скажи Claude «сделай мне skill для X» — он проведёт тебя через диалог, создаст структуру, проверит что описание подходит для матчинга. Через 5-10 минут у тебя свой навык.

3. hooks/ — детерминированные правила

Hooks — это shell-скрипты которые срабатывают на события Claude. Не AI. Обычный bash. Если AI может ошибиться, а ты хочешь гарантию — это работа для hook.

Три основных типа

• PreToolUse — срабатывает до того как Claude запустит tool (Bash, Edit, Write). Можно блокировать опасные команды, валидировать аргументы.
• PostToolUse — срабатывает после. Используется для авто-форматирования (prettier, rubocop), линта, авто-коммитов, нотификаций.
• SessionStart — срабатывает в начале сессии. Загружает свежий контекст: pull последних коммитов, проверка статуса CI, прогрев env.

Примеры реальных hooks

Блокировка rm -rf:

#!/bin/bash
# .claude/hooks/PreToolUse.sh
if echo "$TOOL_ARGS" | grep -qE 'rm -rf|sudo rm'; then
  echo "Заблокировано: rm -rf требует подтверждения вручную" >&2
  exit 2
fi
exit 0

Авто-форматирование Ruby после правок:

#!/bin/bash
# .claude/hooks/PostToolUse.sh
if [[ "$TOOL_NAME" == "Edit" || "$TOOL_NAME" == "Write" ]]; then
  if [[ "$EDITED_FILE" == *.rb ]]; then
    bundle exec rubocop -A "$EDITED_FILE" 2>/dev/null
  fi
fi

Подтянуть свежий main в начале сессии:

#!/bin/bash
# .claude/hooks/SessionStart.sh
git fetch origin main --quiet
echo "Свежий origin/main подтянут. Текущая ветка: $(git branch --show-current)"

Когда не использовать

Если задача — это «AI-логика» (например «отформатируй текст под мой стиль»), hook тут не нужен — это работа для CLAUDE.md или skill. Hook нужен когда правило детерминированное и не должно зависеть от настроения LLM.

Это git hooks, но для агента. Та же логика, та же простота — обычный shell.

4. agents/ — делегирование задач

Subagent — это «другой Claude», у которого свой контекст, свои tools и свои правила. Главная сессия делегирует ему задачу и получает обратно только результат. Подробности работы остаются в его контексте, не засоряя твой основной чат.

Это решает главную проблему длинных сессий: контекст забивается. Когда контекст большой — Claude ошибается чаще, забывает что было раньше, тормозит. Делегирование тяжёлой работы в subagent держит главный поток чистым.

Где живёт

• ~/.claude/agents/<имя>.md — глобальные роли (доступны везде)
• .claude/agents/<имя>.md — проектные (привязаны к репо)

Файл subagent

---
name: code-reviewer
description: Ревьюит изменения по правилам репозитория, ищет нарушения конвенций
tools: [Read, Grep, Bash]
---

Ты — code-reviewer. Прочитай diff текущих изменений (git diff).
Сверь с правилами в CLAUDE.md и conventions.md.
Верни список нарушений или «OK» если всё чисто.

Не предлагай рефакторинг сверх запрошенного.
Не пиши код — только указывай на проблемы.

Полезные шаблоны subagent

• code-reviewer — ревью diff по правилам репо
• test-runner — запуск тестов и краткий отчёт о падениях
• explorer — поиск по кодбазе с возвратом структурированного ответа («где определена эта функция», «какие есть вызовы»)
• feature-dev — реализация задачи end-to-end в отдельном контексте

Когда субагент vs обычный chat

Субагент, если: задача требует много чтения файлов, поиска, длинного анализа — и ты не хочешь чтобы это всё попало в твой главный контекст.

Обычный chat, если: ты хочешь видеть процесс, итерировать, вмешиваться. Субагент возвращает один финальный результат.

5. plugins/ — пакетирование для команды

Plugin — это упаковка всех четырёх предыдущих слоёв (CLAUDE.md, skills, hooks, agents) в один пакет. Тиммейт делает один install — и у него настройка как у тебя.

Это решает проблему «у меня работает, у Васи нет». Когда у команды одинаковый .claude/ — все используют одинаковые конвенции, одинаковые навыки, одинаковые проверки.

Структура плагина

my-plugin/
├── manifest.json      # имя, версия, что внутри
├── skills/            # навыки в комплекте
├── agents/            # subagents в комплекте
├── hooks/             # триггеры в комплекте
└── README.md          # инструкции для тиммейтов

manifest.json

{
  "name": "my-team-plugin",
  "version": "1.0.0",
  "description": "Стек для команды: ревьюер, runner тестов, ruby auto-format",
  "author": "@nakodil_ai",
  "skills": ["code-reviewer-strict", "test-runner-rspec"],
  "hooks": ["PostToolUse"],
  "agents": ["explorer"]
}

Установка тиммейтом

claude plugin install https://github.com/your-org/team-plugin

Один раз поставил → у тиммейта тот же стек что у тебя. Когда обновляешь плагин — все получают апдейт.

Когда нужно

• Команда 2+ человек работает с Claude Code на одном проекте
• Хочешь чтобы конвенции и проверки были у всех одинаковые
• Часто появляются новые тиммейты которым нужно «всё настроить как у нас»

Если ты соло — plugins не нужны, всё лежит в твоём ~/.claude/. Они становятся актуальными когда появляется второй разработчик.

С чего начать сегодня вечером

Не пытайся настроить все пять папок сразу. Возьми одну. Я бы рекомендовал такой порядок:

30 минут — CLAUDE.md

Создай ~/.claude/CLAUDE.md и положи туда пять вещей:

• Как с тобой общаться (язык, тон, длина ответов)
• Краткое описание тебя и твоих основных проектов
• Ключевые пути в системе (где Obsidian, где код, где документы)
• Дисциплина работы с кодом, если ты разработчик («читай файл перед правкой» и т.п.)
• Что Claude НЕ должен делать без подтверждения (deploy, git push, удаление файлов)

Это даст 80% эффекта от всей структуры за 30 минут.

60 минут — два skill

Поставь skill-creator и сделай два своих навыка под задачи которые ты повторяешь чаще всего. У меня это были /post и /week — две задачи которые я делал руками каждую неделю.

90 минут — один hook

Возьми одно правило которое ты не доверяешь LLM. У меня это была блокировка деструктивных команд. Сделай простой PreToolUse-hook на 10 строк bash. Поймёшь механику.

После этого agents/ и plugins/ станут понятны естественно — потому что у тебя уже будет рабочий стек что в них упаковывать.

Что дальше

• Полная официальная документация Claude Code: docs.claude.com
• Подписывайся на @nakodil_ai в Telegram — там разборы реальных кейсов настройки агентов
• Версия для Instagram-карусели — @nakodil_ai в Instagram

Если что-то не работает или есть вопрос по конкретной папке — пиши в DM, отвечаю.