Single source of truth для как писать wiki-страницу. Корневой CLAUDE.md содержит высокоуровневые принципы (зачем wiki, типы страниц, decisions vs concepts). Эта страница — operational spec: какие секции, в каком порядке, что в frontmatter, как footnotes, что запрещено. Используется как checklist для аудита существующих страниц.
Frontmatter
---
type: entity | concept | decision | source
status: draft | active | contested | superseded
updated: YYYY-MM-DD # дата последнего пересмотра (Quartz рендерит в FolderPage)
created: YYYY-MM-DD # опционально; дата первого авторства
description: "..." # 1-3 предложения о чём страница (Quartz рендерит в FolderPage под title)
tags: # опционально; для decision-страниц всегда `decision`
- decision
verified_by: # опционально; см. [[page-readership-model]]
- { who: ildar, when: YYYY-MM-DD }
superseded_by: <wikilink> # обязательно если status: superseded
---Description-правила:
- 1-3 предложения, factual, без воды
- Описывает что на странице, не зачем создали
- Quartz отображает под title в FolderPage — это первое что читатель увидит
- Не дублировать первый абзац body; description — самостоятельная аннотация
Status enum: ровно 4 значения; нюансы (legacy / phase / regional) — в первом абзаце body, не в status:.
Body style — cumulative state, не digest-narrative
Страница описывает где мы сейчас в понимании topic-а. Это не chronology обсуждений, не retelling митинга, не log. Факты-описания + ссылки на decision-страницы для того, что является вопросом.
Анти-pattern (digest-narrative):
Apr 23: Георгий не справился с задачей. Конкретные поломки UX:
- Не понял разницу между «тесты» и «медконтекст»
Apr 22 решение: версия для врачей — приоритет.Признаки: даты как narrative anchors, имена конкретных людей в context observations, «решили на дейлике», sentence-prefix даты.
Good pattern (cumulative state):
Мотивированные, технически продвинутые пользователи не справляются
с разделённым интерфейсом[^digest-2026-04-23-fda] — типичный failure mode:
- Непонимание разницы между «тесты» и «медконтекст»
Версия для врачей — приоритет: бандл карт биомаркеров + источников
+ калькуляторов[^v-n-j-2026-04-22].Признаки: claim-style (что есть / как устроено), без дат-anchor’ов, attribution через footnote-маркер.
Verbatim quotes — только когда язык source-а критичен (precise wording). Иначе synthesize.
Структура секций по типу страницы
Entity (FHIR-resource, vendor, concept-thing с identity)
<intro: 1-3 предложения определения>
## Где живёт в данных / Использование в BloodGPT
## <разделы по аспектам>
## Failure modes (если есть что сказать)
## Открытые вопросы (мелкие TBD bullet'ами)
## Связано
(footnote defs прямо здесь, без heading «Источники»)
Concept (overview процесса, pattern, architectural idea)
<intro: контекст и proposition>
## <разделы по аспектам>
## Открытые вопросы
## Связано
(footnote defs)
Decision (resolved / contested / open architectural choice)
# <Решение одним предложением>
## Status: <active | contested | draft | superseded>
## Контекст
## Рассматривали (см. ниже про bullet-pattern и detail-level)
## Выбрали: <короткое summary решения>
ИЛИ
## Что нужно для разрешения (для status:contested / draft)
## Почему (rationale; опционально слитно с «Выбрали»)
## Следствия
## Открытые вопросы (опционально)
## Связано
(footnote defs)
## Связано — единый bullet-список ссылок
## Связано — generic bullet-список всех связанных wiki-страниц: entities, concepts, decisions — без разделения по подтипам. Пример:
## Связано
- [[fhir-observation]] — основной потребитель Annotation через `note[]`
- [[fhir-composition]] — `author` как Reference на верхнем уровне ресурса
- [[../technical/phi-in-fhir-not-sql]] — где PHI живёт — **active**
- [[../technical/clinical-record-reconciliation]] — dedup vs reconciliation — **draft**Decision-pages смешиваются с обычными entities в общем списке. Status decision’а можно отметить в комментарии (— **active** / — **draft** / — **contested**), если важно подчеркнуть. Без отдельного ## Связанные решения heading — это создаёт лишнюю иерархию.
Carry-over: на ~26 существующих страницах есть ## Связанные решения отдельной секцией — при sweep’е merge в ## Связано.
## Рассматривали — варианты как ### (X) sub-headings с За / Против
Каждый вариант — ### (A) <Имя> sub-heading + описание одной строкой + два labeled bullet-листа: За: и Против:.
## Рассматривали
### (A) Всё PHI в FHIR
Единое хранилище медицинских данных в FHIR-формате.
**За:**
- HIPAA проще: один периметр audit
- `Patient/$everything` — готовый export
- FHIR-стандарт, совместимость с downstream-tooling
**Против:**
- Latency 50–200ms vs SQL 2–5ms (10–100×)
- Нет SQL analytics
- Сложность маппинга нашей модели в FHIR-ресурсы
### (B) SQL + RLS
Postgres с row-level security как primary store, FHIR опционально для export.
**За:**
- Быстро (2–5ms reads)
- Минимум изменений в коде
- RLS даёт изоляцию tenants на DB-уровне
**Против:**
- PHI остаётся в двух местах (два периметра HIPAA audit)
- Нужна синхронизация удалений между SQL и FHIR
### (C) Гибрид: FHIR primary, SQL cache
FHIR как source of truth + SQL layer для быстрых reads.
**За:**
- Best-of-both в теории
**Против:**
- Удвоенная сложность (dual writes, cache invalidation, race conditions)
- Кэш-как-оптимизация откладывается до того как basic архитектура устоится
Initial Claude-рекомендация — **B**. Ильдар отверг и выбрал **A**.Правила:
- Каждый вариант —
### (X) Имяsub-heading. Letter prefix(A) / (B) / (C)всегда, даже если опций две. Облегчает cross-ref в## Выбрали/## Почему/ reversal note без отдельной случая «когда вписывать буквы». - Под heading — одна строка описания (опционально, если имя самодостаточно — пропустить).
- Два bullet-списка с bold-метками За: и Против:. Один аспект на bullet.
- Один список можно опустить если у варианта только плюсы или только минусы — нет принуждения к симметрии.
- Mid-session reversal — отдельный
### (D) <пересмотренный вариант>(раньше### (C)был initial Claude-предложением) или явная нота-строка под всем списком:Initial Claude-рекомендация — **B**. Ильдар отверг и выбрал **A**. - Реальные примеры в wiki:
phi-in-fhir-not-sql(3 варианта с trade-offs),fhir-meta-tagging(5 вариантов с substantive rationale),zero-extensions-fhir(4 варианта включая reversal).
Carry-over: существующие decision-pages используют compact bullet-pattern
- **<Имя>** — описание. <rationale>.без явных За/Против. При sweep’е мигрировать в новый pattern с### (X)+ За/Против.
Wikilinks — встроены в прозу
Anti-pattern:
Решение принято. (см. [[some-page]])
Калькуляторы запускаются через recognition pipeline (см. [[recognition]]).Good pattern: alias-form [[page|видимый текст]] внутри предложения:
Решение принято [[some-page|на дизайн-сессии]].
Калькуляторы запускаются поверх общего [[recognition|recognition pipeline]].Для секции ## Связано — bullet-список ссылок без alias OK (это и есть «список ссылок»).
Heading anchors — slug-safe
Wikilink с anchor ([[page#heading|Heading]]) — Quartz использует github-slugger; backticks / em-dash / специальные знаки в heading создают непредсказуемый slug. Правило: anchored headings — без backticks и спец-знаков.
❌ ## Choice types — `[x]`-суффикс # slug непредсказуем
✓ ## Choice types ([x] суффикс) # slug = choice-types-x-суффикс
Footnotes
Slug naming
Anti-pattern (auto-generated, нечитаемый):
[^github-com-2026-04-27t08-3a00-3a00-000z-d]
Good pattern (readable, type-prefix + date):
[^daily-2026-04-27] # daily standup
[^digest-2026-04-23-fda] # specific topic in digest
[^session-871a7608] # Claude session (sid8)
[^hl7-r4-bundle] # spec reference
[^evans-2003] # paper / book
[^arthur-2026-05-12] # 1:1 call
Definition format
[^slug]: <Title>, <YYYY-MM-DD>, <URL> — <comment>.
- Title — название созвона / digest / документа / спеки
- Date — event-дата для созвонов/сессий/коммитов/papers;
accessed YYYY-MM-DDдля living docs (HL7-spec / regulations / vendor docs) - URL — public GitHub URL для digest’ов, permalink для Slack/Telegram, vendor URL для docs
- Comment — одна строка о чём; для digest’ов можно сохранять digest-внутреннюю [Р]/[Н]/[О] таксономию как описание content
Claude sessions
[^session-871a7608]: Сессия `ildar/871a7608`, 2026-02-13 — обсуждение choice type для `Annotation.author[x]`.
- Owner handle (
ildar/arthur/nikita) обязателен - sid8 — первые 8 символов session UUID
- Дата сессии — найти через
grep <sid> ~/.claude/projects/для earliest timestamp - Без chain root — chain — personal mechanism, не team-shared
ГОСТ-маркер «Цит. по сессии»
Для источников, найденных через WebSearch / WebFetch и не прочитанных автором лично:
[^loinc-v282]: Regenstrief Institute, «LOINC v2.82», 2026-02-24, https://www.regenstrief.org/article/loinc-version-2-82-concept-release/ — release notes. Цит. по сессии `ildar/29362bdd`.
Маркер временный: когда автор сам прочитает оригинальный источник, маркер убирается (footnote становится unmarked = «прочитан» default). Это позволяет постепенно «промывать» wiki от WebSearch-derived claims, поднимая epistemic confidence по мере того как автор лично верифицирует.
Placement в body
- Inline marker
[^slug]в body — там где факт цитируется (закрашен superscript-цифрой в render’е) - Footnote def
[^slug]: ...— в конце файла, без обёртывающего heading - НЕ писать
## Источникиheading — Quartz сам генерирует «Сноски»-блок - НЕ писать activator-line
Источники: [^s1] [^s2]...— это hack, который был нужен раньше; правильно — inline markers в body
Два инварианта
- Дата обязательна (event-date или
accessed YYYY-MM-DD) - Где смотреть — публичный URL для внешних; intra-team референс для Claude-сессий
Запрещённые pattern’ы
- Факт без цитаты из источника
- Footnote без даты
- Footnote на WebSearch-found источник без маркера
Цит. по сессии - Inline-URL’ы в body вместо footnotes
- Inline
[Р]/[О]/[С]/[Н]/[Э]маркеры в body на entity/concept страницах (digest-style) ## Источникиheading в конце страницы- Activator-line
Источники: [^s1] [^s2]... accessed YYYY-MM-DDдля event-based источников (digests/sessions)- Auto-generated ugly slugs (
github-com-...-3a00-3a00) - Wikilink в скобках
(см. [[X]])вместо alias-формы - Backticks / em-dash в heading, на которое ссылается wikilink-anchor
## Источникиили эмодзи (✅/✓/❌) — визуальный шум- Пересказывать source целиком — ссылка лучше
- Длинные verbatim quotes — synthesize если язык source не критичен
- Daily-narrative «Apr 23: X сделал Y» — это digest-style, не cumulative state
- Чрезмерные ссылки на marketing terms в technical body (например
[[fhir-gravity]]где имеется в виду recognition pipeline)
Audit checklist для существующей страницы
Пройти по странице сверху вниз и проверить:
Frontmatter:
-
type:соответствует контенту (entity / concept / decision / source) -
status:один из 4 значений -
updated:иcreated:в ISO формате -
description:1-3 предложения, factual, не вода - Если
type: decision— естьtags: [decision] - Если
status: superseded— естьsuperseded_by:
Body:
- Cumulative state, не digest-narrative (никаких «Apr 23: X сделал Y»)
- Нет inline
[Р]/[О]/[С]/[Н]/[Э]markers в собственном теле - Verbatim quotes только если язык critical, иначе synthesize
- Нет эмодзи / ✓ / ❌
Wikilinks:
- Встроены в прозу через alias-форму, не «(см. X)»
- Heading-anchors на slug-safe headings (без backticks / em-dash)
- В body — нет ссылок на маркетинговые термины там, где имеется в виду технический artefact
Sections:
- Порядок соответствует type-spec’у
- Нет
## Источникиheading - Если есть
## Связанные решения— реальные decision-pages со status
Footnotes:
- Inline markers
[^slug]в body у каждого claim’а - Footnote defs в конце файла, без обёртывающего heading
- Нет activator-line «Источники: [^s1]…»
- Slugs readable (
daily-2026-04-22,session-871a7608), не auto-generated - Формат:
<Title>, <date>, <URL> — <comment>. -
accessed YYYY-MM-DDтолько для living docs; для event-based — event-date - WebSearch-found источники имеют
Цит. по сессии <owner>/<sid8> - Claude-session footnotes — формат
Сессия <owner>/<sid8>, <date> — <topic>.
Связано
- CLAUDE — корневые принципы wiki
- page-readership-model —
verified_byдля review-tracking - structured-llm-service-page-template — специализированный template для structured-output LLM service pages
- wiki-io-contract-format — I/O contract sub-format
Источники
(внутренний документ; основано на конвенциях, выработанных в обсуждениях с Ильдаром в течение мая 2026 + carry-over из CLAUDE.md)