add AI_FLUENCY_PLAN.md

AI_FLUENCY_PLAN.md

@@ -0,0 +1,169 @@
+# Персональный план AI Fluency
+
+**Автор:** Эмиль Амиров  
+**Контекст:** студент КФУ, курс BroJS (KFU-26-1), разработка LangChain/LangGraph-агентов, подготовка к защите проектов  
+**Основа:** [AI Fluency: Framework & Foundations](https://anthropic.skilljar.com/ai-fluency-framework-foundations) (модель 4D: Delegation, Description, Discernment, Diligence)
+
+---
+
+## 1. Цели и контекст
+
+### Зачем мне AI fluency
+- Ускорять учёбу и домашние задания **без потери понимания** кода и архитектуры.
+- Строить надёжных агентов (память, RAG, HITL, MCP), а не «магические» демо.
+- Готовиться к защите: уметь **объяснить** решение, ограничения модели и свою роль в работе.
+
+### Текущий уровень (честная самооценка)
+| Компетенция | Сильные стороны | Зоны роста |
+|-------------|-----------------|------------|
+| **Delegation** | Разделяю задачи: LLM — черновик/объяснение, я — интеграция, тесты, сдача | Иногда делегирую слишком крупные куски («сделай всё ДЗ») |
+| **Description** | Умею задавать структуру (файлы, API, LangGraph), использовать `.env` и контекст репо | Слабее в *performance description* (тон, границы, «остановись и спроси») |
+| **Discernment** | Проверяю код запуском, линтером, MCP/Gitea | Редко фиксирую «галлюцинации» в теоретических ответах |
+| **Diligence** | Не коммичу секреты, знаю про rework в журнале | Нужны явные правила для данных курса и личных проектов |
+
+### Измеримые цели на 8 недель
+1. **Недели 1–2:** для каждого ДЗ — чеклист 4D до начала работы (5 мин).
+2. **Недели 3–4:** один «эталонный» system prompt для учебного агента + шаблон итерации (3 раунда минимум).
+3. **Недели 5–6:** журнал ошибок модели (5 записей: что сказала / что проверил / итог).
+4. **Недели 7–8:** защита: 10-минутный рассказ без слайдов с ИИ — только с демо и своими словами.
+
+---
+
+## 2. Delegation — что кому делегировать
+
+### Режимы взаимодействия (по курсу)
+| Режим | Когда использую | Пример в моей учёбе |
+|-------|-----------------|---------------------|
+| **Automation** | Повторяемые, чётко описанные шаги | Генерация `requirements.txt`, boilerplate README, форматирование |
+| **Augmentation** | Нужно моё суждение + скорость ИИ | Разбор traceback, рефакторинг графа, идеи тест-кейсов |
+| **Agency** | Долгий цикл с guardrails | BroJS-агент с MCP (журнал, Gitea) — только с лимитами и review |
+
+### Матрица «человек / ИИ»
+| Задача | Решение | Почему |
+|--------|---------|--------|
+| Архитектура графа (узлы, interrupt, checkpoint) | **Человек** | Ошибка = неверная модель выполнения |
+| Черновик кода по ТЗ | **ИИ + человек** | ИИ ускоряет, я правлю и запускаю |
+| Сдача в журнал, секреты, `.env` | **Только человек** | Ответственность и безопасность |
+| Поиск по документации LangChain | **ИИ + официальные docs** | ИИ может устареть; сверяю с docs |
+| Этика, цитирование, «чья работа» | **Человек** | Diligence |
+
+### Правило «стоп-делегирования»
+Не отдаю ИИ целиком, если не могу ответить на три вопроса:
+1. Что должно быть на выходе (артефакт)?
+2. Как я проверю результат за < 15 минут?
+3. Что будет, если модель ошибётся?
+
+---
+
+## 3. Description — как описывать задачи ИИ
+
+### Шаблон запроса (Product + Process + Performance)
+
+```
+Контекст: [курс/репо/файл]
+Цель: [одно предложение]
+Продукт: [файлы, формат, критерии готовности]
+Процесс: [шаги: сначала X, потом Y; не трогать Z]
+Поведение: [кратко/подробно; задавать вопросы; не выдумывать API]
+Ограничения: [версии langchain, без pass/TODO, Windows/PowerShell]
+```
+
+### Performance description (как должен вести себя ассистент)
+- «Если требования неясны — задай до 3 уточняющих вопросов, не пиши код.»
+- «Перед финалом перечисли допущения и риски.»
+- «Не предлагай commit/push без явной просьбы.»
+- «Для BroJS: owner Gitea = Emil, ответ в журнал — link или text по типу задания.»
+
+### Контекст-блок (обновляю раз в неделю)
+- Проект: `brojs-agent-main`, Python 3.11+, venv, OpenRouter.
+- Стек ДЗ: LangGraph, MCP journal, Gitea, Qdrant/Ollama где нужно.
+- Слабые места: PowerShell (`;` не `&&`), кодировка UTF-8, лимиты free-моделей (429).
+
+---
+
+## 4. Discernment — как оценивать ответы ИИ
+
+### Цикл Description ↔ Discernment (минимум 3 итерации на нетривиальную задачу)
+1. **Черновик** — получить структуру/код.
+2. **Критика** — «найди 3 бага и 1 лишнюю зависимость».
+3. **Синтез** — внести правки, запустить локально.
+4. **Финал** — сравнить с ТЗ построчно.
+
+### Чеклист проверки вывода
+- [ ] Код запускается в моём окружении?
+- [ ] Все пункты ТЗ закрыты (в т.ч. `langchain>1.0.0`, interrupt, stream)?
+- [ ] Нет выдуманных импортов/API (сверка с docs)?
+- [ ] Нет секретов в репозитории?
+- [ ] Могу объяснить каждый нетривиальный фрагмент на защите?
+
+### Красные флаги
+- Слишком гладкий ответ без trade-offs → **остановка и ручная проверка**.
+- «Уже готово к сдаче» без логов запуска → **не верю до теста**.
+- Один огромный diff → **разбить на шаги**.
+
+### Инструменты верификации
+- `python main.py`, pytest где есть.
+- `scripts/health_check.py` для окружения.
+- Gitea + журнал MCP для сдачи.
+- Для RAG: spot-check источников в Qdrant, не только ответ модели.
+
+---
+
+## 5. Diligence — ответственное использование
+
+### Принципы
+1. **Прозрачность:** на защите говорю, где использовал ИИ (черновик, рефакторинг, документация).
+2. **Конфиденциальность:** API-ключи только в `.env`, не в чатах и не в Gitea.
+3. **Академическая честность:** сдаю **свою** понятую работу; ИИ — инструмент, не соавтор без ревью.
+4. **Ограничение вреда:** не генерирую вредоносный код, не обхожу ограничения платформ курса.
+
+### Действия при ошибке ИИ в продакшене учебного смысла
+- Откатить коммит / не сдавать до исправления.
+- Зафиксировать в комментарии к себе: промпт → ошибка → исправление.
+
+---
+
+## 6. План действий по неделям
+
+| Неделя | Фокус 4D | Действие | Критерий успеха |
+|--------|----------|----------|-----------------|
+| 1 | Delegation | Матрица задач для текущего ДЗ | Заполнена таблица «человек/ИИ» |
+| 2 | Description | Один system prompt в `AGENTS.md` агента | 3 успешных запроса подряд без переделки ТЗ |
+| 3 | Discernment | Журнал 5 проверок выводов | 5 записей с итогом pass/fail |
+| 4 | Diligence | Правила `.env` + pre-submit checklist | 0 утечек ключей, сдача с непустым answer |
+| 5 | Delegation | Режим agency только с HITL | Демо interrupt на защите |
+| 6 | Description | Шаблон prompt в README репо | Коллега может повторить workflow |
+| 7 | Discernment | Mock-защита без слайдов | 10 мин объяснения + вопросы |
+| 8 | Все 4D | Ретроспектива плана | Обновлённая версия плана v2 |
+
+---
+
+## 7. Инструменты и среда
+
+| Инструмент | Роль в плане |
+|------------|--------------|
+| Cursor + агент | Augmentation при разработке |
+| OpenRouter / Claude | LLM с переключением модели при 429 |
+| LangGraph | Agency с checkpoint и interrupt |
+| BroJS Journal MCP | Сдача; всегда `task_update_answer` перед submit |
+| Gitea (Emil) | Хранение кода ДЗ |
+| Anthropic AI Fluency course | Референс терминологии 4D |
+
+---
+
+## 8. Риски и митигация
+
+| Риск | Митигация |
+|------|-----------|
+| Переоценка ИИ на защите | Еженедельная mock-защита без подсказок |
+| Пустая сдача в журнал | Чеклист: answer не пустой (text или link) |
+| Устаревшие API в коде | Сверка с официальной документацией |
+| Выгорание от 429/ретраев | Запасная модель в `OPENROUTER_MODEL` |
+
+---
+
+## 9. Краткое резюме
+
+Мой план AI fluency — **не «больше промптов»**, а дисциплина 4D: осознанно делегировать (automation/augmentation/agency), чётко описывать задачи (product/process/performance), критически проверять вывод (итерации + тесты), ответственно сдавать и защищать работу (diligence). Фокус на курсе BroJS: агенты с памятью, RAG, HITL и MCP — с человеком в контуре принятия решений.
+
+*Версия плана: 1.0 — май 2026*