Документационная архитектура экосистемы¶
Document System — это система внутренней документации, которая помогает команде DET / DETai работать согласованно: понимать устройство экосистемы, принимать решения, фиксировать правила, и быстро вводить новых участников. В общепринятых терминах это можно назвать Documentation Architecture / Operating Documentation: набор слоёв документов, которые покрывают «зачем», «как устроено», «как делать правильно» и «почему мы выбрали именно так».
Это сделано для того, чтобы знания были не “кучей текстов”, а структурированной средой, по которой можно ориентироваться, учиться и действовать как членам команды так и различным AI агентам GPT. Это — context engineering
Типы документов и их атрибуты¶
🇬🇧 Document Types and Their Attributes
Ниже мы описываем каждый тип документа через его слой, его место хранения, его механизм изменения и его доступность - это наши атрибуты архитектурного описания документов.
На данный момент перечень атрибутов каждого типа документов и сам перечень документов являются актуальной в нынешней версии.
Слой¶
Слой определяет, к какому архитектурному уровню системы относится документ. Это про его функцию внутри общей архитектуры экосистемы. Иначе говоря, слой отвечает на вопрос: на каком уровне мышления и управления работает данный документ — уровне смыслов, уровне логики и архитектуры или уровне технических стандартов. Подробнее о каждом слое и типах документов которые к нему относиться смотри в разделах: 1. Philosophy 2. Architecture & Logic 🕸️ 3. Technical Standards ⚙️
Где хранится¶
Этот атрибут указывает на место размещение документа: в каком репозитории, системе или среде он находится (MkDocs, GitHub-репозиторий, ClickUp и т.д.).
Место хранения не случайно — оно не только отражает характер документа, но и интуитивно подсказывает, о чём он и для чего существует. По месту хранения уже можно понять тип знания.
Ведь было бы странно держать в библиотеке знаний инструкцию о том, что run.py запускается с флагом --rec, а не --rom 🤖🤯 — так же как было бы странно описывать мировоззренческую философию всей экосистемы в операционном трекере задач или README 😄 .
Именно поэтому место хранения становится частью архитектуры управления знаниями: место само говорит о статусе, масштабе и назначении документа.
Решение по хранению¶
-
Standards → это “библиотека знаний” → MkDocs (GitHub)
-
Policies → это “политики на уровне всей экосистемы” → MkDocs (GitHub)
-
References → это “операционная конкретика команды” → ClickUp
-
Tutorial / How-to → это маршрут входа → репозиторий Onboarding (issues)
-
Log Summary → это распределённая история исполнения → Folder-local ClickUp List
logs -
Explanation → в MkDocs (GitHub)
(как часть общей базы знаний по экосистеме или по крупному кластеру).
Tip
README → ссылается на Guide
Guide → может ссылаться на Explanation
Explanation → живёт в библиотеке знаний
Процесс версионности ♻️ документов¶
Это способ фиксировать состояние правил, на которых строится вся экосистема. Многие документы задают рамку и структуру, по которым создаются проекты и принимаются решения. Изменяя версию такого документа, мы фактически изменяем действующую норму: формат, логику или принцип работы системы. Поэтому версионность документов — это инструмент управления развитием экосистемы. Во всех документах в метаблоке указывается их тип и версия. Это позволяет однозначно понимать, какая редакция правил действует в данный момент и к какой версии стандарта или политики относится конкретный проект или решение. Подробнее о слоях см. в ♻️ Процесс версионности в 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 | ❌ Нет | ⚠️ Internal |
| Tutorial🎓 | null | Onboarding repo (issues) | v1, v2, v3 … | Public |
| How-to🎒 | null | Onboarding repo (issues) | ❌ Нет | Public |
| Log Summary 🧾 | null | ClickUp Folder/List logs |
одна запись на дату | ⚠️ Internal |
Распределённые Log Summary¶
Каждая проектная Folder хранит собственную дневную историю в List logs. Человек читает изменения прямо в области, с которой работает, а агент может агрегировать распределённые записи по metadata.
Самостоятельный cross-project результат фиксируется отдельно в каждом затронутом контейнере; связанные записи ссылаются друг на друга. Полный contract type: log-summary, classification и provenance определены в реестре metadata schemas.
Слои + Поперечные сущности 🤔¶
🎒 Onboarding (Канал входа / обучения)¶
Onboarding — это коллекция How-to и Tutorials, упакованная как GitHub Issues
Это канал доставки/упаковка документов (~~delivery layer~~), а не смысловой слой.
То есть “onboarding/issues” — это:
- удобный формат выполнения (issue = чекпоинт, прогресс, обсуждение)
- удобная точка входа для новичка
По типологии документов внутри onboarding репо у нас:
-
🎒 How-to (решить задачу)
-
🎓 Tutorial (первый проход/обучение)
Два ClickUp-контейнера Onboarding¶
Каноническая модель назначения, репозитория, владельцев, локального Codex workspace и двух ClickUp-контейнеров описана на странице Onboarding DETai. Эта документационная архитектура фиксирует только маршрут: tutorial / how-to доставляются через onboarding repository и Issues, а участнический и management operational-контуры не подменяют друг друга.
Contract классификации и связей для дневных записей определён в реестре metadata schemas.
Но мы ещё не дошли до того чтобы сделать из этого действительно слой поэтому сейчас он просто если мыслить в категориях слоёв то эти файлы будут обозначаться как null
P.S. Хотите быстро и без лишних сомнений решить, к какому типу документов отнести ту или иную информацию, воспользуйтесь специальным how-to🎒: «Как выбрать тип документа».
Надо определить куда это интегрировать ⁉️¶
| Слой | Что хранится | Формат |
|---|---|---|
| Epic Issue | Оперативная работа версии: этапы, чекбоксы, прогресс | GitHub Issue |
| resource_tracker/ | Завершённые версии и отчёты о приросте ресурсов | Markdown / JSON |
| Resource Tracker — архив и аналитика завершённых версий. | ||
| После закрытия Epic Issue туда попадает отчёт о том, какой ресурс был усилен (технологический, финансовый, командный и т.д.). |
Реализация архитектуры в средах¶
Данный документ описывает общую архитектуру документации экосистемы.
Конкретные среды (например U.L.I.) могут реализовывать эту архитектуру по-своему, определяя:
- где именно хранятся документы
- какие типы документов используются чаще
- как организована работа команды
Описание такой локальной реализации см. в документах соответствующих сред.