ййй

2026-03-27 15:51:10 +03:00
parent 15586f9a8c
commit 0bff171936
1245 changed files with 99621 additions and 543076 deletions
@@ -0,0 +1,14 @@
+# Analysis Assets
+
+Этот каталог содержит служебные артефакты для аналитической и генеративной работы агента.
+
+## Структура
+
+- `rules/` — правила построения документации, frontmatter и шаблоны документов.
+
+## Назначение
+
+Каталог `.analysis/` отделен от `docs/`, чтобы:
+- хранить служебные policy- и template-материалы вне пользовательской документации;
+- передавать правила в LLM как отдельный policy-context;
+- не смешивать документацию проекта и внутренние артефакты анализа.
@@ -0,0 +1,32 @@
+# Documentation Rules
+
+## Назначение
+
+Этот файл фиксирует общие правила формирования, обновления и поддержки технической документации проекта.
+
+Документация проекта должна создаваться как система атомарных, связанных между собой документов, пригодных:
+- для чтения человеком;
+- для сопровождения командой;
+- для индексирования в RAG;
+- для автоматического обновления агентом на основе кода и существующих артефактов.
+
+Этот файл задает:
+- общие принципы документационной архитектуры;
+- правила декомпозиции документации;
+- правила размещения файлов;
+- требования к связям между документами;
+- требования к качеству markdown-документов;
+- правила генерации и обновления документации агентом.
+
+Детальные шаблоны документов и правила frontmatter описываются отдельно:
+- `.analysis/rules/frontmatter-rules.md`
+- `.analysis/rules/templates/*.md`
+
+---
+
+## Область действия
+
+Правила из этого файла применяются ко всей проектной документации, размещаемой в:
+
+```text
+docs/documentation/
@@ -0,0 +1,60 @@
+# Frontmatter Rules
+
+## Назначение
+
+Этот файл фиксирует правила YAML frontmatter для документов в `docs/documentation/`.
+
+Frontmatter обязателен для каждого markdown-документа и нужен для:
+- идентификации документа;
+- определения типа документа;
+- фиксации связей с кодом и другими документами;
+- выделения сущностей, тегов и домена;
+- поддержки индексирования в RAG.
+
+Общие правила построения документации описаны в:
+- `.analysis/rules/documentation-rules.md`
+
+Шаблоны markdown body описаны в:
+- `.analysis/rules/templates/*.md`
+
+---
+
+## Общие правила
+
+1. Frontmatter размещается в начале файла.
+2. Формат — YAML между двумя строками `---`.
+3. Все документы в `docs/documentation/` должны содержать frontmatter.
+4. Поля должны быть стабильными и заполняться единообразно.
+5. Не использовать произвольные поля без необходимости.
+6. Если значение неизвестно и его нельзя уверенно вывести из evidence, поле лучше не заполнять, кроме обязательных полей.
+7. Списковые поля должны оформляться как YAML-массивы.
+8. Идентификаторы и ссылки должны быть стабильными и пригодными для машинной обработки.
+
+---
+
+## Базовый frontmatter
+
+Каждый документ должен начинаться с frontmatter вида:
+
+```yaml
+---
+id: api-orders-create
+title: Метод создания заказа
+doc_type: api_method
+domain: orders
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - ui-order-create-page
+  - logic-order-validation
+related_code:
+  - src/orders/api/create_order.py
+entities:
+  - Order
+  - CreateOrder
+tags:
+  - api
+  - orders
+  - create
+---
@@ -0,0 +1,29 @@
+# Rule: Use Document Templates From Fixed Paths
+
+Агент должен создавать и обновлять техническую документацию только с опорой на шаблоны документов, расположенные в `.analysis/rules`.
+
+Если агент формирует новый документ, он обязан:
+
+- определить тип документа;
+- выбрать соответствующий шаблон по фиксированному пути;
+- сохранить структуру секций и базовых метаданных из шаблона;
+- заполнять только те секции, которые подтверждены кодом и артефактами;
+- не придумывать новые произвольные форматы, если для типа уже существует шаблон.
+
+Пути к базовым шаблонам:
+
+- `.analysis/rules/legacy/template_ui_page.md`
+- `.analysis/rules/legacy/template_api_method.md`
+- `.analysis/rules/legacy/template_logic_block.md`
+
+Правило выбора шаблона:
+
+- для документа типа `ui_page` использовать `.analysis/rules/legacy/template_ui_page.md`
+- для документа типа `api_method` использовать `.analysis/rules/legacy/template_api_method.md`
+- для документа типа `logic_block` использовать `.analysis/rules/legacy/template_logic_block.md`
+
+Если для нужного типа шаблон отсутствует, агент должен:
+
+1. использовать ближайший подходящий существующий шаблон как временную основу;
+2. явно сохранить тип документа в `YAML frontmatter`;
+3. не смешивать в одном документе несколько независимых сущностей.
@@ -0,0 +1,89 @@
+# Template: api_method
+
+```md
+---
+id: api-<stable-id>
+title: <Human-readable title>
+doc_type: api_method
+status: draft
+source_of_truth: code
+domain: <domain-name>
+owner: system-analyst
+endpoint: <METHOD /path>
+auth: <auth-mode-or-unknown>
+idempotent: <true-or-false>
+related_docs:
+  - <doc-id>
+related_code:
+  - <path/to/file>
+entities:
+  - <EntityName>
+tags:
+  - api
+---
+
+# <API Method Title>
+
+## Purpose
+
+Кратко опиши, какую системную задачу решает метод.
+
+## Endpoint Summary
+
+- Endpoint: `<METHOD /path>`
+- Auth: `<auth-mode>`
+- Idempotent: `<true/false>`
+- Triggered by: `<ui/system/integration if known>`
+
+## Technical Use Case
+
+Опиши пошагово обработку запроса:
+
+- вход в endpoint;
+- ключевые проверки;
+- вызовы логики;
+- обращения к БД и внешним системам;
+- формирование ответа.
+
+## Functional Requirements
+
+Вынеси сюда подтвержденные правила, которые дополняют основной сценарий:
+
+- валидации;
+- branching logic;
+- побочные эффекты;
+- ограничения по данным;
+- условия ошибок.
+
+## Request and Response Contract
+
+Опиши контракт в кратком виде или дай ссылку на OpenAPI / контрактный файл.
+
+## Related Logic Blocks
+
+- [<Logic block title>](<path-or-doc-link>)
+
+## Data Access and Integrations
+
+- Reads DB: `<if known>`
+- Writes DB: `<if known>`
+- Integrates with: `<if known>`
+
+## Non-Functional Requirements
+
+Укажи только подтвержденные НФТ:
+
+- timeout;
+- audit;
+- monitoring;
+- security;
+- idempotency rules.
+
+## Related Code
+
+- `<path/to/file>`
+
+## Related Documents
+
+- [<Related document>](<path-or-doc-link>)
+```
@@ -0,0 +1,71 @@
+# Template: logic_block
+
+```md
+---
+id: logic-<stable-id>
+title: <Human-readable title>
+doc_type: logic_block
+status: draft
+source_of_truth: code
+domain: <domain-name>
+owner: system-analyst
+related_docs:
+  - <doc-id>
+related_code:
+  - <path/to/file>
+entities:
+  - <EntityName>
+tags:
+  - logic
+---
+
+# <Logic Block Title>
+
+## Purpose
+
+Кратко опиши, какую переиспользуемую или устойчивую логику реализует блок.
+
+## Where Used
+
+- Called from: `<ui/api/jobs/services if known>`
+- Used by: `<list of known callers>`
+
+## Technical Use Case
+
+Опиши пошагово, как работает логический блок:
+
+- входные данные;
+- ключевые проверки;
+- преобразования;
+- обращения к данным;
+- результат работы.
+
+## Functional Requirements
+
+Вынеси сюда устойчивые правила и ограничения:
+
+- бизнес-правила;
+- проверки;
+- ветвления;
+- ограничения на вход и выход;
+- условия отказа.
+
+## Dependencies
+
+- Uses logic: `<other logic blocks if known>`
+- Reads DB: `<if known>`
+- Writes DB: `<if known>`
+- Integrates with: `<if known>`
+
+## Error Cases
+
+Опиши значимые ошибки и условия их возникновения, если они подтверждены кодом.
+
+## Related Code
+
+- `<path/to/file>`
+
+## Related Documents
+
+- [<Related document>](<path-or-doc-link>)
+```
@@ -0,0 +1,82 @@
+# Template: ui_page
+
+```md
+---
+id: ui-<stable-id>
+title: <Human-readable title>
+doc_type: ui_page
+status: draft
+source_of_truth: code
+domain: <domain-name>
+owner: system-analyst
+related_docs:
+  - <doc-id>
+related_code:
+  - <path/to/file>
+entities:
+  - <EntityName>
+tags:
+  - ui
+---
+
+# <Page Title>
+
+## Purpose
+
+Кратко опиши, какую пользовательскую задачу решает страница.
+
+## Route and Entry Points
+
+- Route: `<route-if-known>`
+- Entry points: `<where user comes from>`
+
+## Technical Use Case
+
+Опиши пошаговый сценарий работы страницы как поток действий и системных реакций.
+
+## UI Structure
+
+Перечисли основные UI-элементы и для каждого укажи:
+
+- назначение;
+- источник данных;
+- значение по умолчанию или placeholder;
+- условия доступности или активации;
+- поведение при взаимодействии;
+- правила валидации.
+
+## Functional Requirements
+
+Вынеси сюда детальные правила, которые не стоит перегружать в use case:
+
+- вызовы API;
+- обработку ответов;
+- локальные правила отображения;
+- условия переходов;
+- feature toggles.
+
+## Related APIs
+
+- [<API document title>](<path-or-doc-link>)
+
+## Related Logic Blocks
+
+- [<Logic block title>](<path-or-doc-link>)
+
+## Non-Functional Requirements
+
+Укажи НФТ, если они подтверждены:
+
+- analytics events;
+- observability;
+- feature toggles;
+- security constraints.
+
+## Related Code
+
+- `<path/to/file>`
+
+## Related Documents
+
+- [<Related document>](<path-or-doc-link>)
+```
@@ -0,0 +1,115 @@
+# {{title}}
+
+## Summary
+- Purpose:
+- Actor:
+- Trigger:
+- Endpoint:
+- Main entities:
+- Main logic:
+- Main errors:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Технический use case
+
+### Основной сценарий
+
+1.
+2.
+3.
+
+### Альтернативные ветки
+
+- 
+- 
+
+## Функциональные требования
+
+### Request validation
+- 
+
+### Processing rules
+- 
+
+### State changes
+- 
+
+### Side effects
+- 
+
+## Contract
+
+### Endpoint
+- Method:
+- Path:
+- Auth:
+- Idempotent:
+- Timeout:
+- Retry:
+
+### Request
+| Field | Type | Required | Constraints | Description |
+|------|------|----------|-------------|-------------|
+|      |      |          |             |             |
+
+### Response
+| Field | Type | Description |
+|------|------|-------------|
+|      |      |             |
+
+### External contract refs
+- OpenAPI:
+- Schema:
+- DTO / serializer:
+- Additional refs:
+
+## Errors
+
+| error_id | http_code | when | client_behavior | retry |
+|----------|-----------|------|-----------------|-------|
+|          |           |      |                 |       |
+
+## Нефункциональные требования
+
+### Security
+- 
+
+### Observability
+- Logs:
+- Metrics:
+- Traces:
+- Audit:
+
+### Reliability
+- 
+- 
+
+### Performance
+- 
+
+## Связанные блоки логики
+- 
+
+## Связанные сущности
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |
@@ -0,0 +1,105 @@
+# {{title}}
+
+## Summary
+- Scope:
+- Purpose:
+- Main modules:
+- Main domains:
+- Main integrations:
+- Key entrypoints:
+- Key data flows:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Границы системы
+
+### In scope
+- 
+
+### Out of scope
+- 
+
+## Архитектурная схема
+
+## Основные модули
+
+| module | responsibility | depends_on | key_code_refs |
+|--------|----------------|------------|---------------|
+|        |                |            |               |
+
+## Основные доменные области
+
+- 
+- 
+
+## Основные интеграции
+
+| integration | direction | purpose | protocol / transport | related_docs |
+|-------------|-----------|---------|----------------------|--------------|
+|             |           |         |                      |              |
+
+## Основные потоки
+
+### Flow 1
+1.
+2.
+3.
+
+### Flow 2
+1.
+2.
+3.
+
+## Архитектурные решения и ограничения
+
+### Key decisions
+- 
+
+### Constraints
+- 
+
+### Risks
+- 
+
+## Нефункциональные аспекты
+
+### Security
+- 
+
+### Reliability
+- 
+
+### Observability
+- Logs:
+- Metrics:
+- Traces:
+- Audit:
+
+### Performance
+- 
+
+### Scalability
+- 
+
+## Связанные сущности
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |
@@ -0,0 +1,92 @@
+# {{title}}
+
+## Summary
+- Domain:
+- Purpose:
+- Entity role:
+- Main attributes:
+- Lifecycle:
+- Invariants:
+- Related APIs:
+- Related logic:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Роль в доменной модели
+
+## Атрибуты
+
+| attribute | type | required | description | constraints |
+|-----------|------|----------|-------------|-------------|
+|           |      |          |             |             |
+
+## Состояния и жизненный цикл
+
+### Основные состояния
+- 
+
+### Переходы состояний
+1.
+2.
+3.
+
+## Инварианты и ограничения
+
+- 
+- 
+
+## Связи с другими сущностями
+
+| entity | relation | description |
+|--------|----------|-------------|
+|        |          |             |
+
+## Использование в системе
+
+### Related API
+- 
+
+### Related UI
+- 
+
+### Related logic
+- 
+
+### Related integrations
+- 
+
+## Функциональные требования
+
+- 
+- 
+
+## Нефункциональные требования
+
+### Audit / history
+- 
+
+### Security
+- 
+
+### Observability
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |
@@ -0,0 +1,93 @@
+```md
+# {{title}}
+
+## Summary
+- Purpose:
+- Trigger:
+- Inputs:
+- Outputs:
+- Main entities:
+- Main dependencies:
+- Side effects:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Технический use case
+
+### Основной сценарий
+
+1.
+2.
+3.
+
+### Альтернативные ветки
+
+- 
+- 
+
+## Функциональные требования
+
+### Preconditions
+- 
+
+### Processing rules
+- 
+
+### Validation rules
+- 
+
+### Output / result rules
+- 
+
+### Side effects
+- 
+
+## Ограничения и условия вызова
+
+- 
+- 
+
+## Нефункциональные требования
+
+### Security
+- 
+
+### Observability
+- Logs:
+- Metrics:
+- Traces:
+- Audit:
+
+### Reliability
+- 
+- 
+
+### Performance
+- 
+
+## Связанные API / UI / integration points
+- 
+
+## Связанные сущности
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |
+```
@@ -0,0 +1,97 @@
+# {{title}}
+
+## Summary
+- Purpose:
+- Actor:
+- Trigger:
+- Route:
+- Main API:
+- Main entities:
+- Main logic:
+- Main states:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Технический use case
+
+### Основной сценарий
+
+1.
+2.
+3.
+
+### Альтернативные ветки
+
+- 
+- 
+
+## Описание UI
+
+## UI Elements
+
+| id | type | label | data_source | default / placeholder | validation | behavior |
+|----|------|-------|-------------|------------------------|------------|----------|
+|    |      |       |             |                        |            |          |
+
+## Функциональные требования
+
+### Input rules
+- 
+
+### State rules
+- 
+
+### Navigation rules
+- 
+
+### Client-side validation
+- 
+
+## Нефункциональные требования
+
+### Security
+- 
+
+### Observability
+- Logs:
+- Metrics:
+- Traces:
+- Analytics:
+
+### Accessibility
+- 
+
+### Performance
+- 
+
+### Feature toggles
+- 
+
+## Связанные API
+- 
+
+## Связанные блоки логики
+- 
+
+## Связанные сущности
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |