Архитектура проекта

Каждый новый чат в Claude Code начинается с чистого листа. Он не помнит, что за проект, какой стек, какие правила ты установил в прошлый раз. Первые два дня это терпимо — пишешь «вот мой проект, вот что нужно», и поехали. Потом превращается в потерю времени: объяснять одно и то же снова и снова.

Решение — несколько файлов в папке проекта, которые Claude читает автоматически при каждом запуске. Один раз настроил — и каждый новый чат уже в контексте. Это и есть архитектура проекта.

Но перед файлами — алгоритм. Большинство людей хотят сразу делать: писать код, создавать страницы. Это тупик. Без продуманной основы через три дня начинаются переделки, хаос и «всё снова не то». Поэтому сначала шесть шагов.

Алгоритм старта

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

1. Идея

Сформулируй одним предложением: что, для кого и зачем. «Я создаю ЧТО для КОГО чтобы решить КАКУЮ проблему». Без этого Claude будет угадывать.

Не нужно готового текста — расскажи как другу, без структуры. Голосом или текстом, как удобно. Claude сам оформит.

2. Исследование

Попроси Claude найти 5–10 аналогов в твоей нише. Смотришь что работает, что нет — это основа для твоего решения.

Найди 5-7 похожих проектов или сервисов в нише [твоя ниша].
Для каждого: что делает, для кого, основные функции, что можно взять за основу.
Сохрани результат в файл research.md

3. Критика

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

Оцени эту идею честно. Что может не сработать?
Какие типичные ошибки в таких проектах?
Что я мог упустить?
Не подхалимничай — мне нужен честный взгляд со стороны.

4. Бриф

Сводишь идею + результаты исследования + критику в один файл — техническое задание. Это документ из которого потом будет рождаться код.

На основе research.md и моей идеи — составь brief.md, техзадание проекта.
Включи: что это (2-3 предложения), для кого, какую проблему решает,
основные функции (MVP), функции на будущее, технологии,
чего НЕ будет на старте, первые шаги.

Учти рекомендации из критики — что улучшить, чего избегать.
Посмотри критически: что я мог упустить?

5. План

Разбей на 3–5 этапов. Каждый этап — одна задача для Claude. Большая задача за один промпт = хаос.

Разбей проект на 4-6 этапов от первого файла до готового результата.
Каждый этап — конкретный шаг с понятным результатом.
Сохрани в PLAN.md в формате [ ] пункт

6. Реализация

Одна задача — один промпт. Не пишешь всё сразу, идёшь по плану шаг за шагом. Сделал пункт — отметил галочку, взял следующий.

Как сформулировать идею

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

Вот реальный поток разговора:

Хочу сделать телеграм-бота для своей кофейни. Чтобы люди могли смотреть меню и делать предзаказ. Ну типа выбираешь напиток, говоришь когда заберёшь, приходишь — уже готово. Ещё хочу чтобы была программа лояльности, каждый 5-й кофе бесплатно.

Помоги превратить это в документацию проекта. Сделай структуру: что это, для кого, основные функции.

Какие функции обычно есть в ботах для кофеен? Что я мог упустить?

Создай файл docs/project.md с этой документацией

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

Четыре файла проекта

На выходе из этих пяти шагов у тебя должны появиться четыре файла. Они создаются один раз и работают на весь проект.

Можно создать все четыре файла одной командой:

Посмотри все файлы в проекте. Создай четыре файла:
- research.md — исследование ниши (конкуренты, что работает, тренды)
- brief.md — техзадание на основе исследования (цель, аудитория, структура, стиль)
- CLAUDE.md — правила работы с этим проектом
- PLAN.md — план-чеклист задач в формате [ ] пункт

Если у тебя есть вопросы — задавай.

А вот шаблон для brief.md — он же подходит для docs/project.md:

# Название проекта

## Что это
Краткое описание в 1-2 предложения.

## Для кого
Кто будет пользоваться? Целевая аудитория.

## Проблема
Какую проблему решает? Зачем это нужно?

## Основные функции
- Функция 1
- Функция 2
- Функция 3

## Страницы / экраны
Что увидит пользователь? Перечень страниц или экранов.

## Чего НЕ будет (пока)
Что сознательно не делаем. Важно для фокуса.

## Технические заметки
Если есть специфика: платформа, ограничения, интеграции.

Цикл улучшения документации

Бриф редко получается идеальным с первого раза. И это нормально — не нужно сидеть час и доводить до совершенства. Лучше запустить цикл улучшения: четыре прохода, каждый занимает минуту, на выходе документ который не стыдно показать.

1. Перечитай как первый раз

Открой brief.md и читай так, как будто видишь его впервые. Где спотыкаешься, что непонятно, чего не хватает — выписывай.

2. Спроси «ты уверен?»

Claude часто говорит уверенно вещи которые неточны — особенно про технологии, цены, конкретные сервисы. Простой приём проверки:

Посмотри ещё раз на brief.md. Особенно на технические детали
и конкретные цифры — ты уверен что это так? Есть ли альтернативы?
Что может оказаться неточным или устаревшим?

3. Критический взгляд эксперта

Попроси Claude примерить роль и посмотреть со стороны:

Представь что ты опытный продакт-менеджер с 10-летним опытом.
Какие вопросы у тебя возникнут к этому brief.md?
Что слабо проработано, что можно усилить, что вообще не учтено?

4. Пересмотр

На основе замечаний из шагов 1-3 — обнови документ. Добавь конкретику где была размытость, исправь неточности, закрой дыры.

CLAUDE.md — подробно

Из четырёх файлов CLAUDE.md — самый важный. Это инструкция на холодильнике для нового сотрудника: «У нас принято так-то. Вот чего нельзя. Вот на что обращать внимание». Любой новый чат — и Claude сразу в контексте.

Ключевое отличие от остальных файлов: Claude читает его автоматически. Не нужно каждый раз говорить «напоминаю, у нас такие-то правила». Просто написал — и оно работает всегда.

Как создать

Три способа — от быстрого к ручному.

Способ первый — одна команда в чате:

/init

Claude пройдётся по всем файлам в папке, поймёт что за проект и создаст CLAUDE.md с базовой структурой. Потом дополняешь под себя.

Способ второй — попросить с конкретикой:

Создай CLAUDE.md для этого проекта. Опиши что это за проект, структуру папок, как запускать, и добавь секцию для ошибок.

Способ третий — создай файл вручную. Файл называется ровно CLAUDE.md и лежит в корне проекта.

Если файл уже есть, но слабый — не переписывай с нуля, попроси разобрать и улучшить:

Посмотри CLAUDE.md и сделай его глубокий разбор. Давай обсудим какие детали могут мешать работе, а какие ещё необходимо добавить.

Лайфхак: клавиша # прямо в чате — быстро добавить правило без открытия файла. Написал # не трогай файл config.json → Claude добавил в CLAUDE.md.

Что писать

Хороший CLAUDE.md отвечает на четыре вопроса: что за проект, для кого, какой стек, какие правила работы. Вот рабочий шаблон:

# Название проекта

## Что это
Одно-два предложения: суть проекта и для кого.

## Аудитория
Кто будет пользоваться. Уровень подготовки. Язык общения с ними.

## Стек
- Язык / фреймворк
- Хостинг
- Особые ограничения (без внешних библиотек, только ES6 и т.д.)

## Стиль
- Цвета, шрифты, акценты
- Тон текста (разговорный / официальный)

## Правила работы
- Перед созданием нового файла — скажи что планируешь
- Не удаляй файлы без явного подтверждения
- Перед фиксом бага ищи корневую причину, не заплатку
- Если задача неочевидная — задавай уточняющие вопросы

## НЕ ДЕЛАТЬ
- Не выдумывай детали которых я не давал
- Не строй предположения — спрашивай
- Не рефакторь код который я не просил трогать

Есть приём который делает правила жёстче. Claude лучше воспринимает инструкции с ключевыми словами-маркерами, особенно на английском:

Правила пиши на английском, пояснения можно на русском. Вот пример рабочего CLAUDE.md с маркерами:

# Project Rules

## 1. NEVER restore previous versions without confirmation
ALWAYS ask before restoring any backup or previous version

## 2. Security — NEVER commit credentials
- config.json contains API key — NEVER commit
- .env files — NEVER commit
- ALWAYS check git status before commits

## 3. Git workflow
- Main branch: main
- ALWAYS create descriptive commit messages

## 4. Before deleting
ALWAYS ask before deleting any file

## 5. Project structure
- src/ — main code
- docs/ — documentation
- See: docs/architecture.md for details

Что НЕ класть в CLAUDE.md

Так же важно знать чего туда не нужно. CLAUDE.md — это инструкция, а не архив. Вот что там лишнее:

Правила в CLAUDE.md должны быть конкретными. «Будь внимательнее» и «не ошибайся» — не работают. «NEVER commit .env files» — работает.

Файл растёт из опыта

CLAUDE.md — живой документ. Он не пишется один раз и забывается. Лучшие правила появляются из реальных факапов.

Claude случайно закоммитил что-то лишнее — добавил правило. Удалил файл без предупреждения — добавил правило. Начал переписывать код который не просили — добавил правило. Так постепенно файл превращается в точную инструкцию именно под твои задачи.

Когда увидел что проблема повторяется, напиши в чате прямо:

Добавь в CLAUDE.md правило: NEVER делай X без подтверждения

# никогда не удаляй файлы без подтверждения

Раз в неделю — чистка. Правила устаревают: проект меняется, некоторые ограничения уже не нужны. Попроси Claude навести порядок:

Посмотри CLAUDE.md — объедини похожие правила и убери устаревшие.

@ ссылки на файлы

Когда правил становится много — не нужно всё держать в одном файле. В CLAUDE.md можно ссылаться на другие файлы через символ @:

Стиль кода описан в @docs/code-style.md
Правила git-коммитов — @docs/git-workflow.md

Символ @ говорит Claude: прочитай этот файл. Вместо 20 правил в основном файле — одна строка. Основной CLAUDE.md остаётся коротким, детали — в отдельных файлах.

Четыре правила, которые реально работают

Из практики — четыре инструкции, которые меняют качество работы сильнее всего. Добавь в свой CLAUDE.md:

## Правила поведения

1. Оспаривай мои решения. Если мой подход неоптимальный — скажи прямо.
   Не соглашайся просто потому что я так сказал.

2. После значимого действия структурируй ответ:
   - Что сделано
   - Что нужно от меня (если нужно)
   - Следующий шаг

   Значимое действие = создал/изменил файлы, сделал коммит, фикс бага,
   рефакторинг, реализация фичи. На простые вопросы и обсуждения —
   обычный ответ, без структуры.

3. Если по ходу работы заметил что-то что стоит улучшить (но я не просил) —
   скажи отдельной строкой в конце. Только если есть что-то конкретное.

4. Всё что можешь сделать сам — делай сам.
   Твоя задача — освободить моё время.

Первое правило даёт партнёра, а не исполнителя — Claude перестанет соглашаться со всем подряд. Второе убирает хаос из ответов после крупных задач (на каждый «как дела» структуру не лепит — это съедало бы токены зря). Третье постепенно улучшает проект без отдельных задач «проверь всё». Четвёртое снимает необходимость микроменеджмента.

Глобальный CLAUDE.md

Помимо проектного CLAUDE.md есть глобальный — он лежит в ~/.claude/CLAUDE.md и применяется ко всем твоим проектам автоматически.

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

# Global Instructions

## Язык и тон
- Всегда на русском
- На «ты», по-дружески, как с коллегой — без официоза
- Кратко и по делу, без воды и лишних «как видишь, я успешно сделал...»
- Без эмодзи в тексте (если только сам не попросил)

## Стиль работы
- Перед тем как создавать или удалять файлы — скажи коротко,
  что собираешься делать, потом делай
- Не дублируй существующую функциональность — сначала проверь,
  нет ли уже такого скилла/файла/решения
- При работе с библиотеками/API/фреймворками — проверяй актуальную
  доку через context7 MCP, не полагайся на свои знания (устаревают)
- Перед фиксом бага — найди корневую причину, не лепи заплатку на симптом
- После фикса нетривиального бага — предложи записать урок в
  knowledge-base/outputs/YYYY-MM-DD-bug-тема.md
- Если задача неочевидная — задавай уточняющие вопросы, не угадывай

## Правила поведения

1. Оспаривай мои решения. Если мой подход неоптимальный — скажи прямо.
   Не соглашайся просто потому что я так сказал.

2. После значимого действия структурируй ответ:
   - Что сделано
   - Что нужно от меня (если нужно)
   - Следующий шаг

   Значимое действие = создал/изменил файлы, коммит, фикс, фича.
   На простые вопросы и обсуждения — обычный ответ, без структуры.

3. Если по ходу работы заметил что-то что стоит улучшить (но я не просил) —
   скажи отдельной строкой в конце. Только если есть что-то конкретное.

4. Всё что можешь сделать сам — делай сам.
   Твоя задача — освободить моё время.

## Контекст обо мне
- Я предприниматель, не разработчик — технические штуки
  объясняй на пальцах, без жаргона по умолчанию
- macOS, zsh, VS Code + Claude Code

Проектный CLAUDE.md дополняет глобальный — не заменяет. Правила суммируются. То что специфично для конкретного проекта (стек, аудитория, особый стиль текста) — в проектный. То что одинаково везде (язык, тон, поведенческие правила) — в глобальный.

Когда правил много

Если CLAUDE.md разрастается — выноси отдельные блоки в папку .claude/rules/:

.claude/
  rules/
    code-style.md      ← правила форматирования кода
    git-workflow.md    ← как коммитить, как пушить
    dont-do.md         ← список запретов

Основной CLAUDE.md остаётся коротким. .claude/rules/ — это встроенный механизм Claude Code: он читает все .md файлы из этой папки при каждом запуске автоматически, так же как и сам CLAUDE.md. Связывать или ссылаться не нужно — просто создал файл в папке, и он работает.

CLAUDE.md vs MEMORY.md

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

Главное правило: не смешивай. Твои правила — в CLAUDE.md. Технические наблюдения агента — в MEMORY.md. Если Claude начнёт перезаписывать твои правила своими заметками — будет бардак.

На CLAUDE.md можно положиться всегда — ты его контролируешь. MEMORY.md помогает, но требует присмотра: через несколько месяцев там накапливается устаревшая информация, которая начинает мешать.

AutoMemory

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

Что именно туда попадает: какие ошибки встретились и как их решили, какие команды используются для сборки, особенности архитектуры проекта. Первые 200 строк MEMORY.md загружаются в каждую новую сессию автоматически — Claude видит свои прошлые заметки в начале разговора и опирается на них.

Посмотреть что сохранилось, включить или выключить:

/memory

Если хочешь зафиксировать что-то конкретное — лучше попросить явно, это надёжнее чем ждать пока он сам запишет:

Запомни что мы всегда используем bun, а не npm в этом проекте

Запиши в память: в этом проекте используется чистый HTML без фреймворков,
стили в styles.css, деплой через Vercel по git push

Раз в месяц стоит заходить в /memory и чистить устаревшее. Без этого заметки превращаются в хлам — старые решения, которые уже не актуальны, начинают влиять на новые ответы.

settings.json и settings.local.json

CLAUDE.md отвечает на вопрос "что Claude должен делать" — правила, стиль, инструкции. settings.json отвечает на вопрос "что Claude вообще может делать" — какие команды разрешены, к каким файлам есть доступ, какую модель использовать. Первое про поведение, второе про доступы и настройки.

На самом деле таких файлов три, и у каждого своё место:

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

Создавать эти файлы вручную не обязательно — можно просто попросить Claude: "создай мне settings.json с базовыми настройками безопасности" — и он сделает. Либо файл появляется сам: когда Claude предлагает выполнить команду и ты нажимаешь "Yes, don't ask again" — он автоматически записывает это разрешение в settings.local.json.

Что такое коммит и пуш — разбираем в статье GitHub →

Permissions — главная настройка

Самое важное что живёт в settings.json — это permissions, разрешения. Они определяют что Claude Code может делать без вопросов, что должен спрашивать, а что запрещено вообще.

Три типа правил: allow — разрешить без вопросов, deny — запретить всегда, ask — спрашивать каждый раз. При конфликте deny всегда побеждает — никакое другое правило его не перекроет.

{
  "permissions": {
    "allow": ["Bash(git status)", "Bash(npm run *)"],
    "deny":  ["Bash(curl *)", "Read(./.env)"],
    "ask":   ["Bash(git push *)"]
  }
}

Синтаксис правил: имя инструмента и в скобках — спецификатор. Звёздочка * работает как «подстановочный знак» — то есть «что угодно вместо звёздочки». Bash(npm run *) разрешает любую команду начинающуюся с npm run — например npm run build, npm run test, npm run dev. Пробел перед звёздочкой важен: Bash(ls *) разрешит ls -la (потому что есть пробел после ls), но не lsof (это другое слово, без пробела).

// Bash — команды терминала
"Bash(npm run build)"       — точная команда
"Bash(git * main)"          — любой git-команде с main
"Bash(* --version)"         — любая команда с флагом --version

// Файлы
"Read(~/.zshrc)"            — конкретный файл из домашней папки
"Read(./.env)"              — .env в текущем проекте
"Edit(/src/**/*.ts)"        — любой .ts файл внутри src/

// Веб
"WebFetch(domain:example.com)"   — все запросы к домену

Готовый deny-список — скопируй себе

Вот рабочий набор запретов для глобального ~/.claude/settings.json. Закрывает три категории угроз: чтение секретных файлов, деструктивные команды и опасные сетевые операции. Это реальный конфиг, а не придуманный пример.

{
  "permissions": {
    "deny": [

      // Секретные файлы — не читать и не выводить в терминал
      "Read(.env)",
      "Read(.env.*)",
      "Read(*credentials*)",
      "Read(*secret*)",
      "Read(**/*.token*)",
      "Read(**/*key*.pem)",
      "Read(**/*key*.json)",
      "Bash(cat */.env*)",
      "Bash(cat *.pem)",
      "Bash(cat *credentials*)",
      "Bash(cat *secret*)",

      // Деструктивные команды — без права на ошибку
      "Bash(rm -rf *)",
      "Bash(rm -r *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(git clean -f*)",
      "Bash(git checkout -- .)",
      "Bash(git branch -D *)",
      "Bash(chmod 777 *)",

      // Опасные сетевые операции
      "Bash(curl * | bash)",
      "Bash(curl * | sh)",
      "Bash(wget * | bash)",
      "Bash(eval *)",

      // Запрет экспортировать секреты в переменные окружения
      "Bash(export *TOKEN*)",
      "Bash(export *SECRET*)",
      "Bash(export *KEY*)",
      "Bash(export *PASSWORD*)"
    ]
  }
}

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

Что ещё можно настроить

Помимо разрешений в settings.json живут другие настройки. Вот практически полезные:

Реальный пример: settings.json для командного проекта — разрешить стандартные команды, заблокировать опасные, и настройки проверить через /status прямо в чате.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git status)",
      "Bash(git log *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

{
  "autoMemoryEnabled": true,
  "permissions": {
    "deny": ["Bash(rm -rf *)"]
  }
}