Как структурировать проект в Claude Code и Codex, чтобы AI экономил токены

Коротко: если Вы работаете с Claude Code или Codex, не держите весь контекст проекта в чате. Создайте внутри проекта простую файловую систему: правила для агента, память, текущий план, сырые источники, бизнес-контекст, готовые результаты и проверки качества. Тогда AI читает меньше лишнего, быстрее понимает задачу и реже выдумывает факты.

Для кого эта структура

Эта схема подходит людям, которые хотят работать с AI-агентами не как с одноразовым чатом, а как с рабочей системой внутри проекта.

Например, Вы можете использовать Claude Code, Codex или оба инструмента. Названия стартовых файлов у них разные, но идея одна: агенту нужно объяснить, где лежат правила, где память, где текущий план, где сырые материалы и где готовые результаты.

Такой пример можно брать как основу, но не нужно копировать его один в один. Главная цель - собрать структуру, с которой AI не начинает каждую задачу с нуля.

Главная идея: не один большой промпт, а карта проекта

Длинный промпт быстро превращается в хаос. Сегодня Вы добавили туда бизнес-контекст, завтра правила стиля, послезавтра новую задачу, а через неделю агент уже читает много лишнего.

Файловая структура работает лучше, потому что каждый тип информации лежит на своём месте:

1. Правила для агента лежат отдельно.
2. Долгая память не смешивается с текущим планом.
3. Сырые материалы не попадают в очищенный бизнес-контекст.
4. Готовые результаты не теряются в чатах.
5. Неизвестные факты записываются как вопросы, а не выдумываются.

Claude Code и Codex: какие файлы использовать

В Claude Code и Codex стартовые файлы выполняют похожую роль, но называются по-разному.

По сути, CLAUDE.md и AGENTS.md почти одинаковы по роли: это стартовые инструкции для разных AI-систем. Они должны отвечать на одни и те же вопросы:

• что агент должен прочитать первым;
• где лежит память проекта;
• где текущий план;
• где бизнес-контекст;
• что нельзя менять без разрешения;
• как проверять результат.

Если Вы используете только Claude Code, начните с CLAUDE.md. Если используете только Codex, начните с AGENTS.md. Если используете оба, не дублируйте длинные правила в двух местах: сделайте один файл главным, а второй пусть коротко ведёт к нему.

Минимальная структура с нуля

На старте не нужна сложная система. Достаточно такой базы:

CLAUDE.md или AGENTS.md
memory.md
plan.md
raw/

business/
  INDEX.md
  project-summary.md
  open-questions.md
  products/
  audience/
  marketing/
  economics/
  voice/

outputs/
evals/
archive/

Это уже превращает пустой проект в понятный workspace для AI-агента.

За что отвечает каждый блок

Что написать в файле правил

Стартовый файл правил не должен быть большим. Его задача - не хранить всю информацию, а направить агента.

Пример логики для CLAUDE.md или AGENTS.md:

1. Сначала прочитай этот файл.
2. Если задача про бизнес, маркетинг, рекламу, контент или продажи - открой business/INDEX.md.
3. Если нужно понять текущий статус - открой plan.md.
4. Если нужны стабильные факты о проекте - открой memory.md.
5. Сырые материалы ищи в raw/.
6. Готовые результаты сохраняй в outputs/.
7. Если факт неизвестен - запиши его в business/open-questions.md, не выдумывай.

Так агент получает маршрут и не тратит токены на случайное чтение всего проекта.

Как эта структура экономит токены

Токены тратятся не только на финальный ответ. Они тратятся на весь контекст, который модель читает перед работой.

Когда всё лежит в одном файле, агент вынужден читать лишнее. Когда есть project-summary.md, он быстро понимает бизнес. Когда есть business/INDEX.md, он видит карту и открывает только нужный файл. Когда сырые материалы лежат в raw/, агент не путает черновики со стабильной памятью.

Практический эффект простой: вместо "прочитай всё и догадайся" агент получает маршрут "прочитай правила, текущий план, короткий summary и только нужную тематическую папку".

Business layer: зачем нужна папка business/

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

Папка business/ отделяет знания о компании от технического шума.

Главное правило для project-summary.md

business/project-summary.md не должен быть складом всего. Это короткая выжимка, которую агент может быстро прочитать перед работой.

Туда стоит положить:

• что за бизнес;
• какие продукты или услуги;
• для кого они;
• какой основной оффер;
• какие боли, желания и возражения у аудитории;
• какая экономика, если она важна для задач;
• какой tone of voice;
• какая текущая цель;
• ссылки на полные файлы.

Если агенту нужна общая картина, он читает summary. Если нужна глубина, открывает конкретный файл.

Что делать, если проект уже существует

Не нужно ломать старую структуру и переносить всё механически. Лучше аккуратно добавить недостающий слой.

1. Определите, с каким агентом работаете: Claude Code, Codex или оба.
2. Добавьте CLAUDE.md или AGENTS.md.
3. Создайте memory.md и plan.md, если их нет.
4. Вынесите сырые материалы в raw/.
5. Создайте business/INDEX.md и business/project-summary.md.
6. Важные бизнес-факты дистиллируйте в тематические файлы.
7. Неизвестные факты записывайте в open-questions.md.

Главное - не превращать новую структуру ещё в один склад. Её задача - помочь агенту быстро найти нужный контекст.

Типичные ошибки

• Писать все правила, память и план в один файл.
• Дублировать разные инструкции в CLAUDE.md и AGENTS.md.
• Класть сырые транскрипты прямо в memory.md.
• Не вести plan.md, из-за чего агент каждый раз начинает с нуля.
• Не фиксировать открытые вопросы.
• Не иметь evals/, то есть проверок качества результата.

FAQ

Что лучше создать: CLAUDE.md или AGENTS.md?

Если Вы работаете в Claude Code, создайте CLAUDE.md. Если работаете в Codex, создайте AGENTS.md. Если используете оба инструмента, можно иметь оба файла, но не дублировать в них разные правила.

Одинаковые ли CLAUDE.md и AGENTS.md?

По роли они очень похожи: это стартовые инструкции для AI-агента. Разница в том, что разные системы читают разные файлы. Поэтому структура правил может быть почти одинаковой, но название файла зависит от инструмента.

Как экономить токены в Claude Code и Codex?

Не заставляйте агента читать всё подряд. Сделайте файл правил роутером, project-summary.md короткой выжимкой, business/INDEX.md картой контекста, а сырые материалы держите в raw/.

Нужна ли папка business/ в каждом проекте?

Она особенно нужна, если AI работает с продуктом, маркетингом, рекламой, продажами, контентом или клиентскими знаниями. Для чисто технического проекта можно начать с минимальной структуры и добавить business/ позже.

Бонус: готовый промпт для Claude Code или Codex

Скопируйте этот промпт в Claude Code или Codex, открыв корень нового или существующего проекта. Он поможет агенту создать структуру аккуратно: без удаления старых файлов, без дублирования правил и без выдумывания бизнес-фактов.

Ты работаешь в корне моего проекта. Нужно настроить файловую структуру для работы с AI-агентом в Claude Code или Codex.

Главные правила:
1. Сначала проверь, какие файлы и папки уже существуют.
2. Не удаляй, не переименовывай и не перезаписывай существующие файлы без моего разрешения.
3. Если файл уже существует, не заменяй его полностью. Аккуратно добавь только недостающий короткий блок или предложи изменения.
4. Если факт о бизнесе неизвестен, запиши его в business/open-questions.md, не выдумывай.

Файл правил:
- если ты работаешь в Claude Code, основной файл правил - CLAUDE.md;
- если ты работаешь в Codex, основной файл правил - AGENTS.md;
- если в проекте нужны оба файла, один сделай главным, а второй коротким loader-файлом, который ссылается на главный.

Создай или дозаполни такую структуру:

CLAUDE.md или AGENTS.md
memory.md
plan.md
raw/

business/
  INDEX.md
  project-summary.md
  open-questions.md
  products/
    catalog.md
    offer-matrix.md
  audience/
    segments.md
  marketing/
    funnel.md
  economics/
    unit-economics.md
  voice/
    tone-of-voice.md

outputs/
evals/
archive/

В файл правил добавь короткий маршрут для агента:
1. Сначала читать файл правил.
2. Для текущего состояния читать plan.md.
3. Для стабильных фактов читать memory.md.
4. Для бизнеса, маркетинга, рекламы, продаж и контента читать business/INDEX.md.
5. Сырые источники искать в raw/.
6. Готовые результаты сохранять в outputs/.
7. Неизвестные факты записывать в business/open-questions.md.

В business/INDEX.md создай карту бизнес-файлов.
В business/project-summary.md создай короткий шаблон: что за бизнес, продукты, аудитория, оффер, боли/желания/возражения, экономика, tone of voice, текущая цель, ссылки на полные файлы.
В plan.md создай короткий блок: текущая задача, следующие шаги, блокеры, как проверить результат.
В memory.md создай место для стабильных фактов и важных решений.
В evals/ создай простой checklist проверки структуры.

После выполнения покажи:
- какие файлы созданы;
- какие файлы обновлены;
- какие вопросы остались открытыми;
- как проверить, что структура работает.

Вывод

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

Этот подход можно использовать как основу, но адаптировать под свой инструмент и свой бизнес. Если нужен Claude Code - начните с CLAUDE.md. Если нужен Codex - начните с AGENTS.md. Если нужна система для бизнеса, добавьте business/ и научите агента работать с фактами, а не с предположениями.

Именно так строятся AI-агенты, которые работают по правилам и базе знаний компании, а не выдумывают ответы из головы.