AI-friendly документация

CLAUDE.md

Рекомендация: Держите этот файл в репозитории относительно небольшим (не более 200 строк, лучше меньше) и при необходимости ссылайтесь в нём на другую документацию.

Пример содержания CLAUDE.md

Базовые правила:

  • Это репозиторий проекта X — описание проекта. В этом репозитории находится API, которая возвращает JSON с результатами.
  • Любые Python-скрипты запускай через энв /home/$USER/.virtualenvs/PROJECT_NAME.
  • Если не можешь решить какую-то проблему через несколько попыток — лучше уточни у меня.
  • Все комментарии в коде пишем на русском языке.
  • Перед написанием кода проверяй, нет ли уже дублирующегося или очень похожего кода.
  • Все импорты только сверху файла, никаких инлайн-импортов.

НИКОГДА без моего явного разрешения:

  • Не выключай, не удаляй и не изменяй логику тестов, если они не проходят.
  • Не изменяй бизнес-логику проекта.
  • Не используй --no-verify при коммитах.
  • Не добавляй все unstaged-файлы в коммит при помощи git commit -A или git add ..
  • Не добавляй фоллбеки без моего явного разрешения.

Инструментарий:

  • Для трекинга экспериментов мы используем ClearML.
  • Для хранения кода используются Azure и Github.
  • В проекте настроены следующие MCP. По умолчанию они выключены.

Верификация работы:

  • Пример скрипта, который тестирует корректность работы — test_train_loop.py. Всегда запускай его после любых изменений.

Документация:

  • Описание структуры репозитория лежит в docs/CODEMAP.md.
  • Описание бизнес-логики проекта лежит в docs/BUSINESS_LOGIC.md.

Частые ошибки:

  • Ты часто пытаешься откатиться на синтетические данные, если реальные данные недоступны. Не делай так — уточни у меня.
  • Ты часто теряешь нужные команды при компактизации контекста. Записывай команды во временный md-файл.

Персональный CLAUDE.md: Если нужно добавить какие-то свои инструкции (например, какой энв питона использовать), то можно сложить их в ~/.claude/CLAUDE.md. Claude Code прочитает все инструкции и сложит их в контекст вместе.

Если хотите использовать более разветвлённую структуру, то можно положить отдельные маркдауны в .claude/rules/, они тоже подгрузятся в контекст сессии автоматически. Например, rules/code-style.md, rules/testing.md.

Внимание: НЕ используйте /init для создания CLAUDE.md. По большей части он напихает бесполезного содержимого. Можно запустить в начале, посмотреть, что он сгенерит и выкинуть всё лишнее или перенести в другие файлы документации.

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

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

Если вы используете несколько инструментов (например, Codex), то можно создать симлинк:

ln -s CLAUDE.md AGENTS.md

Подробнее о CLAUDE.md и памяти Claude Code можно почитать тут.

Прочая документация

В папку документации можно положить всю дополнительную документацию по проекту, которую Claude может прочитать по запросу. Либо можно прямо на неё сослаться в описании задачи через @docs/ARCHITECTURE.md.

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

Альтернативный подход — создать папку ai_docs/, где будет содержаться документация именно для ИИ-агента.

Примеры часто используемых файлов:

  • ARCHITECTURE.md - описание архитектуры проекта
  • MODEL_CARD.md - описание ML-архитектуры проекта
  • DATASETS.md - описание основных датасетов
  • CODEMAP.md - описание структуры репозитория
  • DECISION_LOG.md - лог архитектурных и бизнесовых решений
  • GLOSSARY.md - список часто используемых терминов
  • TROUBLESHOOTING.md - частые проблемы и как их решать
  • CONVENTIONS.md / CONTRIBUTING.md - гайд по разработке проекта
  • API.md - описание структуры API

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

  • Не раздувайте документацию. Если что-то можно понять из кода, лучше указать “прочитай актуальное состояние в таком-то файле”
  • Сделайте скилл обновления документации и просите использовать его перед коммитом

Следующая: MCP и CLI

Предыдущая: Работа над фичей