Гайд · 8 мин чтения

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

Что класть в каждую из пяти папок Claude Code, чтобы агент перестал забывать вещи между сессиями.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Где живёт

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

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

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

Мои восемь 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.

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

Примеры реальных 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 держит главный поток чистым.

Где живёт

Файл subagent

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

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

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

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

Когда субагент 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

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

Когда нужно

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

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

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

30 минут — CLAUDE.md

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

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

60 минут — два skill

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

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

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

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

Что дальше

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