Гигиена проекта при работе с ИИ: когда проект живёт месяцами — как не потерять контекст, решения и проверки

В коротких экспериментах с ИИ всё выглядит просто: дал задачу, получил код, поправил пару ошибок, пошёл дальше.

Проблемы начинаются позже — когда проект живёт не один вечер, а несколько недель или месяцев. Чат помнит не всё. Документация устаревает. Решения остаются в истории переписки. Один ИИ-инструмент помогает проектировать, другой работает с файлами и кодом, третий чат используется для ревью, а владелец проекта постепенно превращается в ручной мост между всеми этими кусками контекста.

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

Я называю набор практик для решения этой проблемы Project Hygiene — гигиена проекта. Это не отдельный промпт и не ещё один способ «правильно общаться с нейросетью». Это способ организовать проектную память, проверки и передачу состояния так, чтобы длинная работа с ИИ-инструментами не расползалась после нескольких сессий.

Сразу ограничу рамку. Я не разработчик по профессии. Моя зона — управление коммерческими проектами, e-commerce и операционные системы. ИИ-инструменты для меня — не способ заменить инженеров, а способ быстрее проектировать, проверять гипотезы, собирать рабочие артефакты и удерживать сложный проект в управляемом состоянии.

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

Что ломается в длинных проектах с ИИ

Пока проект маленький, почти вся память помещается в голове владельца и в текущем чате. Можно помнить, что уже решили, какие файлы меняли, где лежит актуальная версия, какие ошибки уже ловили и какие ограничения нельзя нарушать.

Но у длинного проекта появляется другая динамика.

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

У меня это стало заметно на коммерческом e-commerce проекте. Система росла быстро: backend, интеграции, правила ценообразования, заказы, проверки, тесты, документация. Часть работы шла через Claude Code — ИИ-инструмент, который работает с локальными файлами, командами и кодовой базой. Параллельно использовались архитектурные чаты, где проектировались решения и готовились задачи для исполнения.

На короткой дистанции это ускоряло работу. На длинной — начало создавать рассинхронизацию.

Типовые симптомы были такими.

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

Второй симптом — документация расходится с реальностью. В файле написано одно количество тестов, в коде уже другое. В описании модуля указан старый статус. В списке ограничений лежит правило, которое уже покрыто тестами или устарело. ИИ не обязательно врёт — он просто опирается на тот контекст, который ему дали. Если этот контекст устарел, ответы тоже начинают устаревать.

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

Четвёртый симптом — владелец становится ручной памятью проекта. Вместо того чтобы принимать решения, он начинает постоянно объяснять: «это уже делали», «это нельзя», «здесь старый статус», «вот это решение было принято в другом чате», «этот файл не трогать», «здесь надо сначала прогнать тесты». Чем длиннее проект, тем дороже становится такая ручная память.

Именно в этот момент стало понятно: проблема не решается более подробным промптом. Нужна внешняя проектная память.

Почему одного хорошего промпта мало

Вокруг ИИ-инструментов много разговоров про промпты. Это понятно: хороший запрос действительно помогает получить лучший ответ. Но в длинном проекте промпт решает только часть задачи.

Промпт может объяснить, что нужно сделать сейчас. Он может задать тон, роль, ограничения текущей задачи. Но он плохо подходит для хранения проектной истории.

У длинного проекта есть несколько типов знаний.

Есть текущее состояние: что уже собрано, что сломано, какие тесты проходят, какие задачи открыты.

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

Есть история решений: почему выбрали один подход, а не другой.

Есть рабочие инструкции для ИИ-инструмента: как запускать проверки, какие команды безопасны, какие файлы нельзя читать, какие шаблоны обновлять после изменения модуля.

Если всё это держать в одном большом промпте, он быстро превращается в свалку. Туда попадает и текущее состояние, и старые решения, и правила, и временные заметки, и инструкции на один раз. Через несколько недель уже непонятно, что из этого актуально.

Проблема усиливается тем, что разные виды информации стареют с разной скоростью.

Например, количество тестов может измениться сегодня. Статус модуля может измениться после одного коммита. А правило «не хранить секреты в коде» или решение «все значимые архитектурные решения фиксировать в ADR» может жить месяцами.

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

Поэтому для длинного проекта нужен не один хороший промпт, а разделение знаний по слоям.

Что я называю Project Hygiene

Project Hygiene — это набор правил и артефактов, которые помогают удерживать проект в актуальном состоянии при работе с ИИ-инструментами.

В центре подхода не модель и не конкретный сервис. В центре — проектная память.

Идея простая: если ИИ-инструмент участвует в длинной работе, ему нельзя каждый раз заново объяснять проект из головы владельца. У проекта должны быть внешние артефакты:

• где зафиксировано текущее состояние;

• где лежат устойчивые правила;

• где описаны принятые решения;

• где хранится история проверок;

• где записано, что передать следующей сессии;

• где указано, какие действия нельзя выполнять без контроля.

При этом эти артефакты должны быть не просто «документацией ради документации». Они должны участвовать в рабочем цикле. Если файл не обновляется, не проверяется и не используется, он быстро становится вредным: ИИ начинает опираться на устаревший источник.

Поэтому Project Hygiene состоит не из одного документа, а из контура:

проектная память → рабочая память ИИ-инструмента → проверки → передача состояния → обновление контекста

В моём случае этот контур оформился вокруг нескольких элементов:

• опорные файлы проекта;

• структура .claude/ для Claude Code;

• команда /session-close;

• проверки актуальности документации;

• ротация длинных чатов;

• архитектурные записи решений;

• разделение публичной документации, рабочих инструкций и архива.

.claude/ — это папка с настройками, правилами, командами и навыками для Claude Code. В ней можно хранить не только общий файл CLAUDE.md, но и отдельные правила, команды, шаблоны сессий, проверки и рабочие инструкции. В методологии это не «магическая папка», а место, где живёт рабочая память исполнительного ИИ-инструмента.

/session-close — команда закрытия сессии. Её задача — не красиво подвести итог, а собрать структурированный снимок состояния: что изменилось, какие проверки прошли, какие проблемы остались, что делать следующим шагом.

Такой подход не делает ИИ безошибочным. Наоборот, он исходит из того, что ИИ будет забывать, путаться и опираться на устаревший контекст, если не построить вокруг него нормальную систему памяти и проверок.

Дальше покажу, как я эту систему разложил: сначала по слоям знаний, потом по файлам, потом по рабочему циклу.

Четыре слоя проектной памяти

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

В одном месте могли оказаться:

• текущее количество тестов;

• архитектурное решение месячной давности;

• временная заметка из последней сессии;

• бизнес-правило, которое нельзя нарушать;

• устаревший обходной путь;

• задача, которая уже закрыта;

• ограничение, которое всё ещё критично.

Для человека это ещё можно распутать. Для ИИ-инструмента это быстро становится плохим контекстом. Он видит текст, но не всегда понимает, что в нём актуально, что устарело, что является правилом, а что было временной заметкой.

Поэтому первый принцип Project Hygiene — разделить проектную память по слоям.

Я использую четыре слоя.

1. Живое состояние

Это то, что существует прямо сейчас: код, тесты, база данных, ветка Git, незакоммиченные изменения, текущие ошибки, реальные результаты команд.

Источник правды здесь — не документ и не чат, а сам проект.

Если в файле написано, что тестов 551, а команда показывает другое число, верить нужно команде. Если в описании модуля указан старый статус, а код уже изменился, верить нужно коду и проверкам.

Этот слой нельзя качественно держать в голове. Его нужно регулярно снимать командами и превращать в структурированный снимок.

2. Текущий снимок состояния

Живое состояние слишком объёмное, чтобы каждый раз передавать его в чат целиком. Поэтому нужен короткий снимок: что изменилось, что работает, что сломано, какие проверки прошли, что делать следующим шагом.

В моей методологии эту роль выполняет SNAPSHOT.

SNAPSHOT — снимок состояния проекта. Обычно он удобнее в машинном формате: например, в YAML. YAML — текстовый формат для структурированных данных, который хорошо подходит для списков, статусов и вложенных полей.

Такой снимок не должен пересказывать весь проект. Его задача — дать следующей сессии минимально достаточное понимание текущего состояния.

Примерно так:

meta:
  date: 2026-05-01
  session_status: closed

git:
  branch: main
  status: clean

tests:
  total: 551
  passed: true

docs:
  updated:
    - methodology.md
    - README.md

next_step:
  - review public article draft

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

3. Стабильные знания

Есть информация, которая меняется редко.

Например:

• какие ограничения нельзя нарушать;

• какие бизнес-правила уже приняты;

• какие решения считаются базовыми;

• какие ошибки уже были найдены;

• какие действия требуют проверки;

• какие файлы являются источниками правды.

Это не нужно переписывать после каждой сессии. Но это нужно держать отдельно от текущего состояния.

Если смешать стабильные правила с текущими задачами, через несколько недель файл превращается в свалку: часть строк всё ещё важна, часть уже устарела, часть была временной.

Для этого слоя у меня используются файлы вроде KNOWLEDGE и PROCESS.

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

4. Архив решений

Наконец, есть история. Она не должна каждый день лежать в горячем контексте, но её нельзя терять.

Например:

• почему выбрали один подход, а не другой;

• какие варианты отклонили;

• какие ошибки уже были исправлены;

• какие решения позже стали неактуальными;

• какие аудиты показали расхождения.

Для этого подходит ADR.

ADR — архитектурная запись решения: короткий документ, который объясняет, какое решение принято, почему оно принято и какие последствия у него есть.

В длинном проекте ADR важен не только для людей. Он помогает ИИ-инструменту не предлагать одно и то же решение повторно, не возвращаться к уже отклонённым вариантам и понимать мотивы кода.

Если коротко, четыре слоя выглядят так:

Главное здесь не в названиях файлов. Главное — не смешивать разные типы памяти.

Текущее состояние должно проверяться.
Стабильные правила должны быть короткими и актуальными.
История должна сохраняться, но не засорять рабочий контекст.
Следующая сессия должна получать не весь архив, а нужный слой.

Пять опорных файлов

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

В моей версии это пять опорных файлов.

Они не обязаны называться именно так в каждом проекте. Важнее роли, которые они выполняют. Но стабильные названия удобны: новый чат, новый ИИ-инструмент или новый рабочий контур быстрее понимает структуру проекта.

1. PROJECT_BRIEF

PROJECT_BRIEF — это короткое описание текущего проекта.

Он отвечает на вопросы:

• что это за проект;

• какая сейчас фаза;

• какие основные модули есть;

• что готово;

• что сломано или не проверено;

• какой следующий шаг;

• где лежат остальные источники правды.

Это не место для всей истории проекта. Его задача — быстро вернуть человека или ИИ-инструмент в рабочий контекст.

Если PROJECT_BRIEF становится длинным, он перестаёт выполнять свою функцию. Это не энциклопедия проекта, а карта.

2. SNAPSHOT

SNAPSHOT — это снимок состояния после рабочей сессии.

Он ближе к техническому отчёту, чем к обычной документации.

В него попадает то, что можно проверить:

• текущая ветка;

• статус Git;

• последний коммит;

• сколько тестов прошло;

• какие файлы менялись;

• какие проверки запускались;

• какие проблемы остались;

• что делать следующим шагом.

Здесь важно не превращать snapshot в литературный отчёт. Чем он структурированнее, тем меньше шансов, что следующая сессия поймёт его неправильно.

Плохой snapshot:

«Сегодня многое сделали, вроде всё работает, надо продолжать».

Хороший snapshot:

«Ветка main, статус clean, тестов 551, проверки прошли, следующий шаг — ревью публичной статьи».

Разница простая: первый вариант нельзя проверить, второй можно.

3. KNOWLEDGE

KNOWLEDGE хранит стабильные знания проекта.

Это не текущее состояние и не список задач. Это то, что должно оставаться актуальным долго:

• бизнес-правила;

• технические ограничения;

• инварианты;

• известные ловушки;

• правила безопасности;

• ссылки на важные решения;

• то, что нельзя менять без отдельного обсуждения.

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

Если в проекте уже была ошибка из-за неправильного формата данных, и теперь есть правило, как её не повторять, это тоже KNOWLEDGE.

4. PROCESS

PROCESS описывает не состояние проекта, а способ работы.

Например:

• кто принимает решения;

• когда запускать проверки;

• когда обновлять документы;

• как закрывать сессию;

• когда ротировать чат;

• когда создавать ADR;

• что считается готовым результатом;

• что нельзя делать без подтверждения владельца.

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

Если PROCESS не зафиксирован, каждый новый чат начинает заново угадывать правила. Иногда угадывает правильно, иногда нет.

5. HANDOFF

HANDOFF — это передача состояния между сессиями.

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

Хороший HANDOFF отвечает на четыре вопроса:

• что делали;

• что получилось;

• на чём остановились;

• что делать следующим шагом.

Это не архив и не отчёт для руководства. Это короткая записка для продолжения работы.

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

Если коротко, роли файлов такие:

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

Рабочая память ИИ-инструмента

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

Но у исполнительного ИИ-инструмента есть другая проблема. Ему нужны не только общие сведения о проекте, а рабочие инструкции: как действовать внутри репозитория.

Например:

• какие команды можно запускать;

• какие файлы нельзя читать;

• какие проверки обязательны;

• какие правила действуют для конкретной папки;

• какой формат коммита использовать;

• какие ловушки есть в конкретном модуле;

• как закрывать сессию;

• как обновлять локальную документацию.

Если всё это положить в один огромный файл, он быстро станет нечитаемым. Поэтому в Project Hygiene рабочая память исполнительного инструмента разносится по структуре.

В случае Claude Code центральную роль играет CLAUDE.md.

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

Но один CLAUDE.md не должен превращаться в энциклопедию. В хорошем варианте он остаётся коротким и работает как навигация.

Например, в нём можно держать:

• краткое описание проекта;

• основные правила;

• ссылки на опорные файлы;

• ссылки на отдельные правила;

• важные команды;

• запреты;

• требование запускать проверки перед коммитом.

Всё, что становится слишком подробным, лучше выносить в отдельные файлы.

Для этого используется папка .claude/.

В ней можно разделить рабочую память по типам.

Главный смысл этой структуры не в том, чтобы завести много папок ради порядка. Смысл в том, чтобы не смешивать разные виды инструкций.

Правило должно быть правилом.
Навык должен быть навыком.
Команда должна быть командой.
Проверка должна быть проверкой.

Если всё лежит в одном файле, ИИ-инструменту трудно понять, что обязательно, что справочно, что относится к конкретной задаче, а что уже устарело.

Здесь появляется важная разница между документацией для человека и рабочей памятью для ИИ.

Документация для человека должна объяснять.
Рабочая память ИИ должна направлять действие.

Поэтому публичные документы можно писать развернуто, на русском, с пояснениями. А runtime-файлы для Claude Code — то есть файлы, которые инструмент читает во время работы, — можно вести компактнее и часто на английском.

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

В моём репозитории это разделено именно так: публичные объясняющие документы написаны на русском, а часть файлов .claude/ — на английском, потому что они предназначены для Claude Code.

Следующий элемент, который всё связывает, — /session-close.

/session-close: как закрывать сессию, чтобы следующая не начиналась с нуля

Один из самых дорогих сбоев в длинной работе с ИИ возникает в момент завершения сессии.

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

Поэтому в Project Hygiene закрытие сессии — это не формальность. Это отдельная рабочая процедура.

Я использую для этого команду /session-close.

Её смысл простой: в конце рабочей сессии не просто остановиться, а оставить после себя короткий и понятный снимок состояния.

Хорошая процедура закрытия сессии фиксирует:

• что было сделано;

• какие файлы изменились;

• какие проверки были запущены;

• что прошло успешно;

• что не прошло;

• какие риски или открытые вопросы остались;

• с какого шага продолжать дальше.

Важно, что /session-close — это не красивое резюме в стиле «мы сегодня хорошо поработали». Это инструмент передачи состояния.

Если закрытие сессии сделано хорошо, следующая сессия не начинается с вопроса: «что тут вообще происходит?». Она начинается с продолжения работы.

Что обычно попадает в /session-close

Обычно я ожидаю от такой команды шесть блоков.

1. Что изменили

Короткий список изменений по сути: модуль, документ, правило, структура, проверка.

2. Что проверили

Какие команды запускались, какие тесты проходили, что проверено руками.

3. Текущее состояние

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

4. Открытые проблемы

Что ещё не решено, что требует проверки, где остались риски.

5. Следующий шаг

Не общий пункт «продолжить работу», а конкретное действие.

6. Что нужно передать следующей сессии

Какие ограничения, решения и наблюдения нельзя потерять.

Здесь важен ещё один момент: /session-close должен быть достаточно коротким.

Если он превращается в длинный рассказ на несколько экранов, его перестают читать как рабочий артефакт. Хороший handoff экономит время. Плохой handoff создаёт ещё один слой шума.

Handoff — передача состояния: короткий документ или сообщение, которое позволяет следующей сессии продолжить работу без восстановления всего контекста вручную.

Почему это особенно важно в длинных проектах

В короткой задаче потеря состояния не так страшна. Можно за десять минут восстановить, что происходило.

В длинном проекте цена потери выше.

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

Именно поэтому в методологии закрытие сессии — не приятное дополнение, а обязательная часть цикла.

Рабочий цикл выглядит так:

сессия работы → изменения → проверки → /session-close → обновление проектной памяти → следующая сессия

То есть сессия считается завершённой не в тот момент, когда модель перестала отвечать, а в тот момент, когда состояние проекта передано дальше.

Что это меняет на практике

После появления такой процедуры у меня изменилась сама логика работы с ИИ.

Раньше новая сессия часто начиналась с восстановления памяти.
Теперь она чаще начинается с действия.

Раньше часть решений жила в переписке.
Теперь важное должно переходить либо в опорные файлы, либо в handoff, либо в ADR.

Раньше закрытие работы было естественной остановкой.
Теперь это отдельная операция качества.

На первый взгляд это добавляет бюрократию. На практике — экономит время. Особенно после десятой, двадцатой и тридцатой сессии.

Проверки: почему нельзя верить ни чату, ни документации без верификации

Следующая проблема появляется быстро: даже если структура памяти уже есть, она сама по себе не гарантирует актуальность.

Документ может быть хорошо написан и всё равно устареть.

В README может быть указано одно количество тестов, а в проекте уже другое. В описании модуля может стоять старый статус. В списке ограничений может остаться правило, которое уже покрыто тестами или перестало быть актуальным.

ИИ-инструмент не обязательно ошибается из-за «галлюцинаций». Иногда он просто честно опирается на старый файл.

Поэтому в Project Hygiene важны не только документы, но и проверки.

Я разделяю проверки на три уровня.

Уровень 1. Проверки внутри рабочей сессии

Это базовые проверки, которые должны происходить во время работы:

• тесты прошли или нет;

• статус Git чистый или есть незакоммиченные изменения;

• документация обновлена или нет;

• изменился ли модуль, у которого есть отдельные правила;

• появились ли новые ограничения, которые нужно вынести в KNOWLEDGE или ADR.

На этом уровне важно не доверять ощущениям.

Плохо:

«Вроде всё работает».

Лучше:

«Запущены такие-то тесты, результат такой-то, незакоммиченных изменений нет».

Для ИИ-инструмента такая разница критична. Он должен передавать следующей сессии не настроение, а проверяемое состояние.

Уровень 2. Проверка документации против реальности

Второй уровень — сверка документов с проектом.

Например, в документе написано:

• 551 тест;

• 12 таблиц базы данных;

• 7 файлов CLAUDE.md;

• модуль заказов готов;

• структура .claude/ актуальна.

Каждое такое утверждение желательно проверять командой, если это возможно.

Если число тестов можно получить через запуск тестового набора, не нужно хранить его как вечную истину. Если количество файлов можно проверить через поиск по репозиторию, не нужно полагаться на старую запись в документе.

Главный принцип здесь такой:

измеримое утверждение должно иметь способ проверки.

Если способа проверки нет, нужно хотя бы пометить, что это экспертная оценка, а не факт.

Уровень 3. Периодический аудит

Третий уровень — периодический аудит структуры.

Он нужен не после каждой сессии, а через несколько рабочих циклов.

В таком аудите можно проверять:

• не разросся ли корневой CLAUDE.md;

• не дублируются ли знания между docs/ и .claude/skills/;

• не устарели ли ADR;

• не появились ли правила, которые никто не читает;

• не лежат ли временные заметки в стабильных файлах;

• не смешались ли текущий статус и архив;

• не появились ли расхождения между документацией и реальностью.

Один из полезных результатов такого аудита — список расхождений.

Например:

Такие проверки не делают проект идеальным. Но они не дают ему медленно превращаться в набор красивых, но устаревших файлов.

Почему важны ADR

В длинной работе с ИИ есть ещё одна проблема: модель может видеть результат, но не всегда понимает мотив.

Она видит, что код устроен определённым образом. Видит файлы, названия функций, тесты, структуру папок. Но из этого не всегда понятно, почему было принято именно такое решение.

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

Если такие решения остаются только в переписке, следующий чат их не знает. Он может предложить «улучшение», которое уже обсуждали и отклонили. Или вернуть старую идею, потому что она выглядит логичной в отрыве от истории.

Для этого нужны ADR.

ADR — архитектурная запись решения. Это короткий документ, который фиксирует:

• какое решение принято;

• почему оно принято;

• какие альтернативы рассматривались;

• какие последствия у решения есть;

• где это решение реализовано или проверено.

ADR нужен не для бюрократии. Он нужен, чтобы не принимать одно и то же решение заново каждые две недели.

Хороший ADR отвечает на вопрос:

«Почему здесь так, а не иначе?»

Это отличается от комментария в коде.

Комментарий объясняет локальный фрагмент. ADR объясняет решение на уровне проекта.

Например:

В Project Hygiene ADR попадает в архив решений. Он не должен каждый день лежать в горячем контексте, но к нему должна быть ссылка из опорных файлов, skills или документации.

Если коротко:

• код показывает, что сделано;

• тесты показывают, что работает;

• документация объясняет, как пользоваться;

• ADR объясняет, почему выбрали именно так.

Без ADR проект теряет не только состояние, но и память о мотивах решений.

Ротация чатов: когда пора начинать новый

Отдельный элемент Project Hygiene — ротация чатов.

Чат с ИИ не должен жить бесконечно. Даже если он всё ещё отвечает уверенно, это не значит, что он точно держит контекст.

В длинных чатах постепенно появляются типовые признаки деградации:

• модель путает числа;

• забывает решения из начала чата;

• начинает повторно предлагать уже отклонённые варианты;

• хуже различает актуальное и устаревшее;

• просит заново объяснить то, что уже было зафиксировано;

• уверенно формулирует менее точные ответы.

Поэтому ротация чата — это не аварийная мера, а нормальная рабочая процедура.

Я ориентируюсь на три сигнала.

Первый сигнал — чат стал слишком длинным

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

Длинный чат опасен тем, что в нём накапливается слишком много разнородного контекста: старые гипотезы, временные решения, уже закрытые задачи, промежуточные ошибки.

Человек ещё может помнить, что из этого актуально. Модель — не всегда.

Второй сигнал — изменилась фаза работы

Например, сначала обсуждали архитектуру, потом перешли к реализации, потом к аудиту. Это разные режимы.

Архитектурный чат должен держать причины решений.
Рабочая сессия должна держать файлы, команды и проверки.
Аудит должен искать расхождения.

Если всё это вести в одном бесконечном чате, контекст смешивается.

Третий сигнал — появились ошибки памяти

Если ИИ путает факты или опирается на старые данные, не нужно героически продолжать. Нужно закрыть сессию, обновить опорные файлы и начать новый чат.

Хорошая ротация выглядит так:

1. Завершить текущую рабочую сессию.

2. Выполнить /session-close.

3. Обновить PROJECT_BRIEF, SNAPSHOT и HANDOFF.

4. Перенести важные решения в KNOWLEDGE или ADR.

5. Открыть новый чат.

6. Дать ему актуальные опорные файлы.

7. Проверить, что он правильно понял состояние проекта.

Главное — не ждать, пока чат окончательно деградирует.

Если закрывать чат слишком поздно, он уже хуже справляется с самым важным действием: качественно передать состояние дальше.

Как это работает как цикл

Вся эта структура не имеет смысла, если воспринимать её как папку с документами.

Project Hygiene работает только как цикл.

Сначала есть задача.
Потом ИИ-инструмент работает с кодом, файлами или документами.
Потом запускаются проверки.
Потом сессия закрывается через /session-close.
Потом обновляются опорные файлы.
Потом следующая сессия начинает работу уже не с нуля, а с актуального состояния.

Если убрать проверки, методология превращается в красивую документацию.

Если убрать /session-close, состояние будет теряться между сессиями.

Если убрать ADR, решения будут повторно обсуждаться.

Если убрать разделение слоёв, всё снова окажется в одном большом промпте.

Если убрать ротацию чатов, контекст начнёт деградировать.

Поэтому Project Hygiene — это не один файл CLAUDE.md и не набор «лучших промптов». Это контур работы:

проектная память → рабочая память ИИ-инструмента → проверки → передача состояния → ротация чатов → аудит

Именно контур делает подход полезным на длинной дистанции.

Кейс: e-commerce backend, который быстро вырос за счёт ИИ-сессий

Методология появилась не из желания красиво разложить файлы по папкам. Она появилась из практической проблемы.

Проект-источник — коммерческая backend-система для e-commerce. Backend — серверная часть системы: логика заказов, интеграции, база данных, расчёты, проверки, внутренние процессы.

Система должна была держать несколько типов сущностей:

• товары;

• поставщиков;

• заказы;

• цены;

• правила обработки;

• интеграции;

• документы;

• проверки;

• внутренние статусы.

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

В какой-то момент работа шла через несколько параллельных сессий Claude Code в разных рабочих деревьях Git.

git worktree — рабочее дерево Git: отдельная рабочая папка одного репозитория, которая позволяет параллельно работать в разных ветках без постоянного переключения контекста.

Это удобно: одна сессия может заниматься одним модулем, другая — другим, третья — миграцией или проверками.

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

Иначе через несколько дней уже непонятно:

• какие решения были приняты в какой ветке;

• какие проверки реально проходили;

• какие файлы стали источниками правды;

• какие ограничения появились по ходу;

• какие старые решения уже нельзя использовать;

• какие заметки временные, а какие стали правилом.

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

Что получилось по масштабу

В обезличенном виде проект выглядел так:

Эти цифры важны не как демонстрация масштаба. Важнее другое: даже на таком размере проект уже нельзя удерживать только перепиской и памятью владельца.

Пока файлов мало, можно вручную помнить, что где лежит. Когда появляются десятки файлов, сотни тестов, несколько CLAUDE.md, ADR и параллельные рабочие ветки, ручная память начинает ломаться.

Что пошло не так

Самый полезный вывод был не в том, что ИИ ускорил старт. Это ожидаемо.

Полезнее оказалось увидеть, где ускорение создаёт новые риски.

Первый риск — документация начала отставать.

Проект менялся быстрее, чем обновлялись описания. В одном месте уже был новый статус, в другом — старый. В одном файле была актуальная структура, в другом — промежуточная.

Для человека это раздражает. Для ИИ-инструмента это опаснее: он может уверенно опереться на старый документ.

Второй риск — рабочая память .claude/ начала расходиться с реальностью.

Когда структура .claude/ растёт, в ней появляются правила, skills, команды, агенты, hooks и tasks. Это удобно, пока границы понятны.

Но если не проводить аудит, начинается смешение:

• правило превращается в справку;

• skill начинает дублировать документацию;

• команда становится слишком длинной;

• корневой CLAUDE.md разрастается;

• часть инструкций никто не использует;

• часть правил устаревает.

Именно после такого аудита было найдено 18 расхождений в .claude/, которые пришлось исправлять отдельным коммитом.

Третий риск — ADR начали засорять контекст.

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

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

Если всё это дать ИИ-инструменту одним большим массивом, он может начать опираться на устаревшие решения.

Поэтому понадобился не только архив ADR, но и правила работы с ним: что считается активным решением, что историческим, что требует пересмотра.

Что помогло

В этом проекте Project Hygiene стала не теорией, а способом снизить хаос.

Помогло несколько вещей.

1. Разделение проектной памяти по слоям

Текущее состояние перестало смешиваться со стабильными правилами и архивом решений.

Если нужно понять, что происходит прямо сейчас, смотрим snapshot и проверки.
Если нужно понять, почему выбрали подход, смотрим ADR.
Если нужно понять ограничения, смотрим KNOWLEDGE.
Если нужно продолжить работу, смотрим HANDOFF.

2. Многоуровневые CLAUDE.md

Один корневой CLAUDE.md не должен знать всё.

В проекте появились несколько CLAUDE.md на разных уровнях: общий файл для всего проекта и локальные файлы для отдельных зон.

Это помогло не тащить все правила во все задачи.

Если сессия работает с конкретным модулем, ей нужны правила этого модуля, а не вся история проекта.

3. /session-close

Закрытие сессии стало обязательной операцией.

После сессии должно быть понятно:

• что изменилось;

• какие проверки прошли;

• что осталось открытым;

• какой следующий шаг;

• что нельзя потерять при переходе в новый чат.

Это особенно важно при параллельной работе. Когда несколько сессий идут одновременно, каждая должна оставлять после себя понятный след.

4. Аудиты

Периодический аудит оказался важнее, чем казалось сначала.

Он показал, что даже аккуратная структура со временем начинает расходиться с реальностью. Поэтому нужны проверки не только кода, но и самой проектной памяти.

Проверять нужно не только «работает ли программа», но и:

• соответствует ли документация фактам;

• не дублируются ли правила;

• не устарел ли snapshot;

• не разросся ли CLAUDE.md;

• не потерялись ли ADR;

• не смешались ли docs и skills.

Что не сработало идеально

Важно сказать и обратное: методология не делает проект автоматически управляемым.

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

Например, маленькому проекту не всегда нужны десятки skills, hooks и отдельных agents. Иногда достаточно README, одного CLAUDE.md, snapshot и handoff.

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

Поэтому Project Hygiene нельзя воспринимать как «создал папки — решил проблему».

Работает не структура сама по себе. Работает дисциплина обновления, проверки и передачи состояния.

Что я вынес из этого кейса

Главный вывод такой: ИИ ускоряет не только полезную работу, но и накопление хаоса.

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

Project Hygiene нужна, чтобы вынести эту память из головы владельца в артефакты:

• текущий статус — в SNAPSHOT;

• устойчивые правила — в KNOWLEDGE;

• порядок работы — в PROCESS;

• передачу состояния — в HANDOFF;

• причины решений — в ADR;

• рабочие инструкции ИИ — в CLAUDE.md и .claude/;

• проверку актуальности — в аудиты и команды.

После этого ИИ-инструмент не становится самостоятельным владельцем проекта. Но он получает более качественный контекст, а владелец перестаёт вручную пересказывать одно и то же между сессиями.

Что можно взять в свой проект

Я не думаю, что эту структуру нужно копировать целиком в каждый проект.

Если проект маленький, полный набор .claude/, skills, hooks, agents, ADR и аудитов может быть избыточным. Иногда достаточно трёх вещей:

• короткого описания проекта;

• снимка состояния после сессии;

• правил, которые нельзя нарушать.

Но если проект живёт неделями или месяцами, минимальный набор я бы всё равно сделал.

Минимальный старт

Для начала достаточно пяти файлов:

Этого уже хватает, чтобы не держать всю память в одном чате.

Следующий уровень

Если в проекте появляется исполнительный ИИ-инструмент, который работает с файлами и кодом, я бы добавил:

• CLAUDE.md или аналогичный файл инструкций;

• отдельные правила для критичных зон;

• команду закрытия сессии;

• простой формат ADR;

• проверку актуальности документации.

На этом уровне важно не количество файлов, а границы между ними.

Один файл отвечает за текущее состояние.
Другой — за правила.
Третий — за процесс.
Четвёртый — за передачу состояния.
Пятый — за причины решений.

Когда эти роли смешиваются, проект снова начинает терять память.

Что точно не стоит делать

Я бы не начинал с большой структуры ради структуры.

Не стоит заводить десятки папок, если непонятно, кто и когда будет их обновлять.

Не стоит превращать CLAUDE.md в длинную энциклопедию проекта.

Не стоит хранить временные заметки рядом со стабильными правилами.

Не стоит считать документацию источником истины, если её никто не сверяет с реальным состоянием проекта.

Не стоит оставлять длинный чат открытым только потому, что он ещё отвечает уверенно.

Главный принцип проще:

память проекта должна жить не только в чате.

Полная методология и репозиторий

В статье я не пересказываю всю методологию целиком. Она слишком объёмная для одного материала.

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

context-engineering-method

Репозиторий — это не продукт и не готовая программная основа. Это открытый набор материалов, который можно разобрать, сократить и адаптировать под свой проект.

Внутри:

• README.md — короткий вход в подход;

• methodology.md — полная публичная методология;

• .project/ — шаблоны проектной памяти;

• .claude/ — пример рабочей памяти Claude Code;

• examples/ — обезличенные примеры;

• playbooks/ — сценарии применения;

• templates/ — заготовки файлов;

• scripts/ и .github/workflows/ — демонстрационные проверки.

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

Вместо вывода

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

В длинных проектах этого мало.

Чем дольше живёт проект, тем важнее становится не отдельный ответ модели, а состояние всего контура: какие решения уже приняты, какие документы актуальны, какие проверки прошли, какой чат что знает и что нужно передать дальше.

Проблема не в том, что ИИ «плохо помнит». Проблема в том, что мы часто пытаемся использовать чат как единственное место для проектной памяти.

Project Hygiene для меня — попытка решить именно эту проблему.

Не заменить разработку промптами.
Не сделать ИИ самостоятельным владельцем проекта.
Не построить идеальную документацию.

А вынести память проекта в понятные артефакты и связать их с рабочим циклом:

состояние → правила → решения → проверки → передача контекста → следующая сессия

Когда этот контур появляется, ИИ-инструмент всё ещё ошибается. Документы всё ещё могут устаревать. Проверки всё ещё нужно запускать. Но проект перестаёт зависеть только от памяти владельца и истории переписки.

На длинной дистанции это и есть главный выигрыш.