Инструкция разработчика: работа с требованиями и кодом

Основана на нормативной части RENAR — главы §6 Иерархия требований, §8 Specifications, §10 Lifecycle и Quality Gates.

Примеры в этом руководстве ссылаются на конкретную организационную структуру (Kibertum / andersen / princess / gerda / laplandka / zerkalo). При применении в другой организации — заменить на собственные имена систем и подсистем; substrate-agnostic нормативные правила (§6-§14 стандарта) остаются неизменными.

---

Содержание

1. Что нужно знать перед стартом
2. Первоначальная настройка локального окружения
3. Структура папок на локальной машине
4. Настройка рабочего пространства в IDE
5. Работа с требованиями
6. Работа с задачами
7. Git-процесс
8. Частые сценарии
9. Права доступа — кто что может менять
10. Быстрый справочник

---

1. Что нужно знать перед стартом

Два типа репозиториев

Каждая подсистема имеет два отдельных репозитория:

Репозиторий	Суффикс	Что внутри	Кто пишет
Требования	.req	BR, SR — что система должна делать	Архитектор, Tech Lead
Исходный код	.src	Код, тесты, CI/CD	Разработчик

Они разделены намеренно: требования версионируются независимо от кода, имеют другой цикл ревью и другие права доступа.

Иерархия

Система (andersen)
  └── Подсистема (princess, gerda, laplandka, zerkalo)
        └── Модуль (если есть)

Каждый уровень имеет свой .req репозиторий. Требования верхнего уровня — родители для требований ниже.

Три уровня требований

BR  — Бизнес-требование  (зачем это нужно бизнесу)
 └── SR  — Системное требование  (что делает система)
      └── TR  — Требование к задаче  (конкретика для реализации)
                  ↑ это поля вашей задачи в трекере, не файл

TR не является файлом. TR — это Goal + Acceptance Criteria в задаче трекера.

---

2. Первоначальная настройка локального окружения

Шаг 1. Определите свою подсистему

Уточните у Tech Lead, с какой подсистемой вы работаете:

• princess — клиентский портал
• gerda — AI-пайплайн
• laplandka — оркестратор
• zerkalo — публичный сайт

Шаг 2. Создайте локальную структуру папок

mkdir -p ~/projects/kibertum/andersen
cd ~/projects/kibertum/andersen

Шаг 3. Клонируйте нужные репозитории

Обязательно для всех — родительские требования системы (только чтение):

git clone git@gitlab.com:kibertum/andersen/andersen.req

Обязательно — репозитории вашей подсистемы:

# Замените SUBSYSTEM на вашу подсистему: princess / gerda / laplandka / zerkalo
SUBSYSTEM=princess

mkdir -p $SUBSYSTEM
git clone git@gitlab.com:kibertum/andersen/$SUBSYSTEM/$SUBSYSTEM.req $SUBSYSTEM/$SUBSYSTEM.req
git clone git@gitlab.com:kibertum/andersen/$SUBSYSTEM/$SUBSYSTEM.src $SUBSYSTEM/$SUBSYSTEM.src

По необходимости — требования смежных подсистем (только чтение):

# Клонируйте только если работаете с интеграцией
mkdir -p gerda
git clone git@gitlab.com:kibertum/andersen/gerda/gerda.req gerda/gerda.req

Шаг 4. Проверьте результат

find ~/projects/kibertum -maxdepth 4 -name ".git" -type d | sed 's|/.git||' | sort

Ожидаемый результат для разработчика Princess:

~/projects/kibertum/andersen/andersen.req
~/projects/kibertum/andersen/princess/princess.req
~/projects/kibertum/andersen/princess/princess.src

---

3. Структура папок на локальной машине

Локальная структура зеркалит иерархию GitLab. Это важно: относительные пути ../.. между репозиториями становятся предсказуемыми.

~/projects/kibertum/
  andersen/
    andersen.req/          ← требования системы (read-only для разработчика)
    princess/
      princess.req/        ← требования вашей подсистемы
      princess.src/        ← код вашей подсистемы  ← здесь вы работаете
    gerda/
      gerda.req/           ← клонируется по необходимости
      gerda.src/
    laplandka/
      laplandka.req/
      laplandka.src/
    zerkalo/
      zerkalo.req/
      zerkalo.src/

Правило: не меняйте имена папок. Они совпадают с именами проектов в GitLab.
Это позволяет скриптам и CI работать с одними путями везде.

---

4. Настройка рабочего пространства в IDE

VS Code Workspace

Создайте файл workspace в папке подсистемы:

cat > ~/projects/kibertum/andersen/princess/princess.code-workspace << 'EOF'
{
  "folders": [
    {
      "path": "princess.src",
      "name": "Code — Princess"
    },
    {
      "path": "princess.req",
      "name": "Requirements — Princess"
    },
    {
      "path": "../andersen.req",
      "name": "Requirements — System (read only)"
    }
  ],
  "settings": {
    "files.exclude": {
      "**/.git": true
    }
  }
}
EOF

Открыть: code ~/projects/kibertum/andersen/princess/princess.code-workspace

В боковой панели вы видите сразу три репозитория. Переключаться между кодом и требованиями — одно нажатие.

JetBrains (IntelliJ, WebStorm, PyCharm)

Откройте каждый репозиторий как отдельный модуль через File → Attach Project или используйте Project Structure → Modules.

---

5. Работа с требованиями

5.1 Как читать требования

Перед началом задачи прочитайте SR своей задачи:

princess.req/
  sr/
    SR-01-auth.md       ← читаете свой SR

В frontmatter SR найдите поле parent — это ссылка на родительский BR:

parent:
  id: BR-01
  repo: "kibertum/andersen/andersen.req"
  file: "br/BR-01-order-ai-dev.md"

Откройте родительский BR в andersen.req/br/BR-01-order-ai-dev.md — это ответ на вопрос “зачем вообще существует эта функциональность”.

5.2 Как читать трассировку

Полная цепочка от задачи до бизнес-цели:

Задача TASK-42 (ваш трекер)
  → SR-01 (princess.req/sr/SR-01-auth.md)
    → BR-01 (andersen.req/br/BR-01-order-ai-dev.md)

Если что-то непонятно в задаче — поднимайтесь по цепочке вверх.

5.3 Как изменить требование

Разработчик предлагает изменение — создаёт Issue в .req репозитории с описанием несоответствия между SR и реальным поведением.

Tech Lead / Архитектор вносит изменение:

cd princess.req
git checkout -b change/TZ-2026-002-totp

# Редактируете файл SR
# Обновляете version и updated в frontmatter
# Добавляете запись в source[]

git add sr/SR-01-auth.md
git commit -m "[delta:TZ-2026-002] SR-01 v1.2: добавить TOTP"
# Создаёте MR в GitLab

Запрещено: коммитить изменения требований напрямую в main без MR и ревью.

5.4 Что нельзя делать с требованиями

• Менять andersen.req без согласования с архитектором
• Менять требования смежных подсистем (gerda.req, laplandka.req)
• Удалять файлы требований — только переводить в status: deprecated
• Создавать файлы версий (SR-01-v1.md, SR-01-v2.md) — история в git log

---

6. Работа с задачами

6.1 Перед тем как взять задачу

Задача готова к работе, если выполнены все пункты Context Gate QG-0:

• Сформулирована цель (Goal)
• Есть Acceptance Criteria — конкретные, тестируемые, независимые
• Есть хотя бы один негативный сценарий в AC
• Задача ссылается на SR (поле в трекере)
• Назначен тип работы
• Если затрагивает безопасность — Threat Surface задекларирован

Если чего-то нет — не берите задачу в работу. Вернитесь к Supervisor/Tech Lead.

6.2 Acceptance Criteria — как читать

Каждый AC — это отдельный тест. Хорошие AC:

✓ POST /auth/login возвращает 200 и JWT-токен при верных credentials
✓ POST /auth/login возвращает 401 при неверном пароле  ← негативный сценарий
✓ POST /auth/login возвращает 422, если поле email отсутствует
✓ JWT-токен истекает через 24 часа

Плохие AC (задачу брать нельзя):

✗ Логин должен работать корректно
✗ Обработка ошибок должна быть надёжной
✗ Система должна быть безопасной

6.3 Если AC непонятен или противоречит SR

1. Прочитайте SR, на который ссылается задача
2. Прочитайте родительский BR
3. Если противоречие есть — создайте комментарий в задаче с конкретным вопросом

Не интерпретируйте молча. AI интерпретирует молча — именно поэтому и нужны чёткие требования.

---

7. Git-процесс

7.1 Работа с кодом (.src репозиторий)

Стандартный feature-branch workflow:

cd princess/princess.src

# Создать ветку от main
git checkout main && git pull
git checkout -b feat/TASK-42-totp-auth

# ... работа ...

git add src/auth/totp.py
git commit -m "feat(auth): реализовать TOTP-аутентификацию (TASK-42)"

# Создать MR в GitLab

Формат коммита: <type>(<scope>): <описание> (<TASK-ID>)

7.2 Работа с требованиями (.req репозиторий)

cd princess/princess.req

# Ветка для изменения требования
git checkout -b change/TZ-2026-002-totp

# Изменить файл, обновить frontmatter
git add sr/SR-01-auth.md
git commit -m "[delta:TZ-2026-002] SR-01 v1.2: добавить поддержку TOTP"

7.3 Привязка MR к задаче

В описании MR всегда указывайте:

Closes #42
Related SR: SR-01 (princess.req)

Если изменение затрагивает несколько .req репозиториев:

Related: kibertum/andersen/andersen.req!15

7.4 Именование веток

Что делаете	Ветка
Новая функциональность	feat/TASK-NN-slug
Исправление бага	fix/TASK-NN-slug
Изменение требования	change/TZ-YYYY-NNN-slug
Новое требование	feat/BR-NN-slug или feat/SR-NN-slug

---

8. Частые сценарии

Сценарий 1. Начинаю новую задачу

1. Открыть задачу в трекере
2. Проверить QG-0 (все пункты выполнены?)
3. Найти ссылку на SR в задаче
4. Открыть SR в princess.req/sr/
5. Прочитать SR + родительский BR если нужен контекст
6. Создать ветку feat/TASK-NN-slug в princess.src
7. Реализовать + написать тесты по AC
8. MR → ревью → merge

Сценарий 2. Обнаружил несоответствие между SR и требованием задачи

1. НЕ делать ничего молча
2. Добавить комментарий в задачу:
   "SR-01 §3 описывает X, задача требует Y — это противоречие.
    Прошу уточнить."
3. Дождаться ответа Supervisor/Architect
4. Не брать задачу в работу до устранения несоответствия

Сценарий 3. Нужно понять откуда взялось требование

# В .req репозитории
git log -- sr/SR-01-auth.md         # история изменений SR
git show <commit-hash>               # детали конкретного изменения

Или в frontmatter файла найдите поле source — там ссылка на ТЗ и его раздел.

Сценарий 4. Работаю с интеграцией (Princess → Gerda)

# Клонировать требования смежной подсистемы
cd ~/projects/kibertum/andersen
mkdir -p gerda
git clone git@gitlab.com:kibertum/andersen/gerda/gerda.req gerda/gerda.req

# Добавить в workspace
# Открыть andersen.req/int-sr/INT-SR-01-princess-gerda.md
# Там описан контракт интеграции

Интеграционные требования (INT-SR) всегда живут в andersen.req/int-sr/ — не внутри подсистем.

Сценарий 5. Пришло дельта-ТЗ, меняются требования

Это работа архитектора/Tech Lead, но разработчику нужно:

1. Дождаться merge MR с обновлёнными SR
2. Сделать git pull в princess.req
3. Прочитать tz/TZ-YYYY-NNN-index.md — там список изменённых требований
4. Проверить, затрагивают ли изменения ваши текущие задачи
5. Если да — обновить или закрыть задачи по согласованию с Supervisor

Сценарий 6. Обновить локальные репозитории требований

# Скрипт обновления всех .req репозиториев
find ~/projects/kibertum -name "*.req" -type d | while read repo; do
  echo "Updating $repo..."
  git -C "$repo" pull --ff-only
done

---

9. Права доступа — кто что может менять

Репозиторий	Разработчик	Tech Lead	Архитектор
andersen.req (системные BR/SR)	Только чтение	Только чтение	Запись через MR
princess.req (SR подсистемы)	Только чтение	Запись через MR	Запись через MR
princess.src (код)	Запись через MR	Запись + ревью	—
gerda.req (чужая подсистема)	Только чтение	Только чтение	—

Если нужно изменить требование — создайте Issue в .req репозитории, не коммитьте напрямую.

---

10. Быстрый справочник

Куда смотреть когда непонятно

Вопрос	Куда смотреть
Что должна делать система?	princess.req/sr/SR-NN-*.md
Зачем это нужно бизнесу?	andersen.req/br/BR-NN-*.md
Откуда взялось это требование?	frontmatter source → ТЗ
Как изменилось требование?	git log -- sr/SR-NN-*.md
Как работает интеграция с Gerda?	andersen.req/int-sr/INT-SR-01-*.md
Что изменилось по последнему ТЗ?	andersen.req/tz/TZ-YYYY-NNN-index.md

Чеклист перед созданием MR

• Код покрывает все AC из задачи
• Есть тесты на негативные сценарии
• MR содержит ссылку Closes #NN на задачу
• Если изменилось поведение — создан Issue в .req для обновления SR

Команды Git которые используются чаще всего

# Обновить требования
git -C ~/projects/kibertum/andersen/princess/princess.req pull

# Посмотреть историю конкретного SR
git -C ~/projects/kibertum/andersen/princess/princess.req log -- sr/SR-01-auth.md

# Найти требование по ID
grep -r "id: SR-01" ~/projects/kibertum/andersen/ --include="*.md"

# Найти все задачи, ссылающиеся на SR-01
grep -r "SR-01" ~/projects/kibertum/andersen/ --include="*.md"

Глоссарий

Термин	Значение
BR	Бизнес-требование — зачем нужна функциональность
SR	Системное требование — что делает система
TR	Требование к задаче — Goal + AC в трекере
AC	Acceptance Criteria — критерии приёмки задачи
QG-0	Context Gate — проверка готовности задачи к разработке
.req	Git-репозиторий с требованиями подсистемы
.src	Git-репозиторий с кодом подсистемы
INT-SR	Интеграционное требование между подсистемами
delta-ТЗ	Дополнение к ТЗ при повторном заказе
deprecated	Устаревшее требование — не удаляется, только помечается