Imported from YuZinyakoff/ai-safety-evals-wiki (AGENTS.md). Install upstream with npx skills add YuZinyakoff/ai-safety-evals-wiki. Copyright stays with the author.

Назначение репозитория

Этот репозиторий — тематическая LLM-поддерживаемая база знаний по курсу AI Safety & Evals.

Главный принцип

raw/ — слой исходников.
wiki/ — слой поддерживаемого знания.
Исходники в raw/ считаются источником истины и не должны переписываться без явной просьбы.
Приоритет агента — улучшать и поддерживать wiki/, а не выдавать одноразовые ответы только в чате.
Если в raw/ еще нет материалов, не нужно создавать пустые страницы источников.

Структура репозитория

Raw layer

raw/week-01..week-05/theory/ — теоретические материалы недели: статьи, блогпосты, тексты
raw/week-01..week-05/notebooks/ — практические ноутбуки недели
raw/week-01..week-05/extra/ — дополнительные материалы недели
raw/shared/ — материалы, не привязанные к конкретной неделе

Материалы с рамкой недели

В raw/week-XX/extra/ допустимо хранить заметки от организаторов курса: вводные рамки недели, карты чтения, предварительные вопросы и вопросы для обсуждения.
Такие файлы лучше держать в простом Markdown-формате с коротким стабильным ASCII-friendly именем, например course-framing-week-01.md.
Это полезный слой педагогического контекста, а не замена предметным источникам недели.
Такие заметки прежде всего должны улучшать wiki/weeks/week-XX.md, а не подменять source pages по theory- и extra-материалам.
Организационные детали без содержательной оптики в raw/ сохранять не нужно.

Правила raw normalization

Цель raw/ — по возможности хранить не только ссылку или бинарный файл, но и локально доступный текст источника.
Предпочтительный порядок такой:
1. качественный web-clipped .md
2. для arXiv: clipped .md из HTML-версии, при сохранении PDF как визуального ground truth
3. оригинальный файл плюс сгенерированный sidecar filename.ext.md как fallback-extract
4. только URL как временное и неполное состояние
Сгенерированные Markdown-sidecar файлы допустимо хранить рядом с оригиналом в raw/.
Оригинальный файл при этом сохраняется и не заменяется sidecar-версией.
Sidecar-файлы вида filename.ext.md, полученные из PDF и других бинарных документов, нужно считать вспомогательным извлеченным текстом, а не автоматически лучшей raw-версией источника.
Для материалов с формулами, таблицами, схемами и сложной версткой sidecar из PDF часто теряет структуру; если есть хороший clipped .md или TeX/HTML-источник, он обычно предпочтительнее для ingest.
Для arXiv-статей HTML-clipped .md обычно является лучшим рабочим текстом для ingest, а TeX Source полезен как high-fidelity backup для формул, таблиц и figure captions.
Если у источника уже есть более качественный локальный текст, чем sidecar из PDF, такой sidecar не нужно создавать, хранить или использовать для ingest только ради формальной полноты.
Для .ipynb не требуется обязательная конвертация в Markdown до ingest.
Если в raw/ лежит только URL или короткая заметка со ссылкой, это нужно считать неполным raw-состоянием и явно отражать в wiki/.
Если для бинарного документа уже существует хороший clipped .md, не нужно создавать дублирующую конвертацию только ради полноты.

Wiki layer

wiki/home.md — главная страница базы знаний
wiki/weeks/week-01..week-05.md — страницы по неделям курса
wiki/sources/ — страницы по отдельным источникам
wiki/concepts/ — страницы по концептам и темам
wiki/syntheses/ — более крупные синтезы, сравнения и сводки
index.md — содержательный каталог страниц wiki с короткими описаниями
log.md — журнал ingest / query / lint и других значимых изменений базы, который ведется только добавлением новых записей

Язык и стиль

Содержимое wiki по умолчанию ведется на русском языке.
Названия файлов и папок должны оставаться короткими, стабильными и ASCII-friendly.
Пиши ясно, компактно и накопительно.
Страницы недель, источников, концептов и синтезов должны оставаться простыми и удобными для постепенного заполнения.
Явно различай:
- факты из источников,
- интерпретации,
- открытые вопросы.

Правила ingest

Когда в raw/ появляются новые материалы:

Сначала оцени raw-состояние источника.
Если у источника еще нет локально доступного текста, по возможности сначала нормализуй raw:
- используй уже существующий clipped .md, если он есть
- для arXiv предпочитай clipped .md из HTML-версии и при необходимости сверяйся с TeX Source
- либо создай рядом Markdown-sidecar для PDF и других поддерживаемых документов как fallback-extract
- URL-only случай пометь как неполный и не притворяйся, что источник локально сохранен полностью
Выбери лучшее доступное локальное представление источника, а не просто любой текстовый файл рядом.
Если exploratory sidecar оказался заметно хуже уже существующего clipped/HTML/TeX raw, не считай его частью preferred raw и при необходимости удаляй, чтобы не засорять raw/.
Прочитай источник.
Если в raw/ есть organizer/course-framing note для недели, используй его как дополнительную рамку для wiki/weeks/week-XX.md, но не как основное доказательство предметных claims.
Создай или обнови страницу в wiki/sources/.
Обнови соответствующую страницу недели в wiki/weeks/, если материал относится к конкретной неделе.
Создай или обнови страницы в wiki/concepts/, если источник вводит или уточняет важные идеи.
Если появляется полезная межисточниковая сводка, создай или обнови страницу в wiki/syntheses/.
Если wiki еще недостаточно хороша для сохранения информации, предложи улучшения структуры.
Обнови index.md.
Добавь краткую запись в log.md.

Если файла в raw/ еще нет, ограничься улучшением обзорных страниц и шаблонов в wiki/.

Правила source pages

Для каждого источника в wiki/sources/ желательно фиксировать:

тип источника: theory / notebook / extra
неделя или shared
путь к raw-исходнику
краткое содержание
в кратком содержании полезно описывать не только главный тезис, но и ход текста: как устроен аргумент, paper или notebook, особенно для длинных источников
если это помогает чтению, полезно явно фиксировать, на какие вопросы источник помогает отвечать
для длинных и сложных источников полезен отдельный блок структура материала: реальные крупные части исходника, чтобы по source page было видно, из каких блоков состоит paper, lecture, note или resource page
секция как читать источник быстро должна по возможности опираться на реальные названия и блоки исходника, а не на общий совет вида “почитайте introduction и conclusion”
если raw-структура у источника бедная или шумная, лучше честно дать грубую карту текста, чем придумывать фальшивые section names
для особенно важных или спорных текстов полезно явно обозначать их эпистемический статус / как на них смотреть: это consensus-like reference, programmatic proposal, critique, survey, benchmark paper или field memo
для текстов, где wiki-level интерпретация особенно важна, полезен явный паттерн:
- Что источник утверждает прямо
- Интерпретация для курса
ключевые идеи
связь с другими страницами wiki
если страница содержит заметную wiki-level интерпретацию сверх пересказа источника, ее полезно явно отделять от фактического слоя хотя бы на уровне формулировок и секций
source page должна помогать не только вспомнить текст, но и быстро зайти в него с вопросом и найти релевантный слой без линейного перечитывания

Правила home / index / log

wiki/home.md должен оставаться входной страницей по сценариям использования, а не полным каталогом всех страниц.
index.md должен оставаться содержательным каталогом wiki: перечислять страницы по категориям и давать короткие one-line summaries.
log.md должен вестись только добавлением новых записей в конец файла, чтобы журнал оставался простым для grep и быстрой проверки недавней истории.

Правила notebooks

Если источник — ноутбук:

выдели цель ноутбука
зафиксируй setup
укажи данные / задачу / модели / scorer, если они есть
кратко опиши результаты и ограничения
свяжи ноутбук со страницей недели и relevant concept pages

Правила query

Когда пользователь задает вопрос:

Сначала опирайся на wiki/.
Если wiki еще недостаточно хороша для ответа, сначала улучши wiki, потом отвечай.
Если ответ получился полезным и переиспользуемым, предложи сохранить его в wiki/syntheses/.

Правила lint

Когда тебя просят проверить базу:

найди orphan pages
найди дубли или почти дубли
найди слабые cross-links
найди часто упоминаемые концепты без отдельной страницы
предложи минимальные полезные улучшения
внеси небольшие, обзорные изменения без тяжелой реорганизации

Дисциплина изменений

Не меняй структуру репозитория без явной причины.
Не создавай лишние папки заранее.
Предпочитай маленькие и проверяемые изменения.
Не переписывай большие куски текста без необходимости.
Если существующую страницу можно расширить, не создавай дубликат.
Не создавай пустые source pages, concept pages или syntheses только ради полноты структуры.

ai-safety-evals-wiki

About