Документационная архитектура U.L.I.¶

U.L.I. Document System — это система локальной документации среды разработки, которая помогает участникам DETai работать согласованно: понимать устройство среды, фиксировать локальные правила, поддерживать процессы разработки и быстро вводить новых участников в контекст.

U.L.I. является environment-уровнем внутри кластера DETai.
Это не самостоятельный уровень управления всей экосистемой, а рабочая среда, которая использует общие правила экосистемы и применяет их в локальном контексте разработки.

⚠️ Важно: U.L.I. не определяет собственную типологию документов.

Типы документов, их базовые атрибуты и общая логика документационной системы задаются на уровне всей экосистемы DET / DETai в документе:

Документационная архитектура экосистемы

Допустимые функции документов — index, explanation, standard, policy, guide и другие — определяются в справочнике:

Функции документов

Обязательные metadata-поля документов определяются в документе:

Политика metadata документов

Таким образом, данный документ не вводит новую общую систему типов документов, а показывает, как экосистемная документационная архитектура применяется внутри среды U.L.I.

Роль документации внутри U.L.I.¶

Документация U.L.I. нужна не только для хранения знаний, но и для организации самой среды разработки.

Она помогает:

объяснять устройство среды и её внутреннюю логику
фиксировать локальные стандарты и политики
задавать единые маршруты входа и работы
связывать общие нормы экосистемы с практикой конкретных проектов
делать среду понятной как людям, так и будущим AI-агентам

Внутри U.L.I. документация выступает как операционный интерфейс среды: через неё участники понимают, как устроена работа, а проекты получают согласованную рамку для локального развития.

Архитектурные слои документации U.L.I.¶

Внутри U.L.I. используется зеркальная трёхслойная структура документации.

1. 🐝 Philosophy¶

Этот слой фиксирует локальные принципы, установки и смысловые основания среды.
Здесь формулируется не общая философия всей экосистемы, а именно то, как среда U.L.I. понимает свою роль, формат взаимодействия людей и AI и внутренние рабочие установки.

2. 🕸️ Architecture & Logic¶

Этот слой объясняет, как устроена сама среда U.L.I., как связаны её элементы и по какой логике в ней организованы процессы.

Здесь обычно находятся документы, которые помогают ответить на вопросы:

как устроена среда
как читать систему документов U.L.I.
как связаны между собой стандарты, процессы и роли
почему среда организована именно так

3. ⚙️ Technical Standards¶

Этот слой фиксирует практические правила среды: стандарты, политики, локальные reference-материалы и связанные документы, которые помогают поддерживать единый способ работы внутри U.L.I.

Именно здесь чаще всего оформляются локальные нормы, касающиеся:

документации
процессов разработки
проектного цикла
версионности
naming conventions
release-подходов
технических рабочих правил

Как U.L.I. использует экосистемную типологию документов¶

На уровне экосистемы определено, какие типы документов существуют вообще.
На уровне U.L.I. определяется, как эти типы применяются внутри среды, где они обычно хранятся и какую локальную функцию выполняют.

Ниже приведена прикладная таблица использования типов документов внутри U.L.I.

Типы документов в U.L.I. и их локальное применение¶

Тип документа	Как используется в U.L.I.	Типичный scope	Где обычно хранится	Примечание
Philosophy	Описывает смысловые основания среды U.L.I., формат взаимодействия людей и AI, общие установки среды	environment	MkDocs / knowledge base	Используется для среды в целом, а не для отдельного проекта
Principles	Фиксирует принципы работы среды, локальные установки и правила включённости в процессы	environment	MkDocs / knowledge base	Должны быть согласованы с более высокими принципами экосистемы
Guide	Помогает ориентироваться в конкретном проекте, репозитории или участке среды	project	внутри репозитория проекта	Guide ближе к локальному контексту исполнения
Explanation	Объясняет устройство среды, проекта, процесса или архитектурной логики	environment / project	MkDocs или репозиторий проекта	Environment-объяснения описывают сам U.L.I.; project-объяснения — конкретный проект
Standard	Задаёт правило или норму работы внутри среды либо проекта	environment / project	MkDocs / knowledge base; иногда репозиторий проекта	Локальные стандарты проекта допустимы, если не противоречат более высокому уровню
Policy	Фиксирует обязательное правило для конкретной среды или проекта	environment / project	для среды — knowledge base / MkDocs; для проекта — внутри репозитория проекта	Политики среды подчиняются экосистемным политикам, проектные — средовым и экосистемным
Reference	Содержит операционную конкретику: команды, параметры, shortcuts, рабочие списки	project	ClickUp / локальные заметки команды	Обычно не имеет высокой нормативной силы
ADR	Фиксирует архитектурные и технические решения конкретного проекта	project	внутри репозитория проекта	ADR относится к проектному уровню, а не к общей среде

Как читать эту таблицу правильно¶

Эта таблица не заменяет документ
Документационная архитектура экосистемы.

Она показывает не общую теорию типов документов, а их локальное применение внутри U.L.I.

То есть:

экосистема определяет, что такое Standard, Policy, Explanation и т.д.
U.L.I. показывает, где и как эти типы обычно используются внутри среды
конкретный проект внутри U.L.I. может иметь свои документы, если они не противоречат более высокому уровню норм

Уровни действия документов внутри U.L.I.¶

Поскольку U.L.I. является средой внутри кластера DETai, документы внутри неё могут действовать на разных уровнях.

Environment-level¶

Документ действует на всю среду U.L.I.
Например:

стандарты среды
философия среды
объяснение архитектуры U.L.I.
политики среды разработки

Project-level¶

Документ действует только внутри конкретного проекта или репозитория.
Например:

Guide проекта
ADR проекта
локальный Policy проекта
локальный Standard проекта
Reference-материалы проекта

Это различие особенно важно, потому что внутри одной среды могут существовать несколько проектов, и не все документы обязаны распространяться на всю среду одинаково.

Принцип подчинённости документов¶

Документы U.L.I. не существуют изолированно.
Они входят в иерархию нормативной силы документов всей экосистемы.

Общий принцип такой:

ecosystem → cluster → environment → project

Это означает:

документы экосистемного уровня имеют приоритет над документами U.L.I.
документы среды U.L.I. имеют приоритет над локальными документами отдельных проектов
проектные документы не должны противоречить правилам среды и экосистемы

Если проекту требуется локальный стандарт или политика, такой документ допустим, но он должен:

быть явно ограничен своим уровнем действия
не противоречить более высокому уровню

Версионность документов в U.L.I.¶

Документы среды U.L.I. подчиняются общему процессу версионности, принятому в экосистеме.

См. документ: ♻️ Процесс версионности

Также документы U.L.I. используют общую систему метаданных

См. документ: Политика metadata документов