Документационная архитектура экосистемы¶
Document System — это система внутренней документации, которая помогает команде DET / DETai работать согласованно: понимать устройство экосистемы, принимать решения, фиксировать правила и быстро вводить новых участников. В общепринятых терминах это можно назвать Documentation Architecture / Operating Documentation: набор слоёв документов, которые покрывают «зачем», «как устроено», «как делать правильно» и «почему мы выбрали именно так».
Это сделано для того, чтобы знания были не «кучей текстов», а структурированной средой, по которой могут ориентироваться, учиться и действовать как члены команды, так и AI-агенты. Это — context engineering.
Типы документов и их атрибуты¶
🇬🇧 Document Types and Their Attributes
Ниже мы описываем каждый тип документа через его слой, место хранения, механизм изменения и доступность — это атрибуты архитектурного описания документов.
Слой¶
Слой определяет, к какому архитектурному уровню системы относится документ. Иначе говоря, слой отвечает на вопрос: на каком уровне мышления и управления работает данный документ — уровне смыслов, уровне логики и архитектуры или уровне технических стандартов.
Подробнее о каждом слое и типах документов смотри в разделах:
- Philosophy
- Architecture & Logic 🕸️
- Technical Standards ⚙️
Где хранится¶
Этот атрибут указывает место размещения документа: в каком репозитории, системе или среде он находится — MkDocs, GitHub-репозитории, ClickUp и т. д.
Место хранения не случайно: оно отражает характер знания и подсказывает, кто владеет его изменением. При этом функция документа и место хранения — разные атрибуты. Например, tutorial остаётся tutorial независимо от того, доставляется ли он через Onboarding Issue или хранится рядом с кодом конкретного проекта.
Решение по хранению¶
- Standards → библиотека знаний → MkDocs (GitHub).
- Policies → политики уровня экосистемы → MkDocs (GitHub).
- References → операционная конкретика команды → ClickUp или owning-система, если reference является runtime-конфигурацией.
- Tutorial / How-to общего onboarding-маршрута → репозиторий Onboarding (issues).
- Project-specific Tutorial / How-to → owning repository проекта, когда текст относится к конкретному инструменту и должен версионироваться вместе с его реализацией.
- Embedded runtime tutorial → owning repository проекта; такой документ может быть source of truth для встроенной помощи интерфейса, чтобы текст в Git и UI не расходился.
- Log Summary → распределённая история исполнения → Folder-local ClickUp List
logs. - Explanation → MkDocs (GitHub) как часть базы знаний по экосистеме или крупному кластеру.
Tip
README → ссылается на Guide
Guide → может ссылаться на Explanation
Project Tutorial → может одновременно служить source of truth для встроенной помощи продукта
Explanation → живёт в библиотеке знаний
Процесс версионности ♻️ документов¶
Это способ фиксировать состояние правил, на которых строится вся экосистема. Многие документы задают рамку и структуру, по которым создаются проекты и принимаются решения.
Изменяя версию такого документа, мы фактически изменяем действующую норму: формат, логику или принцип работы системы. Поэтому версионность документов — инструмент управления развитием экосистемы.
Во всех канонических документах в метаблоке указывается их тип и версия. Локальные project-specific tutorial/how-to могут использовать metadata своего owning repository, но должны явно фиксировать функцию документа, владельца и связь с runtime-проекцией, если такая связь существует.
Подробнее о слоях см. в ♻️ Процесс версионности в U.L.I..
Visibility¶
Visibility определяет уровень доступности документа: кто имеет право его видеть и использовать — все люди, только команда или ограниченная роль.
Этот атрибут задаёт границы распространения знания и управляет прозрачностью системы. Он помогает различать публичные принципы, полупубличные регламенты и внутренние рабочие материалы.
☝️ Таблица¶
| Тип документа | Слой | Где хранить | Процесс версионности ♻️ | Visibility |
|---|---|---|---|---|
| Philosophy | Philosophy | MkDocs (GitHub) | Edition (1, 2, 3 …) | Public |
| Principles | Philosophy | MkDocs (GitHub) | Edition (1, 2, 3 …) | Public |
| Explanation | Architecture & Logic 🕸️ | MkDocs (GitHub) | v1, v2, v3 … | Public |
| Standard | Technical Standards ⚙️ | MkDocs (GitHub) | v1, v2, v3 … | Public |
| Policy | Technical Standards ⚙️ | MkDocs (GitHub) | v1, v2, v3 … | Public / Semi-public |
| Reference | Technical Standards ⚙️ | ClickUp / owning system | ❌ / по contract | ⚠️ Internal |
| Tutorial🎓 | null | Onboarding или owning repository проекта | v1, v2, v3 … | Public / Internal |
| How-to🎒 | null | Onboarding или owning repository проекта | по локальному contract | Public / Internal |
| Log Summary 🧾 | null | ClickUp Folder/List logs |
одна запись на дату | ⚠️ Internal |
Project-specific и embedded tutorials¶
Не каждый tutorial является onboarding-документом всей экосистемы. Если документ обучает работе с конкретным проектом или инструментом, его естественный владелец — сам проект.
Project-specific tutorial особенно уместно хранить рядом с кодом, когда выполняется хотя бы одно условие:
- шаги зависят от текущего интерфейса проекта;
- текст должен изменяться в том же PR, что и функция;
- tutorial используется внутри продукта как встроенная справка;
- AI-агенту нужен один source of truth и для реализации, и для пользовательского объяснения.
В таком случае runtime-интерфейс рендерит или проецирует текст tutorial, а не поддерживает независимую копию. Это снижает drift между кодом, документацией и фактическими подсказками пользователю.
Распределённые Log Summary¶
Каждая проектная Folder хранит собственную дневную историю в List logs. Человек читает изменения прямо в области, с которой работает, а агент может агрегировать распределённые записи по metadata.
Самостоятельный cross-project результат фиксируется отдельно в каждом затронутом контейнере; связанные записи ссылаются друг на друга. Полный contract type: log-summary, classification и provenance определены в реестре metadata schemas.
Слои + поперечные сущности¶
🎒 Onboarding — канал входа / обучения¶
Onboarding — это один из каналов доставки Tutorial / How-to, а не эксклюзивное место существования этой функции документа.
Для экосистемного маршрута участия GitHub Issues удобны потому, что дают:
- чекпоинты и прогресс;
- обсуждение;
- последовательное прохождение;
- единую точку входа для нового участника.
По типологии документов внутри onboarding repository чаще всего находятся:
- 🎒 How-to — решить конкретную задачу;
- 🎓 Tutorial — пройти первый целостный маршрут.
Project-specific tutorial может жить в owning repository и при необходимости быть связан с onboarding issue, который лишь маршрутизирует участника к нему.
Два ClickUp-контейнера Onboarding¶
Каноническая модель назначения, репозитория, владельцев, локального Codex workspace и двух ClickUp-контейнеров описана на странице Onboarding DETai. Эта документационная архитектура фиксирует маршрут участия и не подменяет локальную документацию конкретных проектов.
Contract классификации и связей для дневных записей определён в реестре metadata schemas.
Но мы ещё не дошли до того, чтобы сделать из onboarding полноценный смысловой слой, поэтому при классификации слоя эти файлы пока могут обозначаться как null.
P.S. Хотите быстро решить, к какому типу документов отнести информацию, воспользуйтесь специальным how-to🎒: «Как выбрать тип документа».
Надо определить куда это интегрировать ⁉️¶
| Слой | Что хранится | Формат |
|---|---|---|
| Epic Issue | Оперативная работа версии: этапы, чекбоксы, прогресс | GitHub Issue |
| resource_tracker/ | Завершённые версии и отчёты о приросте ресурсов | Markdown / JSON |
Resource Tracker — архив и аналитика завершённых версий. После закрытия Epic Issue туда попадает отчёт о том, какой ресурс был усилен — технологический, финансовый, командный и т. д.
Реализация архитектуры в средах¶
Данный документ описывает общую архитектуру документации экосистемы.
Конкретные среды и проекты могут реализовывать эту архитектуру по-своему, определяя:
- где именно хранить локальные документы;
- какие функции документов используются чаще;
- как организовать работу команды;
- какие project-specific tutorial/how-to должны версионироваться вместе с кодом;
- какая документация является source of truth для runtime-подсказок интерфейса.
Описание такой локальной реализации см. в документах соответствующих сред.