Анатомия папки .claude/

Почему Claude забывает всё каждую новую сессию?

Открываешь Claude Code утром, а он не помнит, что вы делали вчера. Это не баг. Каждая сессия Claude Code начинается с чистого контекста. Знания между сессиями переносят два механизма: файлы CLAUDE.md и автопамять, где Claude сам пишет заметки.

Без структуры это значит: ты заново объясняешь, какие у тебя API-ключи, какой стиль кода в проекте, какие переменные именуются как, и какие решения вы уже приняли по архитектуре. Каждый. Раз.

• API-ключи
• стиль кода
• имена переменных
• вчерашние решения
• что не пушить без подтверждения

Решение: в самом Claude Code. Папка .claude/ внутри проекта подгружается автоматически при старте каждой сессии. Что положишь туда: Claude знает с первой секунды.

Этот пост: карта. Шесть файлов и папок внутри .claude/ плюс одна папка рядом, memory-bank/. Что делает каждый, как настроить, какие ловушки.

Что лежит в папке .claude/ и рядом с ней?

Claude Code читает .claude/ при каждом старте, это и есть «мозг проекта». Memory-bank рядом: это «что Claude помнит» через сессии.

your-project/
├─ CLAUDE.md              → правила. ≤ 200 строк
├─ CLAUDE.local.md        → личное. в git не идёт
├─ .mcp.json              → MCP-серверы. только в корне
├─ memory-bank/           → память между сессиями
│  ├─ progress.md         → что сделано / в работе
│  ├─ decisions.md        → архитектурные решения
│  └─ insights.md         → грабли, на которые наступал
└─ .claude/                → мозг проекта
   ├─ skills/             → навыки. Claude берёт сам
   ├─ agents/             → суб-агенты, свой контекст
   ├─ commands/           → слэш-команды по имени файла
   ├─ hooks/              → твои скрипты для хуков
   ├─ settings.json       → права, модель, реестр хуков
   └─ settings.local.json → личное. в git не идёт

Ниже: каждый файл по делу. Сверху первым: CLAUDE.md, потому что без него остальное полупустое.

Что такое CLAUDE.md и что в него класть?

Главный файл. Здесь живут правила, которые Claude обязан соблюдать в этом проекте. Без него агент пишет код наугад.

CLAUDE.md: инструкция для AI.

Что класть

• стек и зависимости (TypeScript strict, какая UI-библиотека, какие иконки)
• стиль кода и формат коммитов
• архитектурные решения проекта
• правила «никогда»: что не пушить без явного «иди», какие команды запрещены
• краткие команды на старте: где запускается тестирование, где собирается билд

Ловушка: делать CLAUDE.md на 500+ строк. Длинный файл занимает больше контекста, и Claude хуже соблюдает правила. Документация советует держать файл короче 200 строк. Норма: до 200 строк. Большее: выносить в скиллы и memory-bank.

# NotifyMotion: инструкции проекта

## Стандарты
- TypeScript strict, никаких `any`
- @phosphor-icons/react для всех иконок
- тёмная тема по умолчанию

## Архитектура
- Canvas 2D + Zustand для глобального стейта
- WebCodecs + Mediabunny для MP4-экспорта

## Формат коммита
- NM-XXX: суть одной строкой
- Co-Authored-By: Александр

## Никогда не пушить без явного «иди».

Что такое memory-bank/ и зачем он нужен?

Если .claude/ = как Claude работает, то memory-bank/ = что Claude помнит между сессиями. Без неё каждый день начинается с чистого листа.

Это не часть Claude Code из коробки, это community-паттерн, который ставится руками. Не путай его с автопамятью Claude Code: там Claude сам пишет заметки в ~/.claude/projects/<проект>/memory/. Три файла дают 80% результата:

memory-bank/: память между сессиями.

Три файла внутри

• progress.md: что сделано, что в работе сейчас, что отложено и почему
• decisions.md: архитектурные решения и «почему именно так»
• insights.md: находки, грабли, на которые наступал, чтобы не повторять

Ловушка: грузить всё в контекст с первой команды. По JIT-принципу (just-in-time retrieval): пусть Claude сам подтянет нужный файл, когда тема всплывёт. Иначе зальёшь токены.

# Архитектурные решения

## 2026-05-08 · Stripe vs Paddle
Решение: Stripe Connect.
Почему: Paddle не работает в KZ.
Альтернативы пробовали: нет.

## 2026-05-10 · Auth: Supabase
Решение: Supabase Auth + RLS.
Почему: уже есть в стеке,
магические ссылки из коробки.

## Принципы (не правим)
- один экран = один компонент
- стейт только в Zustand store
- никаких prop-drilling глубже 2

Memory-bank: это точка перехода

Между «новичок постоянно повторяет агенту одно и то же» и «опытный вайбкодер передаёт агенту проект на 6 месяцев работы».

Когда в memory-bank/ появляется второй раздел в decisions.md, заметишь, что Claude перестал переспрашивать очевидное. Это и есть путь от новичка к опытному вайбкодеру.

Что такое skills/ и когда Claude подгружает навык?

Скилл: это папка с файлом SKILL.md. Внутри: инструкция для Claude по конкретному навыку. Claude сам решает, когда подгрузить: по описанию в frontmatter он матчит запрос пользователя и подхватывает нужный скилл.

.claude/skills/: model-invokable знания.

Чем удобно

• один скилл = одна папка, переиспользуется между проектами
• Claude подгружает только тогда, когда нужно (бережёт токены)
• не нужно лить весь стек в CLAUDE.md, выносим узкие навыки сюда
• есть готовые скиллы от Anthropic в anthropics/skills

Ловушка: писать в description размытое «всё про дизайн». Claude по этому полю решает, подгружать или нет. Конкретика выигрывает: «срабатывает при создании React-компонента с дизайн-задачей».

---
name: ui-design
description: дизайн интерфейсов.
  Подбор шрифтов, палитры и отступов
---

# UI Design
Используй при сборке любого UI.

## Когда срабатывать
- пользователь говорит «дизайн» или «UI»
- файл .tsx, .vue, .svelte, .html
- проект: дашборд или SaaS

## Источник
- shadcn/ui MCP для примеров
# Claude подхватит сам.

Когда заводить суб-агентов в agents/?

Каждый файл: суб-агент с YAML-frontmatter (имя, описание, набор инструментов, модель). Claude Code делегирует ему задачу через Agent-инструмент. У агента свой контекст: он не съедает токены основной сессии.

.claude/agents/: команда из одного Claude.

Когда заводить

• code-reviewer.md: сеньор-ревьюер для каждого PR
• debugger.md: ловит баги в изоляции, не путает основной контекст
• security-auditor.md: ищет дыры (auth, SQLi, XSS) и секреты в коде
• tester.md: пишет / гоняет тесты, отдельный контекст под Playwright

Ловушка: завести 10 агентов на старте. Каждый агент = больше токенов на матчинг. Норма: 3-5 агентов под реальные задачи проекта.

---
name: code-reviewer
description: сеньор-ревьюер для PR
tools: Read, Grep, Glob
---

# Code Reviewer
Ты: сеньор-инженер. Без вежливости.

## Проверяй
- баги, которые попадут в прод
- дыры безопасности (auth, SQLi, XSS)
- логику, расходящуюся со спекой
- тесты, которые слишком много мокают

# У агента: свой контекст.

Зачем нужны слэш-команды в commands/?

Каждый .md в этой папке становится /имя-файла в чате Claude. Готовый workflow на тапе. Ты решаешь, когда запускать, в отличие от скиллов, которые Claude берёт сам. Команды и скиллы теперь один механизм: файл в commands/ и скилл с тем же именем создают одну команду, при конфликте побеждает скилл.

.claude/commands/: workflow по запросу.

Полезные команды

• /commit: разобрать git diff --staged, написать осмысленное сообщение в твоём формате
• /review: позвать code-reviewer-агента на текущие изменения
• /test: сгенерировать тесты на новые функции
• /ship: пройти полный pre-deploy чек-лист (тесты, типы, билд)

Ловушка: делать команды-альясы для очевидных задач. Команда оправдана только если она содержит не-очевидный workflow, последовательность шагов, которую ты повторяешь много раз.

---
description: разобрать diff и написать commit
---

# /commit
Запусти `git status` и `git diff --staged`.
Найди *почему*, не *что*.

## Формат
- Subject: 50 символов, повелит. наклонение
- Body: объясни рассуждения
- префикс NM-XXX

## Никогда
- push без подтверждения
- --no-verify

# Слэш-команды = самый быстрый UX.

Что такое hooks/ и что к ним прикручивать?

Шелл-скрипты, которые срабатывают автоматически до или после действий Claude. Регистрируются в settings.json. Без вопросов, без исключений.

.claude/hooks/: всегда срабатывают.

Что прикручивать

• format-on-save.sh: авто-формат каждого файла после Edit (prettier / ruff / gofmt)
• block-dangerous-bash.sh: блок rm -rf, git push --force, --no-verify
• block-secrets.sh: не даёт записать .env или ключи в коммит
• desktop-notify.sh: пингует macOS-уведомлением, когда Claude закончил

Ловушка: писать в хуке логику, которая нужна иногда. Хук срабатывает всегда. Сомневаешься: выноси в слэш-команду.

#!/usr/bin/env bash
# авто-формат каждого файла после Edit

FILE=$(jq -r .tool_input.file_path)

case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx)
    npx prettier --write "$FILE" ;;
  *.py)
    ruff format "$FILE" ;;
  *.go)
    gofmt -w "$FILE" ;;
esac

# срабатывает после каждого Edit

Как управлять всем через settings.json?

Плагины упаковывают агентов, команды, хуки и MCP-серверы в одну единицу. Они ставятся командой /plugin и лежат в ~/.claude/plugins/, а не в папке проекта. settings.json: это главная панель: что Claude разрешено, какая модель, какие хуки активны.

.claude/settings.json: панель управления.

Что настраиваешь

• model: какой Claude использовать (Sonnet, Opus, Haiku)
• permissions.allow: какие инструменты Claude может вызывать (Bash, Read, Edit, Glob, Grep)
• permissions.deny: запрещённые команды (типичный пример: Bash(rm -rf *))
• hooks.PostToolUse: список хуков-скриптов
• outputStyle и statusLine: как Claude отвечает и что показано в нижнем баре

Ловушка: класть секреты в settings.json и коммитить. Личные настройки и ключи держи в settings.local.json: Claude Code сам исключает его из git при создании. Созданный вручную файл добавь в .gitignore.

{
  "model": "claude-opus-5-5",
  "permissions": {
    "allow": [
      "Bash(npm run *)", "Bash(git *)",
      "Read", "Edit", "Glob", "Grep"
    ],
    "deny": ["Bash(rm -rf *)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/format-on-save.sh"
          }
        ]
      }
    ]
  },
  "outputStyle": "Explanatory",
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

Что положить в новый проект, чтобы Claude перестал забывать?

Минимальный набор, чтобы Claude перестал забывать всё с первой сессии. Настройка занимает около часа.

shell · из корня нового проекта

# 1. структура папок
mkdir -p .claude/{skills,agents,commands,hooks} memory-bank

# 2. главный файл правил
touch CLAUDE.md
touch CLAUDE.local.md
echo "CLAUDE.local.md" >> .gitignore

# 3. память между сессиями
touch memory-bank/{progress,decisions,insights}.md

# 4. базовые скиллы от Anthropic ставятся внутри Claude Code:
#    /plugin marketplace add anthropics/skills
#    /plugin install example-skills@anthropic-agent-skills

# 5. суб-агент для PR-ревью
cd .claude/agents/
touch code-reviewer.md  # текст из раздела 06 ↑

# 6. слэш-команда /commit
cd ../commands/
touch commit.md  # текст из раздела 07 ↑

# 7. хук авто-формата
cd ../hooks/
touch format-on-save.sh  # текст из раздела 08 ↑
chmod +x format-on-save.sh

# 8. settings.json: из раздела 09 ↑
cd ..
touch settings.json
touch settings.local.json
echo ".claude/settings.local.json" >> ../.gitignore

# 9. перезапустить Claude Code в этой папке
claude

После этого первый промпт Claude уже знает, какой у тебя стек, какие правила, кому делегировать ревью и что нельзя пушить без подтверждения. Это и есть путь от новичка к опытному вайбкодеру.