doc: гайд по AI-моделям (Opus/Sonnet/Fable) + README polygon-docs
This commit is contained in:
@@ -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` |
|
||||
@@ -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 строк) |
|
||||
Reference in New Issue
Block a user