Что агент видит: контекст

1. Большой чужой проект нельзя свалить вслепую

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

Он пробует нащупать это вслух в чате, и Лёха его тормозит:

— С маленькой игрой этот номер пройдёт: внятно опишешь результат — и хватит, дальше дело агента. А работу над порталом так не свалишь. Он большой, чужой и ты сам в нём ещё не разобрался. Если сейчас закроешь его и убежишь к Minecraft, к вечеру вернёшься и будешь по новой соображать, что тут к чему. Давай хотя бы проговорим: что это за проект и что в нём где.

Неудобство какое-то новое. Тёма нехотя проходит по порталу глазами и называет вслух, что видит. Вот, кажется, общая витрина — то, что видит посетитель на входе. Вот что-то про начисление наград, очки какие-то. Вот лидерборд — таблица лучших. Вот бонусная игрушка внутри кампании. Вот отдельные партнёрские куски — про них он вообще ничего не понимает, чужое. Криво, на ощупь, половина вообще не понятно что и зачем. Но хотя бы это уже не «открыл и утонул в объёме» — он впервые сам разбивает кашу на куски с именами.

Скукота подступает к горлу и Тёма решает переменить тему, надеясь что Леха не заметит:

— Слушай, кстати. Саня иногда будто слепнет. Прошу поправить что-то, а он рядом и делает вид, что не видит соседний кусок кода — будто его вообще нет. То тупит, то ленится, не пойму. Это вообще что?

К его удивлению Лёха с удовольствием цепляется за вопрос — он его явно ждал.

— О, вот это хороший момент. Саня не тупит и не ленится. Это ты пока не понимаешь, что он на самом деле видит. Давай объясню я тебе на конкретном примере: на твоём большом портале, — на маленьком оно бы и не вылезло. Пошли.

2. Окно внимания — файл с историей

Лёха открывает агента прямо в папке портала.

— Смотри. Ты думаешь, ИИ-агент «знает твой репозиторий». Открыл проект — держит всё в голове. Так?

— Ну… да. Он же тут, в папке.

— А вот и нет. И это самое важное, что ты сегодня поймёшь. Давай без прелюдии, по-простому. Знаешь, как агент вообще устроен внутри? Вся ваша с ним работа — это один длинный текстовый файл. Обычный. В нём подряд, сверху вниз, лежит история: твоё сообщение, ответ агента, твоё следующее, его ответ, что он прочитал, что сделал. Лента переписки. Каждый раз, когда ты жмёшь Enter, ИИ-агент отправляет файл с вашей перепиской на ИИ-сервер, где ИИ перечитывает весь этот файл целиком, с самого верха — и дописывает в конец следующее сообщение. И так по кругу.

Тёма моргает.

— Погоди. То есть он каждый раз всё заново вычитывает? Всю нашу болтовню?

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

— А что вообще в этот файл попадает? — Тёма подаётся ближе к монитору.

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

Он даёт Тёме секунду переварить и добавляет:

— А теперь про «слепого Саню». Когда он «не увидел соседний кусок кода» — это не каприз. Просто того файла не было в ленте сообщений. Ты его явно не давал, сам агент его не открывал — значит, в истории его содержимого нет, а значит для агента он не существует. Нельзя учесть то, чего перед тобой нет. Раньше ты думал «ИИ знает мой репозиторий». А правда такая: «он знает только то, что сейчас лежит в файле-истории». Две разные вселенные.

Тёма медленно кивает. Что-то щёлкает.

— То есть он не тупил. Я ему файл не дал, а он сам прочитать его не догадался?

— Давай я тебе проведу маленький ликбез про содержимое этого файла с вашей перепиской. Его ещё называют контекстом.

3. Заглянуть в файл: команда /context

Леха продолжает: — Во-первых, ты всегда можешь посмотреть что уже есть в этом файле. А во-вторых, этим файлом можно управлять.

— Меньше слов, больше дела, — Тёма недоверчив. — Покажи, что у нас там в этом файле прямо сейчас.

— Легко. Есть команда. — Лёха печатает прямо в сессии:

/context

— Она рисует, чем забита лента: сколько места занято и на что. Смотри.

На экране разворачивается раскладка:

❯ /context
  ⎿  Context Usage
     ⛁ ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   claude-opus (1M токенов)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   55.6k/1M токенов (6%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   По категориям:
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Системные инструкции: 3.9k
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Правила проекта: 6.7k
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Прочитанные файлы: 9.9k
                                           ⛁ История сообщений: 22k
                                           ⛶ Свободно: 944k

  Прочитанные файлы (в окне):
     pages/campaign/index.html
     assets/js/shell.js
     src/leaderboard.js

— Вот твой файл-история как на ладони, — говорит Лёха. — Каждый квадратик — кусочек места. Закрашенные ⛁ — занято, пустые ⛶ — свободно. Сверху видно: занято 55 тысяч из миллиона, шесть процентов. А ниже — на что ушло: системные инструкции, правила проекта, прочитанные файлы, история вашего разговора. А в самом низу — поимённо, какие файлы портала он успел прочитать и сейчас держит в окне. Всё, что агент реально видит, — вот тут. Ничего сверх этого у него нет.

Тёма разглядывает квадратики.

— То есть эти проценты — это сколько ленты уже занято?

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

— А теперь, — продолжает Лёха, — ищи тут файл про начисление наград, reward-flow. Есть он в списке прочитанных?

Тёма пробегает глазами — и не находит.

— Нету его.

— То-то и оно. Его в ленте нет. Поэтому если ты сейчас попросишь «поправь начисление очков» — агент будет гадать вслепую, он этот кусок не видит. На маленькой игрушке такое почти не вылезало: там весь проект два файла, он их сразу хватал. А тут проект здоровый, целиком в файл не лезет, и видно как на ладони: половины портала перед агентом просто нет.

4. Положить файл в ленту: значок @

— И что, он так и будет слепой? — Тёма уже понимает, что нет, но спрашивает.

— Нет, конечно. Раз файла в ленте нет — положи его туда сам. Вот так:

Посмотри @src/reward-flow.js и поправь начисление очков.

— Значок @ перед именем файла дописывает этот файл прямо в ленту, — поясняет Лёха. — Был не виден — стал виден. Теперь агент его учтёт, потому что файл лежит у него в истории. И вся «магия» испаряется: ты больше не ждёшь, что агент сам догадается, — ты сам кладёшь ему в файл то, что нужно для задачи.

Тёма пробует сам — подаёт через @ тот самый файл, который только что не находился. Прогоняет правку. И впервые агент не промахивается мимо соседнего куска — потому что этот кусок теперь в ленте. Для верности Тёма ещё раз пишет /context — и видит reward-flow.js в списке прочитанного: попал куда надо.

— О, — Тёма откидывается. — Значит, Саня и не тупил ни разу. Просто я ему глаза не открывал — не показывал, куда смотреть.

— Вот ты и понял главное за сегодня. Не «почему он не догадался», а «а я и не показал». — Лёха доволен. — Хочешь, чтоб агент учёл конкретный файл, — не надейся на телепатию. Подай его через @, попроси прочитать, опиши. Сам собирай перед ним ленту.

5. Сбросить окно: /clear и /rewind

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

/clear

— Это не «удалить всё», — уточняет он, ловя тревогу на лице Тёмы. — Старая история сохранится, к ней всегда можно вернуться. Просто перед агентом теперь чистый лист, пустая лента. Начинаешь разговор заново.

И тут у Тёмы всплывает старое воспоминание.

— Слушай, а помнишь, я /rewind дёргал, когда откаты разбирали? Так и не понял тогда, что именно отматывается.

— А теперь поймёшь, — Лёха почти улыбается. — Отматывалась ровно эта лента. /rewind отрезает у файла-истории хвост — как будто открутил ленту назад, к тому месту, где ещё всё было хорошо. Видишь, ещё один кусок пазла встал на место.

— Слушай, а ведь он меня этим месяц бесил, — говорит Тёма. — А это не баг был. Просто граница такая: видит ленту, не скинул ему файл — значит его нет.

6. Своя карта зон проекта

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

— Очень интересная мысль. А что в неё писать? — цепляется Тёма за неясное.

— Не красота, а зоны. Где витрина, где начисление наград, где лидерборд, где бонусная игра, где партнёрские куски.

— А агенту она зачем? — кидает Тёма. — Я ж ему файлы и так по запросу подкидываю.

— Так она не агенту, — хмыкает Лёха. — Она тебе. Через час сам забудешь, что тут несущее, а что хрупкое и куда лезть опасно.

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

# PROJECT_NOTE — launch-портал (моя карта зон)

ВИТРИНА — pages/ + assets/js/shell.js, assets/css/portal.css
    страницы разделов, общий каркас: шапка, навигация, обёртка страниц.
    НЕСУЩЕЕ: сломаю — падает весь портал. Трогать осторожно.

REWARD-FLOW — src/reward-flow.js (+ data/rewards.json)
    начисление наград и очков. Ядро кампании.
    НЕСУЩЕЕ: на нём висит вся механика призов.

LEADERBOARD — src/leaderboard.js
    таблица лидеров. Читает очки из reward-flow.

BONUS-GAME — src/bonus-game/
    бонусная мини-игра «три в ряд» со своим счётом и тестами. Живёт отдельно от остального.

PARTNER-ЗОНЫ — src/partner/ (acme.js, globex.js)
    куски партнёров. Чужой код, я в нём не разбирался.
    ОПАСНО: вслепую не трогать — там свои правила, легко сломать чужое.

Сборка: npm run build. Тесты: npm test.

Тёма перечитывает свою карту — и до него доходит, что он держит в руках не просто заметку.

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

— Вот теперь ты рассуждаешь как профи, — кивает Лёха.