ййй
This commit is contained in:
@@ -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 |
|
||||
|------|--------|---------|
|
||||
| | | |
|
||||
Reference in New Issue
Block a user