568 lines
22 KiB
Markdown
568 lines
22 KiB
Markdown
# 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`
|
||
|
||
```markdown
|
||
---
|
||
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)
|
||
|
||
```markdown
|
||
---
|
||
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` (Техническое задание)
|
||
|
||
```markdown
|
||
---
|
||
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`
|
||
|
||
```markdown
|
||
---
|
||
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)
|
||
|
||
```markdown
|
||
---
|
||
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`
|
||
|
||
```markdown
|
||
---
|
||
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` (паспорт проекта для агентов)
|
||
|
||
Один файл в корне репо — главное, что читает агент при заходе в проект.
|
||
|
||
```markdown
|
||
# 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.
|