doc: гайд по AI-моделям (Opus/Sonnet/Fable) + README polygon-docs

polygon-docs/README.md

@@ -0,0 +1,21 @@
+# polygon-docs — документация полигона
+
+Папка для всей документации, не связанной с app-autotest.
+Никакого кода — только планы, промпты, аудиты.
+
+## Ключевые файлы
+
+| Файл | Описание |
+|------|----------|
+| [ai-models-guide.md](ai-models-guide.md) | **Гайд по AI-моделям.** Когда использовать Opus/Sonnet/Fable, как составлять промпты. |
+| [sonnet-polygon-prompt.md](sonnet-polygon-prompt.md) | Промпт Соннету — спроектировать архитектуру полигона |
+| [sonnet-response.md](sonnet-response.md) | Ответ Соннета — архитектура + план реализации |
+| [sonnet-code-review-prompt.md](sonnet-code-review-prompt.md) | Промпт Соннету — code review #1 (v0.2.0) |
+| [sonnet-code-review-2-prompt.md](sonnet-code-review-2-prompt.md) | Промпт Соннету — code review #2 (v0.2.2, после decouple) |
+| [sonnet-integration-prompt.md](sonnet-integration-prompt.md) | Промпт Соннету — интеграция polygon ↔ app-autotest |
+| [opus-architecture-audit-prompt.md](opus-architecture-audit-prompt.md) | Промпт Опусу — архитектурный аудит |
+| [opus-architecture-audit-response.md](opus-architecture-audit-response.md) | Ответ Опуса — 5 находок |
+| [fable5-architecture-audit-response.md](fable5-architecture-audit-response.md) | Ответ Fable 5 — 7 находок |
+| [my-opinion-fable-vs-opus.md](my-opinion-fable-vs-opus.md) | Моё мнение — сравнение Опуса и Fable |
+| [decouple-plan.md](decouple-plan.md) | План развязки монолитного app.py на blueprint'ы |
+| [tf-provider-refs.md](tf-provider-refs.md) | Ссылки на генератор YAML в `~/tf_provider` |

polygon-docs/ai-models-guide.md

@@ -0,0 +1,103 @@
+# Гайд: когда и как использовать Opus, Sonnet, Fable
+
+Дата: 2026-07-31. Основано на опыте проекта polygon (v0.1.0 → v0.3.0).
+
+## Кто для чего
+
+| Модель | Роль | Сильные стороны | Слабые стороны |
+|--------|------|----------------|----------------|
+| **Claude Opus** | Архитектор | Видит систему целиком. Находит структурные проблемы. | Может пропустить баги в коде. |
+| **Claude Sonnet** | Code reviewer | Быстрый. Годится для рутинных ревью. | Поверхностный — 2 ревью пропустили 3 бага которые нашёл Fable. |
+| **Claude Fable 5** | Bug hunter | Видит баги которые все пропустили. Не требует контекста. | Слаб в архитектурных вопросах. Дороже Опуса в 2 раза. |
+
+## Результаты на проекте polygon
+
+| Находка | Опус | Sonnet #1 | Sonnet #2 | Fable 5 |
+|---------|------|-----------|-----------|---------|
+| Workers=1 для in-memory | — | 🔴 | — | — |
+| KeyError в _merge_params | — | 🔴 | — | — |
+| _cfg.DELAY вместо import | — | — | 🔴 | — |
+| Публичный деплой vs single-user | 🔴 | — | — | — |
+| **setdefault не работает** | — | — | — | 🔴 |
+| **sleep блокирует /health** | — | — | — | 🔴 |
+| **int(param_id) без try** | — | — | — | 🟡 |
+| Нет симуляции ошибок | 🟡 | — | — | 🟡 |
+
+**Вывод:** Fable в одиночку нашёл то, что 3 других ревью (Опус + 2×Соннет) пропустили.
+
+## Схема использования
+
+```
+Новый проект / крупный рефакторинг:
+  1. Опус → архитектурный план
+  2. Реализация (я)
+  3. Sonnet → code review (дешёвый, рутинный)
+  4. Исправления
+  5. Fable → bug hunt (дорогой, но вычищает остатки)
+
+Мелкие изменения:
+  1. Реализация
+  2. Sonnet → code review
+```
+
+## Как составлять промпты
+
+### Для Опуса (архитектор)
+
+**Нужно:** полный контекст. Что за проект, какие решения приняты, что уже сделано, куда идём.
+
+```
+- Что такое проект (2-3 абзаца)
+- Текущая архитектура (структура файлов, ключевые решения)
+- Что сделано (хронология)
+- Что проверять (конкретные вопросы)
+- 5-6 вопросов на которые нужен ответ
+```
+
+**Размер:** 100-150 строк. **Цена:** дорого, но оправдано — архитектурные ошибки самые дорогие.
+
+### Для Fable (bug hunter)
+
+**Нужно:** минимум контекста. Он читает код и находит баги сам.
+
+```
+- 2 предложения что это за проект
+- «Вот код, найди баги которые приведут к:
+    • крашу сервера (500, unhandled exception)
+    • потере/порче данных (гонки, KeyError, wrong state)
+    • дырам в безопасности (открытые эндпоинты, инъекции)
+    • блокировкам (sleep, deadlock, busy-wait)»
+- «Ответ — только критические находки, без стиля и код-стайла»
+```
+
+**Размер:** 30-40 строк. **Экономия:** ~4× меньше токенов vs полный промпт.
+
+**Проверено:** даже с полным промптом (тем же что для Опуса) Fable нашёл больше багов. Короткий промпт должен дать тот же результат — он смотрит на код, а не на контекст.
+
+### Для Sonnet (рутинное ревью)
+
+**Нужно:** структура проекта + на что смотреть.
+
+```
+- Структура файлов (таблица)
+- Что изменилось с прошлого ревью
+- Конкретные зоны проверки (безопасность, API, импорты, ...)
+- Формат ответа (🔴🟡🔵)
+```
+
+**Размер:** 80-100 строк. **Цена:** самая низкая из трёх.
+
+## Антипаттерны
+
+- ❌ Давать Fable полный промпт как Опусу — переплата без пользы
+- ❌ Давать Опусу короткий промпт как Fable — пропустит архитектурные проблемы
+- ❌ Пропускать Fable после крупных изменений — баги всплывут в бою
+- ❌ Использовать Sonnet для архитектурных решений — слишком поверхностный
+
+## Итог
+
+| Задача | Кого | Промпт |
+|--------|------|--------|
+| Архитектура | Opus | Полный (150 строк) |
+| Code review | Sonnet | Средний (100 строк) |
+| Bug hunt | Fable | Короткий (40 строк) |