# 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. Структура: ``` / ├── 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-.md │ ├── design/ │ │ ├── design-tokens.json # цвета, типографика, spacing │ │ ├── components.md # каталог UI-компонентов │ │ └── style-guide.md │ ├── work-items/ # ⭐ артефакты по задачам │ │ └── / │ │ ├── 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-.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/ # групповые артефакты на фазу │ │ └── / │ │ ├── 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`); в остальных случаях — без префикса. ### Файлы артефактов задачи - Шаблон: `-.` — `01-brd.md`, `04-test-plan.yaml`. - `NN` — двузначный, с ведущим нулём. - `slug` — kebab-case, латиница. - Расширение зависит от типа: `.md` для текстовых, `.yaml` для машинно-читаемых, `.mmd` для Mermaid, `.json` для данных. ### ADR - Шаблон: `adr--.md` — `adr-0017-use-redis-for-rate-limit.md`. - `NNNN` — четырёхзначный, монотонно возрастает в рамках папки. - Глобальные ADR — в `docs/architecture/adr/`. - ADR конкретной задачи — в `docs/work-items//06-adr/`. - ADR могут ссылаться друг на друга, но не должны дублироваться. ### Ветки Git - `feature/-` — фича: `feature/PROJ-123-add-noise-zones-on-map`. - `bugfix/-` — баг. - `hotfix/-` — срочный фикс на prom. - `phase/-` — фаза (если используется фазовая модель). - `chore/` — обслуживание (без Plane-задачи). `` — точный идентификатор 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..` (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: created_by: created_at: 2026-05-04T10:00:00Z priority: medium status: draft | submitted | clarification | approved --- # Business Request — PROJ-123: ## Что хотим <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.