| 1 | # Playbook: учить матчасть, а не метаться (v1) |
| 2 | |
| 3 | Общий принцип для агентов: при непонимании домена или API — сначала изучить матчасть, затем действовать. |
| 4 | |
| 5 | ## Триггеры |
| 6 | |
| 7 | - Повторяющиеся ошибки по одной и той же задаче (CHAT_ID_INVALID, CHANNEL_INVALID, 404, неверный формат и т.п.). |
| 8 | - Неясная семантика API или домена. |
| 9 | - Фактическое «угадывание» параметров или форматов вместо опоры на документацию. |
| 10 | |
| 11 | ## Правило |
| 12 | |
| 13 | Если понимаешь, что **не понимаешь** — не продолжать подбор вариантов. |
| 14 | |
| 15 | 1. **Остановиться** и явно зафиксировать: домен/API не изучен. |
| 16 | 2. **Изучить матчасть:** официальная документация (core.telegram.org, MS Learn, спецификации), база знаний (route_context, read_knowledge_file), Context7 или другие MCP по библиотеке. |
| 17 | 3. **Зафиксировать в KB** недостающие факты, если их ещё нет (чтобы следующий агент не повторял разбор). |
| 18 | 4. **После этого** продолжать реализацию. |
| 19 | |
| 20 | ## Цель |
| 21 | |
| 22 | Не тратить циклы на trial-and-error в незнакомом домене. Один проход: **прочитать → зафиксировать → сделать** вместо серии неудачных попыток. |
| 23 | |
| 24 | ## Связь |
| 25 | |
| 26 | Единственная точка правды — этот файл в knowledge. Подтягивать через route_context или read_knowledge_file по запросам вида «застрял», «when stuck», «ошибка API», «не получается», «разобраться с библиотекой», «ретроспектива», «ошибка выжившего». |
| 27 | |
| 28 | ## Ретроспектива при застревании |
| 29 | |
| 30 | Когда задача не продвигается или перед передачей хода/завершением сессии — провести короткую **ретроспективу**. Не только «что сделали / что планируем / хватает ли данных», но и: |
| 31 | |
| 32 | 1. **Что уже пробовали** — перечислить попытки (подходы, инструменты, гипотезы). |
| 33 | 2. **Почему не получилось** — для каждой попытки: причина провала или незавершения (не «мало данных», а что именно: не спросили вовремя, не записали решение, ушли в цикл, передали ход вместо шага и т.п.). |
| 34 | 3. **Что извлекаем** — один-два вывода для следующего шага или для следующего агента (что усилить в процессе, что зафиксировать в KB/agent-notes). |
| 35 | |
| 36 | **Ошибка выжившего:** видим мы только «самолёты, вернувшиеся на базу» — успешные или частично успешные попытки. Усиливать броню нужно **там, где пробоин не было** у вернувшихся: то есть там, где попытки не долетели (агент перестал действовать, пользователь бросил задачу, контекст потерялся). Явно спросить: |
| 37 | - Где агент перестал делать шаги или ушёл в цикл? |
| 38 | - Где пользователь сам доделал или отменил задачу? |
| 39 | - Какие неочевидные причины застревания мы не видим в логе, но можем предположить? |
| 40 | |
| 41 | Зафиксировать выводы в agent-notes или в секции «провалы и выводы», чтобы следующий агент или следующий чат видел не только план, но и анти-паттерны. |
| 42 | |