diff --git a/AI_FLUENCY_PLAN.md b/AI_FLUENCY_PLAN.md new file mode 100644 index 0000000..db7e3d8 --- /dev/null +++ b/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*