раздел 02

Эталонная структура папок

Ниже - дерево, которое можно скопировать как есть. Оно не единственно верное, но у него есть свойство, ради которого всё затевалось: по имени папки сразу понятен уровень, а агент находит нужное без подсказок.

Дерево воркспейса

workspace/
├── AGENTS.md              # общие правила для всех проектов (в Claude Code - CLAUDE.md)
├── README.md              # что тут лежит и как устроено
├── .env                   # один файл секретов на весь воркспейс, не в git
│
├── _templates/            # УНИВЕРСАЛЬНОЕ: шаблоны документов
│   ├── README.md          # список шаблонов и когда какой брать
│   ├── invoice.md
│   ├── act.md
│   ├── kp.md
│   └── contract.md
│
├── _methods/              # УНИВЕРСАЛЬНОЕ: методологии и стиль
│   ├── README.md
│   ├── style.md           # правила текстов
│   ├── interview.md       # как проводить интервью
│   └── pricing.md         # как считать цену
│
├── .claude/skills/        # УНИВЕРСАЛЬНОЕ: процессы как скиллы
│   ├── make-invoice/
│   └── weekly-review/
│
├── projects/              # ПРОЕКТНОЕ
│   ├── kp-generator/
│   │   ├── AGENTS.md      # уточнения для этого проекта
│   │   ├── README.md
│   │   ├── NOTES.md       # журнал изменений
│   │   └── src/
│   └── site-landing/
│       └── ...
│
├── clients/               # КЛИЕНТСКОЕ, не в общий git
│   ├── Acme/
│   │   ├── README.md      # кто это, контекст, статус
│   │   ├── requisites.md  # реестр юрлиц и контактов
│   │   ├── INBOX-LOG.md   # журнал входящего по клиенту
│   │   ├── inbox/         # сырое входящее: письма, файлы
│   │   ├── docs/          # договоры, счета, акты, КП
│   │   └── calls/         # транскрипты и записи созвонов
│   └── Beta Corp/
│       └── ...
│
├── _inbox/                # сырое входящее без адресата
│   └── INBOX-LOG.md
│
└── _archive/              # закрытое, не удаляем
    └── 2026-08/

Три вещи, которые делают это дерево рабочим:

  1. Подчёркивание в начале имени (_templates, _inbox) держит служебные папки вверху списка и отделяет их от проектов.
  2. У projects/ и clients/ разная судьба в git: проекты коммитятся, клиенты - нет.
  3. В каждой папке верхнего уровня есть README.md, который объясняет, что тут и как этим пользоваться.
_templates, _methods, skills
Универсальное
Корень воркспейса. Меняется редко, читается отовсюду. Одна копия на всё.
projects/<имя>/
Проектное
Код, README, NOTES.md, свой AGENTS.md / CLAUDE.md. Свой git-репозиторий у каждого.
clients/<имя>/
Клиентское
inbox, docs, calls, requisites.md. Вне общего git, по папке на компанию.

AGENTS.md / CLAUDE.md на каждом уровне

Файл правил агента лежит на двух уровнях, и они складываются.

Общий, в корне воркспейса. Правила, которые действуют везде: где шаблоны, где методологии, что запрещено, как называть файлы, куда писать секреты. Именно здесь строки вида «шаблон КП - _templates/kp.md, всегда начинать с него».

Уточняющий, в папке проекта. Стек, команды запуска, особенности этого проекта. Он не повторяет общий, а дополняет: агент читает оба, сначала корневой, потом проектный.

В клиентских папках файл правил обычно не нужен: агент попадает туда по явной ссылке из задачи, а правила обращения с клиентскими данными записаны в корневом файле. Что именно агент читает и в каком порядке - в курсе AGENTS.md и CLAUDE.md, а обзор всех системных файлов агента - в Системные документы агента.

Правила именования

Имена файлов и папок - это тоже интерфейс для агента. Правил немного.

Даты в начале имени, если важна хронология. 2026-09-15-call-acme.md или короче 260915-call-acme.md. Файлы сами сортируются по времени, и агент видит, что новее. Дата в конце имени (call-acme-15.09.md) этого не даёт.

Латиница и дефисы в технических именах. Папки проектов, скрипты, шаблоны: kp-generator, make-invoice, style.md. Без пробелов, без кириллицы, без заглавных букв. Пробелы и кириллица в путях ломают команды и скрипты, и агент тратит попытки на экранирование.

Человекочитаемые имена в клиентских папках. clients/Acme/, clients/Beta Corp/ - как компания называет себя. Сюда вы ходите руками, а агент - по ссылке. Здесь пробелы допустимы.

Без версий в имени. kp_final_2_new.md означает, что у вас нет ни версий, ни финала. Версии хранит git (см. Git: основы), а в имени файла остаётся только смысл.

Одинаковые имена служебных файлов. README.md, NOTES.md, requisites.md, INBOX-LOG.md - везде так. Агент, увидев requisites.md в любой клиентской папке, знает, что внутри.

плохо                              хорошо
──────────────────────────────     ──────────────────────────────
КП для Акме (финал) v2.docx        clients/Acme/docs/2026-09-10-kp.md
Новая папка 3/                     _inbox/
шаблон кп новый.md                 _templates/kp.md
скрипт генерации.py                projects/kp-generator/src/build.py

Как перейти на такую структуру

Не переносите всё за один вечер. Порядок такой:

  1. Создайте корневой AGENTS.md / CLAUDE.md и папки _templates/, _methods/, _inbox/, _archive/, projects/, clients/. Пустые.
  2. Заведите README.md в каждой из них: одна-две строки, что здесь.
  3. Новое кладите сразу по правилам. Старое пока не трогайте.
  4. Раз в неделю переносите из старого по одному проекту или клиенту. Через месяц-два старая куча закончится сама.