База знаний о практическом применении AI-агентов: архитектура, паттерны, инструменты, рабочие процессы, кейсы, сравнения и источники. Главная цель структуры — быстро находить нужную заметку и не дублировать одно и то же знание в разных местах.
- Patterns OVERVIEW — оглавление раздела с learning path.
- Таксономия AI-агентов — assistant, workflow, agent, autonomous agent, multi-agent system.
- Agent Harness — из чего состоит рабочая обвязка вокруг агента.
- Skills и правила для агентов — как оформлять переиспользуемые инструкции.
- Оценка ответов LLM — способы оценки final answer, rubrics, LLM-as-judge и human review.
- Работа с код-агентами — цикл постановки задачи, проверки и фиксации результата.
- Исследование фреймворков — выбор OpenAI/Anthropic/LangGraph/AutoGen/CrewAI/LlamaIndex/low-code стека.
| Раздел | Роль |
|---|---|
| patterns | Архитектурные блоки, проектные решения, workflow, recipes, learning path, case-карта, how-to |
| tools | Модели, SDK, платформы, runtime |
| sources | Статьи, переводы, курсы, обработанные источники и provenance |
| meta | Шаблоны и проектные skills |
- Пользовательские папки и Markdown-файлы называем строго на английском в
kebab-case:agent-harness.md,working-with-coding-agents.md. - Для обзорных страниц используем единое имя
OVERVIEW.md. - Служебные dot-файлы и файлы инструментов могут сохранять стандартные имена экосистемы:
.gitignore,.gitlab-ci.yml,.githooks/pre-commit. - Порядок разделов задаётся этой таблицей, а не числовыми префиксами в названиях папок.
Одна мысль должна иметь один основной дом:
- архитектура, паттерн или решение — в
patterns/; - инструмент или модель — в
tools/; - инструкция к действию — в
patterns/; - внешний источник — в
sources/; - overview-файлы только навигируют и кратко объясняют, куда идти.
Каждая сущность в базе знаний имеет единственную canonical страницу, где живут её факты. Все остальные заметки только ссылаются на эту страницу — никогда не дублируют её содержание.
| Сущность | Где canonical страница | Что содержит |
|---|---|---|
| Инструмент, платформа, провайдер, модель | tools/ (или tools/models/, tools/platforms/) |
Факты: возможности, модели, цены, Open Source статус, агентные фичи, use cases |
| Архитектурный паттерн, компонент, решение | patterns/ |
Проблема → Решение → Когда применять → Связанные паттерны |
| Внешний источник (статья, курс, видео) | sources/ (provenance) |
Что это, откуда, автор, дата, relevance, обзор ресурса |
| Практический workflow, рецепт, how-to | patterns/implementation/ или patterns/production-operations/ |
Пошаговый алгоритм, проверка, частые ошибки |
Как это работает на практике:
- Если нужно описать Claude Code — факты о нём пишутся один раз в
tools/platforms/anthropic.mdилиtools/claude-code.md - Если
patterns/implementation/working-with-coding-agents.mdописывает workflow с Claude Code — он ссылается на страницу Claude Code, а не копирует цены/модели - Если
patterns/advanced/agent-antipatterns.mdупоминает ошибки Claude Code — он ссылается на страницу Claude Code - Если меняется цена Claude Code — правка в одном месте
Проверка: найди любую информацию в двух разных заметках. Если она одна и та же — это дубль, который нужно заменить ссылкой на canonical страницу.
Подробный шаблон для инструментов — в sources/OVERVIEW → шаблон.
Если новая заметка повторяет существующую, нужно поставить ссылку на canonical note, а не копировать текст.
- Определить тип материала: концепция, паттерн, инструмент, практика, кейс, сравнение, статья или источник.
- Создать заметку в соответствующем разделе.
- Добавить ссылку в
OVERVIEW.mdэтого раздела. - Если материал пришёл из внешнего источника, добавить карточку в
sources/по шаблону source.md. - Запустить проверку:
python3 meta/scripts/validate-vault.shВ проекте есть три уровня валидации:
- Валидация vault (битые ссылки, frontmatter):
python3 meta/scripts/validate-vault.sh- Canonical cross-reference (bare mentions → wiki-links):
python3 meta/scripts/validate-canonical-refs.py- Регенерация canonical-map.json (из tools/ структуры):
python3 meta/scripts/generate-canonical-map.pyОн проверяет:
- локальные Markdown-ссылки;
- наличие frontmatter у заметок в
sources/; - обязательные поля
title,url,type,category,tags,added,status.
Все три проверки подключены в локальный pre-commit hook .githooks/pre-commit.
Проект использует единый реестр технологий — meta/canonical-map.json. Он генерируется автоматически:
python3 meta/scripts/generate-canonical-map.pyСкрипт сканирует все .md файлы в tools/, извлекает название из frontmatter title: или h1, и создаёт JSON-маппинг {slug: {name, path}}. Map используется:
- validate-canonical-refs.py — проверяет, что все упоминания технологий в
patterns/иtools/оформлены как wiki-ссылки на canonical страницу - pre-commit hook — автоматически регенерирует map и запускает проверку перед каждым коммитом
- Каждый инструмент/платформа имеет одну canonical страницу в
tools/ - Все остальные заметки только ссылаются на canonical страницу, не дублируя факты
- Ссылки оформляются относительным путём от файла к canonical странице (например,
../../tools/platforms/perplexity.md) - Bare mentions (текстовые упоминания без ссылок) недопустимы — их ловит
validate-canonical-refs.py
- Связи между заметками делаем Markdown-ссылками на существующие файлы.
- Списки в обзорных страницах должны быть ссылками, если материал уже создан.
- Не оставляем битые ссылки как “заглушки”.
- После каждого изменения запускаем релевантные проверки, коммитим и пушим результат.