Карта проекта для ИИ

Чтобы агент не перечитывал проект заново на каждый запрос, а сразу знал, где что лежит. Двадцать пунктов: от «нужно ли это тебе» до «как проверить, что стало лучше».

01 Сначала реши, нужна ли она вообще

• В проекте больше 30-40 файлов, и они разнородные: код, документация, схемы базы, PDF.
• Агент регулярно теряется: открывает не те файлы, переспрашивает про структуру.
• Ты ловил себя на том, что вручную объясняешь модели, где что лежит - и не первый раз.

02 Возьми идею у первоисточника

• Прочитай заметку llm-wiki Андрея Карпати - весь паттерн там на одну страницу.
• Главное правило: сырые источники не трогаем, вопросы задаём только собранному справочнику.
• Справочник живой: он дополняется новыми источниками, а не пересобирается с нуля каждый раз.

03 Собери карту

• Поставь graphify: uv tool install graphifyy, затем graphify install.
• Запусти в корне проекта: /graphify.
• Проверь, что появилась папка graphify-out/ с файлами graph.json, GRAPH_REPORT.md и graph.html.
• Открой graph.html и глазами пройдись по связям: похоже на твой проект или нет.
• Хочешь смотреть карту как хранилище заметок - добавь флаг --obsidian и открой её в Obsidian.

04 Положи её так, чтобы она не съедала контекст

• В CLAUDE.md - одна строка: где лежит карта и когда в неё смотреть. Не сама карта.
• Держи CLAUDE.md короче 200 строк: он грузится в каждую сессию целиком и ест контекст постоянно.
• Длинную инструкцию по работе с картой вынеси в скилл - его тело подгружается только при вызове.
• Добавь graphify-out/ в .gitignore, если карта пересобирается на каждой машине локально.

05 Проверь, что стало лучше

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

06 Как читать чужие цифры экономии

• Найди корпус замера. «52 тестовых файла» - это не твой проект и не твоя нагрузка.
• Посмотри, что стояло в знаменателе. «Против чтения всех файлов подряд» - сравнение с заведомо худшим способом работы.
• Проверь авторство. Автор идеи и автор кода - часто разные люди, и это меняет вес аргумента.
• Ищи абсолютные числа «было / стало». Есть только отношение - значит, нарисовать можно любое.

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