admin/wiki

Files

Stream 143f9ad259 auto-sync: 2026-05-15 00:50:01

2026-05-15 00:50:01 +03:00

22 KiB

Raw Blame History

02. Структура репозитория и naming convention

Назначение: зафиксировать жёсткую структуру файлов и папок в каждом проекте, naming convention, шаблоны артефактов с frontmatter — чтобы агенты могли работать в любом репо одинаково, а человек мог за минуту найти нужный документ.

Простым языком

Все репозитории организованы по одному шаблону, как папки в одинаково сложенном гараже: «розетки — тут, ключи — тут, инструкция к мотоблоку — тут». Если зайти в любой проект и набрать docs/work-items/<номер>/ — там лежит всё, что нужно понять об этой задаче: бизнес-постановка, ТЗ, архитектурные решения, дизайн-макеты, отчёт о тестировании, лог деплоя.

Имена файлов — строгие. Не final_v3_FINAL.md, а 02-trz.md. Не arch (копия).md, а adr-0017-use-redis-for-rate-limit.md. Этот педантизм — не для красоты: на нём держится возможность агентов читать и писать без ошибок.

Канон структуры проекта (репозитория)

Каждый репозиторий — это один проект в Plane. Структура:

<repo-root>/
├── README.md                          # Что это за проект, для людей
├── CLAUDE.md                          # Паспорт проекта для агентов (см. ниже)
├── AGENTS.md                          # Алиас CLAUDE.md (для совместимости)
├── CHANGELOG.md                       # Keep a Changelog format
├── LICENSE
├── .env.example                       # Все env-переменные с пустыми значениями
├── .gitignore
├── .editorconfig
├── Makefile                           # make dev / test / lint / build / deploy-test
├── Dockerfile
├── docker-compose.yml                 # для локальной разработки и preview
├── docker-compose.test.yml            # для CI/preview-окружений
│
├── .github/                           # или .gitea/, .gitlab/ — в зависимости от форджа
│   ├── workflows/                     # CI/CD
│   │   ├── ci.yml                     # на каждый push/PR: lint, test, build
│   │   ├── preview.yml                # ephemeral preview на PR
│   │   ├── deploy-test.yml            # деплой в test на merge в main
│   │   ├── deploy-prom.yml            # деплой в prom на тег
│   │   └── nightly.yml                # ночной регресс на test
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── ISSUE_TEMPLATE/
│
├── .openclaw/                         # Конфиг агентов для этого проекта
│   ├── agents/                        # subagent definitions
│   │   ├── analyst.md
│   │   ├── architect.md
│   │   ├── designer.md
│   │   ├── developer.md
│   │   ├── reviewer.md
│   │   ├── tester.md
│   │   └── deployer.md
│   ├── skills/                        # project-specific skills (опц.)
│   ├── mcp.json                       # описание MCP-серверов проекта
│   └── budget.yaml                    # лимиты токенов на задачу
│
├── docs/
│   ├── README.md                      # навигация по docs/
│   ├── architecture/
│   │   ├── README.md                  # обзор архитектуры
│   │   ├── c4-context.mmd             # C4 уровень 1 — Context
│   │   ├── c4-container.mmd           # C4 уровень 2 — Container
│   │   ├── c4-component.mmd           # C4 уровень 3 — Component
│   │   ├── data-model.mmd             # ER-диаграмма
│   │   └── adr/                       # глобальные ADR проекта (не привязанные к задаче)
│   │       ├── README.md              # индекс ADR
│   │       └── adr-NNNN-<slug>.md
│   ├── design/
│   │   ├── design-tokens.json         # цвета, типографика, spacing
│   │   ├── components.md              # каталог UI-компонентов
│   │   └── style-guide.md
│   ├── work-items/                    # ⭐ артефакты по задачам
│   │   └── <plane-id>/
│   │       ├── 00-business-request.md
│   │       ├── 01-questions.md        # опц.
│   │       ├── 01-brd.md
│   │       ├── 02-trz.md
│   │       ├── 03-acceptance-criteria.md
│   │       ├── 04-test-plan.yaml
│   │       ├── 05-customer-journey.md # опц.
│   │       ├── 06-adr/
│   │       │   └── adr-NNNN-<slug>.md
│   │       ├── 07-infra-requirements.md
│   │       ├── 08-data-requirements.md
│   │       ├── 09-ui-requirements.md  # опц.
│   │       ├── 10-tech-risks.md
│   │       ├── 11-design/             # опц.
│   │       │   ├── wireframes.md
│   │       │   ├── mockups.md
│   │       │   ├── states.md
│   │       │   ├── a11y.md
│   │       │   └── assets/
│   │       ├── 12-review.md
│   │       ├── 13-test-report.md
│   │       ├── 13-test-report/
│   │       │   └── screenshots/
│   │       └── 14-deploy-log.md
│   ├── phases/                        # групповые артефакты на фазу
│   │   └── <phase-id>/
│   │       ├── 00-phase-brd.md
│   │       ├── 01-phase-plan.md
│   │       └── 02-release-notes.md
│   ├── runbook.md                     # как запустить локально / в test / в prom
│   ├── operations/                    # SRE-документация
│   │   ├── monitoring.md
│   │   ├── alerts.md
│   │   ├── incident-response.md
│   │   └── backup-restore.md
│   └── api/
│       ├── openapi.yaml               # спецификация API
│       └── postman.collection.json    # опц.
│
├── src/                               # исходники (структура зависит от стека)
├── tests/
│   ├── unit/
│   ├── integration/
│   ├── e2e/                           # Playwright
│   ├── visual/                        # visual regression baseline
│   ├── fixtures/
│   └── README.md
│
├── migrations/                        # миграции БД (Alembic / Flyway / Prisma)
│
├── scripts/
│   ├── lint-spec.sh                   # spec-linter: проверяет docs/work-items/
│   ├── lint-adr.sh                    # adr-linter
│   ├── check-coverage.sh
│   └── render-mermaid.sh
│
└── infra/                             # IaC
    ├── ansible/                       # плейбуки деплоя
    ├── compose/                       # production docker-compose файлы
    └── terraform/                     # опц.

Naming convention

Папки

Только kebab-case, латиница: work-items, c4-context, customer-journey.
Никаких пробелов, заглавных, кириллицы. Никогда.
Числовой префикс — там, где порядок чтения важен (01-brd.md, 02-trz.md); в остальных случаях — без префикса.

Файлы артефактов задачи

Шаблон: <NN>-<slug>.<ext> — 01-brd.md, 04-test-plan.yaml.
NN — двузначный, с ведущим нулём.
slug — kebab-case, латиница.
Расширение зависит от типа: .md для текстовых, .yaml для машинно-читаемых, .mmd для Mermaid, .json для данных.

ADR

Шаблон: adr-<NNNN>-<slug>.md — adr-0017-use-redis-for-rate-limit.md.
NNNN — четырёхзначный, монотонно возрастает в рамках папки.
Глобальные ADR — в docs/architecture/adr/.
ADR конкретной задачи — в docs/work-items/<id>/06-adr/.
ADR могут ссылаться друг на друга, но не должны дублироваться.

Ветки Git

feature/<plane-id>-<slug> — фича: feature/PROJ-123-add-noise-zones-on-map.
bugfix/<plane-id>-<slug> — баг.
hotfix/<plane-id>-<slug> — срочный фикс на prom.
phase/<phase-id>-<slug> — фаза (если используется фазовая модель).
chore/<slug> — обслуживание (без Plane-задачи).

<plane-id> — точный идентификатор Work Item в Plane (формат PROJ-123).

Коммиты (Conventional Commits)

feat(scope): описание — новая фича
fix(scope): описание — багфикс
docs(scope): описание — изменения только в документации
refactor(scope): описание — рефакторинг без изменения поведения
test(scope): описание — добавление/правка тестов
chore(scope): описание — обслуживание
arch(scope): описание — архитектурные изменения (новый ADR)

Тело коммита обязательно содержит ссылку на Plane: Refs: PROJ-123 или Closes: PROJ-123.

Теги релизов

v<MAJOR>.<MINOR>.<PATCH> (semver) — v1.4.0.
Pre-release: v1.4.0-rc.1, v1.4.0-beta.2.

Шаблоны артефактов

Все Markdown-артефакты содержат frontmatter в YAML — он позволяет агентам и линтерам делать машинную проверку.

Шаблон `00-business-request.md`

---
type: business-request
plane_id: PROJ-123
title: "<заголовок Work Item>"
project: <project-key>
created_by: <user-email>
created_at: 2026-05-04T10:00:00Z
priority: medium
status: draft | submitted | clarification | approved
---

# Business Request — PROJ-123: <title>

## Что хотим
<1–5 предложений, без «как»>

## Зачем (бизнес-ценность)
<метрика или гипотеза успеха>

## Контекст
<что побудило / какая проблема>

Шаблон `01-brd.md` (Business Requirements Document)

---
type: brd
plane_id: PROJ-123
version: 1
status: draft | review | approved | superseded
related:
  business_request: ./00-business-request.md
  trz: ./02-trz.md
authors:
  - "agent:analyst"
  - "human:<email>"
last_updated: 2026-05-04
---

# BRD — PROJ-123

## 1. Цель и метрика успеха
- Цель: <одно предложение>
- Метрика: <измеримый KPI и его целевое значение>

## 2. Стейкхолдеры
| Роль | Имя/команда | Интерес |
|------|-------------|---------|
| Заказчик | … | … |
| Конечный пользователь | … | … |

## 3. Scope
### В скоупе
- …
### Вне скоупа
- …

## 4. Бизнес-правила
- BR-1: …
- BR-2: …

## 5. Допущения и ограничения
- …

## 6. Риски и митигации
| Риск | Влияние | Вероятность | Митигация |
|------|---------|-------------|-----------|

## 7. Готовность (DoD на BRD)
- [ ] Все стейкхолдеры перечислены
- [ ] Метрика успеха измерима
- [ ] Scope/out-of-scope явные

Шаблон `02-trz.md` (Техническое задание)

---
type: trz
plane_id: PROJ-123
version: 1
status: draft | review | approved | superseded
related:
  brd: ./01-brd.md
  acceptance: ./03-acceptance-criteria.md
  test_plan: ./04-test-plan.yaml
ui_affected: true | false
last_updated: 2026-05-04
---

# ТЗ — PROJ-123

## 1. Функциональные требования
- REQ-F-1: <система должна …> [origin: BR-1]
- REQ-F-2: …

## 2. Нефункциональные требования
- REQ-NF-1 (Производительность): … [метрика и порог]
- REQ-NF-2 (Безопасность): …
- REQ-NF-3 (Доступность): …

## 3. Сценарии использования
### UC-1: <название>
- Актор: …
- Предусловие: …
- Шаги: 1) …  2) …
- Постусловие: …
- Альтернативные сценарии: …

## 4. Данные
- Сущности: …
- Изменения схемы: …
- Миграции: …

## 5. API (если применимо)
- эндпоинт, метод, тело, ответ — ссылка на `docs/api/openapi.yaml` секция X

## 6. UI (если ui_affected=true)
- Затрагиваемые экраны: …
- Новые компоненты: …
- См. `09-ui-requirements.md`

## 7. Зависимости
- от других задач: …
- от внешних сервисов: …

## 8. Out of scope
- …

Шаблон `03-acceptance-criteria.md`

---
type: acceptance
plane_id: PROJ-123
related:
  trz: ./02-trz.md
  test_plan: ./04-test-plan.yaml
---

# Acceptance Criteria — PROJ-123

## AC-1: <короткое название> [REQ-F-1]
```gherkin
Feature: <feature name>
  Scenario: <scenario>
    Given <начальное состояние>
    When <действие>
    Then <ожидаемый результат>

AC-2: …


### Шаблон `04-test-plan.yaml` (machine-readable)

```yaml
# JSON-Schema: schemas/test-plan.schema.json
plane_id: PROJ-123
version: 1
test_cases:
  - id: TC-1
    title: "User sees noise zones on map"
    type: e2e          # unit | integration | e2e | visual | a11y | performance | security
    priority: P0       # P0 (блокирующий) | P1 | P2 | P3
    coverage:
      - REQ-F-1
      - AC-1
    steps:
      - "open /map"
      - "click 'Noise zones' toggle"
      - "wait for layer rendered"
    expected:
      - "noise-zones layer visible"
      - "legend shows 5 frequency bands"
    automation:
      tool: playwright
      file: tests/e2e/noise-zones.spec.ts
  - id: TC-2
    type: visual
    target_screen: /map?layer=noise
    baseline: tests/visual/baseline/map-noise.png
    threshold: 0.01    # 1% pixel difference

Шаблон ADR (Michael Nygard, slightly extended)

---
type: adr
plane_id: PROJ-123          # или null для глобальных
adr_id: 0017
status: proposed | accepted | rejected | superseded | deprecated
date: 2026-05-04
authors:
  - "agent:architect"
supersedes: null            # ссылка на adr_id, который заменён
superseded_by: null
---

# ADR-0017: Use Redis for rate-limiting

## Context
<какую задачу/проблему решаем, какие силы действуют>

## Decision
<что решили — одно предложение в активном залоге>

## Alternatives considered
- **A**: <вариант>. Отвергнуто, потому что …
- **B**: …

## Consequences
### Positive
- …
### Negative
- …
### Neutral
- …

## Compliance / How to verify
<как проверить, что ADR действительно соблюдён в коде>

Шаблон `13-test-report.md`

---
type: test-report
plane_id: PROJ-123
pr: <pr-url>
preview_env: <preview-url>
date: 2026-05-04
verdict: pass | fail | conditional
related:
  test_plan: ./04-test-plan.yaml
  acceptance: ./03-acceptance-criteria.md
---

# Test Report — PROJ-123

## Summary
- Test cases total: 24
- Passed: 24 / Failed: 0 / Skipped: 0
- Coverage delta: +1.2%
- Visual regression: 0 unreviewed diffs
- a11y violations: 0 (A/AA)
- Performance: p95 = 230ms (порог 500ms)

## По типам
### Unit/Integration
…

### E2E
…

### Visual regression
…

### Accessibility
…

### Performance
…

## Найденные баги
| Bug | Severity | Plane Issue | Status |
|-----|----------|-------------|--------|

## Скриншоты и логи
…

Шаблон `CLAUDE.md` (паспорт проекта для агентов)

Один файл в корне репо — главное, что читает агент при заходе в проект.

# CLAUDE.md — паспорт проекта <project-name>

## Tл;Dr
<2–3 предложения: что делает проект, для кого, на чём>

## Стек
- Backend: Python 3.12 + FastAPI 0.110
- Frontend: React 18 + TypeScript 5.4 + Vite 5
- БД: PostgreSQL 16 + миграции Alembic
- Кэш: Redis 7
- Очередь: Celery + Redis broker
- Контейнеризация: Docker + Compose
- CI/CD: GitHub Actions
- Деплой: Ansible + Docker Compose на VPS
- Мониторинг: Prometheus + Grafana

## Команды
- `make dev` — поднять локально
- `make test` — все тесты
- `make lint` — линтеры
- `make build` — собрать образ
- `make deploy-test` — деплой в test (через CI; локально не запускать)

## Среды
- **dev** — локально (docker-compose), https://dev.<project>.local
- **test** — VPS https://test.<project>.example.com
- **prom** — VPS https://<project>.example.com

## Структура
- `src/api/` — FastAPI приложение
- `src/web/` — React frontend
- `src/workers/` — Celery воркеры
- `migrations/` — миграции БД
- `tests/` — тесты
- `docs/` — документация (см. `docs/README.md`)

## Конвенции
- Conventional Commits
- Имена веток: `feature/PROJ-NNN-slug`
- ADR: `docs/architecture/adr/`
- Для каждой задачи: `docs/work-items/PROJ-NNN/`

## Правила для агентов
1. Перед любым действием прочесть этот файл и `docs/architecture/README.md`.
2. Никогда не править артефакты других этапов (если не возвращаешь задачу — есть отдельная процедура).
3. Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ.
4. Никогда не закрывать задачу самостоятельно — это делает CI.
5. Бюджет токенов на задачу — в `.openclaw/budget.yaml`. При исчерпании — эскалация.

## Контакты
- Стейкхолдер: <email>
- DevOps: <email>
- Plane Workspace: <url>

Линтеры структуры

В scripts/:

lint-spec.sh — для каждой папки docs/work-items/<id>/:
- проверяет наличие обязательных файлов в зависимости от текущей стадии
- валидирует frontmatter по JSON-Schema
- проверяет, что related: ссылки указывают на существующие файлы
- проверяет покрытие требований (каждый REQ- имеет хотя бы один AC- и TC-)
lint-adr.sh — для каждого ADR:
- проверяет наличие секций (Context, Decision, Alternatives, Consequences)
- проверяет, что superseded_by указывает на существующий ADR
- проверяет монотонность нумерации в папке
render-mermaid.sh — рендерит все .mmd в SVG, падает при синтаксической ошибке.
check-naming.sh — проверяет, что все папки и файлы соответствуют convention (kebab-case, нет пробелов, нет кириллицы в именах).

CI запускает все четыре на каждом PR.

Антипаттерны структуры (чего НЕ делать)

❌ Создавать docs/temp/, docs/old/, docs/2024-archive/. Старое — через git history, не через папки-кладбища.
❌ Хранить ТЗ в виде .docx/.pdf. Только .md (docx можно прикладывать как вложение к BR, но истинная версия — md).
❌ Копировать одно ТЗ из задачи в задачу. Используется related: или ADR.
❌ Класть в docs/work-items/<id>/ файлы, не относящиеся к задаче (общие диаграммы → docs/architecture/).
❌ Менять формат frontmatter «под себя». Поля строго те, что в шаблонах.
❌ Хранить секреты или production-конфиги в репо. Только .env.example без значений.
❌ Версионировать node_modules, .venv, dist, build, скриншоты больше 1MB.

22 KiB Raw Blame History Unescape Escape