Skip to content

schema.md

Latest commit

 

History

History
250 lines (178 loc) · 17.9 KB

schema.md

File metadata and controls

250 lines (178 loc) · 17.9 KB
Raw
type schema
applies_to Wiki at wiki/
maintained_by Dzmitry Varabei (координатор)
last_updated 2026-04-21
version 1.0

Schema — правила Wiki

Операционные правила, как агенты и координаторы пишут страницы в wiki/. Тон прямой и технический. Голос Tandi здесь не звучит — он живёт в эссе, а не в правилах. Конституция отвечает на вопрос «кто такая Tandi», этот документ — на вопрос «как устроена Wiki». Паттерн взят из заметки Карпати (см. vision.md, раздел 5): три слоя — raw sources (неизменные), Wiki (LLM создаёт и поддерживает), Schema (правила). Этот файл — третий слой.

1. Назначение Wiki

Wiki — единственный источник правды о фактах RS School: людях, курсах, инфраструктуре, решениях, концептах, инцидентах. Зафиксированный факт цитируется в эссе, ответах на issues, онбординге и ответах тьютора.

Чем Wiki не является:

  • Не маркетинговый сайт. Внешние материалы (лендинги, презентации, публичные выпуски Tandi) живут в public/, docs/editorial/ и релизных артефактах.
  • Не лента новостей. Хроника событий — в log.md и в выпусках Tandi. Wiki держит текущее состояние, не историю.
  • Не папка черновиков. Незавершённые мысли и идеи — в docs/ideas/, docs/editorial/ или личных заметках. В Wiki попадает только то, что готово быть цитируемым фактом.
  • Не голос Tandi. Wiki описывает факты нейтрально. Голос Tandi (раздел 3 Конституции) — в эссе, не здесь.

Простая проверка перед созданием страницы: «будет ли агент или человек цитировать это как факт о школе?» Если нет — место не здесь.

2. Структура файлов

Wiki живёт в wiki/. Шесть категорий. Имена файлов — kebab-case, расширение .md.

wiki/
  index.md               # каталог всех страниц
  log.md                 # append-only журнал действий
  people/                # люди: координаторы, менторы, команды
  courses/               # курсы: rs-tandem, angular, ai-systems
  infrastructure/        # пайплайны, репозитории, деплой, интеграции
  decisions/             # решения: что выбрали и почему (аналог DECISIONS.md)
  concepts/              # концепты школы: чекпоинт, дневник, ladder, defence
  incidents/             # инциденты и war stories

Шесть категорий — закрытый список. Новые добавляются только через PR в этот документ. Если страница не укладывается ни в одну — скорее всего, это не факт о школе. Подпапки внутри категории допустимы при разрастании (people/coordinators/, people/teams/); решение — у Воробья или координатора на lint-pass'е.

3. Типы страниц

Каждая страница — один из четырёх типов. Тип указывается в frontmatter.

  • entity — одна сущность: человек, команда, курс, репозиторий, сервис. Пример: people/dzmitry-varabei.md, courses/angular.md.
  • concept — понятие или паттерн школы. Пример: concepts/checkpoint.md, concepts/diary-entry.md.
  • source-summary — пересказ raw-источника (CLAUDE.md, session-protocol, war story, выпуск Tandi). Сжимает источник до фактов, ссылается на оригинал. Оригинал неизменен. Пример: concepts/tandi-voice.md → docs/editorial/tandi-voice-b.md.
  • index — индексный или журнальный файл. Только index.md и log.md.

Одна страница — один тип. Смешанный материал дробится на несколько страниц с перекрёстными ссылками.

4. Frontmatter

Каждая страница начинается с YAML-блока. Обязательные поля:

---
type: entity | concept | source-summary | index
title: <человекочитаемый заголовок>
status: active | archived | draft
last_updated: YYYY-MM-DD
sources:
  - <путь к raw-источнику>
  - <или внешний URL>
related:
  - <путь к другой wiki-странице>
  - <или пусто, если связей пока нет>
---

Правила:

  • type — один из четырёх перечисленных, без значения по умолчанию.
  • title — на языке страницы (русский для большинства, английский для Angular-специфики).
  • status — active по умолчанию. draft — в процессе (допустимо, не цитируется). archived — факт устарел, удалять нельзя; агенты игнорируют, ссылки живы.
  • last_updated — дата последней значимой правки. Опечатка не сдвигает; правка факта — обязательно.
  • sources — пути к первоисточникам. Для source-summary обязательны; для entity и concept желательны.
  • related — пути к связанным wiki-страницам (от wiki/). Пустой список допустим только для свежесозданных страниц; lint пометит их как кандидатов в orphan.

Стиль frontmatter совпадает с constitution.md (см. блок в начале того файла).

5. Формат index.md

index.md — каталог всех страниц Wiki, сгруппированный по шести категориям из раздела 2. Формат:

# Wiki Index

## people/
- `people/dzmitry-varabei.md` — координатор RS School [active]

## courses/
- `courses/rs-tandem.md` — флагманский курс, 37 команд [active]
- `courses/angular.md` — первый курс федерации после флагмана, старт 04-27 [active]

## infrastructure/
- `infrastructure/pipeline-overview.md` — 6-шаговый пайплайн Tandi [active]

## decisions/
- `decisions/clone-main-only.md` — клонируем только main-ветку, почему [active]

## concepts/
- `concepts/checkpoint.md` — формула чекпоинта [active]
- `concepts/tandi-voice.md` — пересказ voice guide для агентов [active]

## incidents/
- `incidents/007-voice-we-keep-forgetting.md` — как pipeline-голос вытеснял Tandi [active]

Правила:

  • Одна строка на страницу: `путь` + тире + одно предложение саммари + [status].
  • Саммари — факт, а не приглашение: «координатор RS School», не «страница о координаторе».
  • Категории в порядке раздела 2. Внутри категории — алфавит по пути.
  • Пустая категория сохраняет заголовок с пометкой _(пока пусто)_.

Создание, переименование или архивирование синхронно правит index.md. Страница без записи — orphan (раздел 9).

6. Формат log.md

log.md — append-only журнал. Старые записи не правятся; ошибочная запись закрывается новой. Формат записи:

## [YYYY-MM-DD] <action> | <subject> | <by>
<одно-три предложения контекста, опционально>

Допустимые action:

  • ingest — добавлен новый источник, созданы/обновлены страницы.
  • update — существующая страница обновлена значимо (не опечатка).
  • amendment — правка constitution.md или schema.md.
  • lint — проведён lint-pass; краткий итог в теле записи.
  • orphan-found — lint нашёл страницу без ссылки из index.md.
  • contradiction-found — lint нашёл факт, противоречащий другой странице.

subject — путь, заголовок или номер инцидента. by — имя, github-handle или идентификатор агента (tandi-scout, claude-agent-<short-hash>). Пример:

## [2026-04-21] ingest | constitution v1.0 | Dzmitry Varabei
Создана Конституция Tandi. Добавлена `concepts/tandi-voice.md`, обновлён `index.md`.

## [2026-05-15] lint | первый монтли-проход | Dzmitry Varabei
Найдено 2 orphan, 1 противоречие по формуле checkpoint. Подробности — в записях ниже.

Сортировка — хронологическая, новые записи в конец файла.

7. Ingest workflow

Новый источник (документ, war story, решение, обновлённый CLAUDE.md) попадает в Wiki по одному и тому же порядку — для агента и для координатора:

  1. Прочитать источник целиком. Без выборочного чтения. Источник остаётся неизменным.
  2. Написать или обновить source-summary-страницу в нужной категории. Саммари — факты, не пересказ стиля. Ссылка на оригинал — в sources.
  3. Обновить связанные entity и concept страницы. Если источник упоминает человека, курс, чекпоинт, решение — каждая такая страница правится, если факты изменились. Типичный ingest задевает 5–15 страниц.
  4. Обновить index.md. Новые страницы — в категорию, изменённые саммари — поправить строку.
  5. Дописать запись в log.md. Одна запись на ingest, с перечислением затронутых страниц.
  6. Проверить related-связи. Новая страница ссылается хотя бы на одну существующую, и хотя бы одна существующая — на неё.

При неуверенности, является ли факт новым или противоречащим старому, ingest останавливается, в log.md идёт запись с action contradiction-found; разбирает Воробей или координатор на следующем lint-pass'е.

8. Query workflow

Когда агент или координатор ищет факт для эссе, ответа на issue, онбординга или отчёта:

  1. Сначала — index.md. Это карта Wiki; прямой grep — fallback, не первый шаг.
  2. Перейти по ссылке. Прочитать страницу целиком, включая frontmatter (status, last_updated).
  3. Следовать related-связям. Факт редко живёт на одной странице; 2–3 соседних обычно дают полный контекст.
  4. Синтезировать ответ с цитированием страниц вида (wiki: concepts/checkpoint.md). Студенту ссылку показывать необязательно, во внутренних заметках и отчётах жюри — обязательно.
  5. Вернуть находку в Wiki. Обнаружился факт, которого в Wiki нет? Создать страницу или дополнить существующую. Query, из которого ничего не осело — упущенная возможность.

Страница со status: archived в query-ответах не участвует, кроме случаев, когда вопрос прямо про историю.

9. Lint workflow

Ежемесячный прогон. Первый — 2026-05-15, ответственный — Воробей (см. vision.md, разделы 5 и 9 R4). Дальше ответственность ротируется между координаторами. Проверки:

  • Противоречия. Один факт на двух страницах описан по-разному. В log.md — contradiction-found, разбирается отдельно.
  • Устаревшие страницы. last_updated старше трёх месяцев. Агент проходит по источникам, проверяет актуальность; при подтверждении — обновляет дату без изменения содержания и делает пометку в log.md.
  • Orphan-страницы. Нет в index.md или не упомянуты ни одной другой страницей. Запись orphan-found; решение — подключить или архивировать.
  • Битые ссылки. sources и related, указывающие на несуществующие файлы, — починить или удалить.
  • Нарушения схемы. Отсутствует обязательное поле frontmatter, type не из списка, страница написана в голосе Tandi (раздел 10).

Каждый lint-pass завершается одной записью lint в log.md со сводкой; детали — в подзаписях.

10. Анти-паттерны

Чего в Wiki нельзя:

  • Копировать raw-источник дословно. Wiki — саммари, не зеркало. Дословное копирование разрушает слой «Wiki LLM создаёт и поддерживает» (vision.md, раздел 5). Оригинал — через sources.
  • Создавать страницу без записи в index.md. Страница вне индекса — orphan с рождения.
  • Править без обновления last_updated. Дата — единственный сигнал для lint'а и query-агентов.
  • Писать в голосе Tandi. Wiki — факты, не эссе. «Tandi заметила» здесь не пишется; тянет на литературный оборот — материал для эссе. Голос — в разделе 3 Конституции.
  • Дублировать страницы. Есть concepts/checkpoint.md — обновить её, а не создавать concepts/checkpoint-new.md.
  • Удалять страницы. Удаление ломает ссылки и стирает историю. Корректный путь — status: archived: страница живёт, агенты игнорируют, ссылки целы.

11. Минимальный пример страницы

Скелет страницы типа entity:

---
type: entity
title: Курс Angular
status: active
last_updated: 2026-04-21
sources:
  - vision.md
  - courses/angular/README.md
related:
  - concepts/checkpoint.md
  - infrastructure/pipeline-overview.md
---

# Курс Angular

Первый курс федерации Tandi после флагмана. Старт — 2026-04-27. Первый курс, где Tandi запускается не школой-центром, а внешним координатором со своей LLM-подпиской.

## Ключевые факты
- Язык курса: английский по умолчанию, двуязычный.
- Course Kit: `courses/angular/` в `rs-tandem-dashboard`.
- Критерий успеха пилота: к 2026-05-03 хотя бы один координатор умеет запустить `collect`/`scan` локально (`vision.md`, раздел 6).

## Что дальше
Ссылки на `decisions/` и `incidents/` заполняются по мере появления.

Обязательная часть — frontmatter, заголовок, фактологическая секция, раздел со связями. Остальное — по необходимости.

Схема меняется медленнее Wiki, но чаще Конституции. Поправки — через PR, запись в log.md с action amendment.