docs(agents): add Randomayzer project agent rules
This commit is contained in:
ochenstarik-ui
parent
4e4370d6f1
commit
c4e8731758
1 changed files with 149 additions and 0 deletions
149
AGENTS.md
Normal file
149
AGENTS.md
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
# Правила работы агентов — Randomayzer
|
||||
|
||||
Документ адресован любому исполнителю: человеку или агенту. Он описывает не устройство проекта, а обязательный порядок работы над ним.
|
||||
|
||||
## 1. Границы задачи
|
||||
|
||||
Задание определяет область. Выход за неё запрещён, даже когда исправление очевидно и занимает минуту: перемешанные изменения нельзя независимо отревьюить и откатить. Замеченное рядом — отдельным списком в отчёт и предложением следующей задачи.
|
||||
|
||||
Изменять `Randomizer`, `AuditProof`, deterministic proof format, snapshot hash algorithm и алгоритм `HMAC_SHA256_FY_V1` можно только по отдельному прямому заданию владельца проекта.
|
||||
|
||||
## 2. Факты и догадки
|
||||
|
||||
Выдумывать нельзя. Если решение не принято, версия неизвестна, поведение не проверено или контракт VK не подтверждён — так и пишем: `UNVERIFIED` / `не определено`.
|
||||
|
||||
Для фактов о VK API, VK ID, OAuth, token scopes, limits и method capabilities источник истины — актуальная официальная документация VK/VKCOM. Старые примеры, сторонние SDK и предположения не выдавать за подтверждённый контракт.
|
||||
|
||||
## 3. Проверка
|
||||
|
||||
«Работает» — не результат проверки. В отчёт идут команды и фактический результат их запуска.
|
||||
|
||||
Минимальный gate для production-кода:
|
||||
|
||||
```text
|
||||
npm ci
|
||||
npx prisma generate
|
||||
npm test
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
Если какая-либо команда не запускалась или среда не позволила её выполнить, это указывается явно. Нельзя писать `green`, `PASS`, `готово` или `закрыто`, если соответствующая проверка фактически не была выполнена.
|
||||
|
||||
Для concurrency/security задач обязательны заявленные в задании regression/adversarial tests, а не только happy-path unit tests.
|
||||
|
||||
## 4. Задания и результаты
|
||||
|
||||
Задания и отчёты живут в `agents/`. Полная схема — в `agents/README.md`.
|
||||
|
||||
Коротко: задание — в `agents/<agent-id>/inbox/`, результат — в `agents/<agent-id>/done/`, черновики — в `agents/<agent-id>/notes/`.
|
||||
|
||||
Задание, пришедшее в чате, агент сначала фиксирует в своём `inbox/`, и только потом работает. Своих служебных папок за пределами `agents/<agent-id>/` не заводить.
|
||||
|
||||
Каждый результат обязан содержать:
|
||||
- base commit SHA;
|
||||
- resulting commit SHA, если код менялся;
|
||||
- список изменённых файлов;
|
||||
- фактически выполненные команды проверки и их результат;
|
||||
- `CRITICAL/HIGH/MEDIUM/LOW` findings, если это review;
|
||||
- список `UNVERIFIED` утверждений;
|
||||
- оставшиеся blockers и non-blocking tech debt.
|
||||
|
||||
## 5. Роли агентов
|
||||
|
||||
Роль задаётся конкретным заданием и не расширяется самостоятельно.
|
||||
|
||||
- **Antigravity** — основной implementation-agent. Пишет код только в рамках задания, добавляет regression tests и отчёт.
|
||||
- **OpenCode** — implementation/review agent по отдельному заданию. Не дублирует одновременно зону Antigravity без прямого указания.
|
||||
- **Grok** — по умолчанию adversarial/stress reviewer. Production source не меняет, если это прямо не разрешено заданием.
|
||||
- **Claude** — по умолчанию независимый security/code reviewer. Production source не меняет, если это прямо не разрешено заданием.
|
||||
- **Главный агент/координатор** — принимает работу, сводит независимые ревью, определяет статус фазы и разрешает следующий этап.
|
||||
|
||||
Ни один исполнитель не объявляет самостоятельно `Phase CLOSED`, `release-ready` или `production-ready` — это решение принимает только главный агент после проверки evidence.
|
||||
|
||||
## 6. Git и main
|
||||
|
||||
Каждая задача начинается с фиксации base SHA. Перед отчётом агент обязан указать фактический HEAD/result SHA.
|
||||
|
||||
Самостоятельный force-push запрещён.
|
||||
|
||||
Пушить/мержить в `main` разрешено только главному implementation-agent, явно назначенному владельцем проекта для текущей задачи. Review-агенты (Grok/Claude) не пушат production-код и не смешивают review-artifacts с незапрошенными исправлениями.
|
||||
|
||||
Если несколько агентов работают параллельно, их зоны должны быть непересекающимися либо работа должна идти в отдельных ветках/коммитах с последующим контролируемым merge.
|
||||
|
||||
## 7. Security review gate
|
||||
|
||||
Любое изменение в следующих областях требует независимой проверки до закрытия фазы:
|
||||
- authentication / OAuth / PKCE;
|
||||
- authorization / ownership / IDOR;
|
||||
- sessions / cookies / CSRF;
|
||||
- token storage / TokenVault / refresh;
|
||||
- VK auth resolver / SERVICE→USER fallback;
|
||||
- Prisma ownership/credential migrations;
|
||||
- idempotency / rate limiting;
|
||||
- draw concurrency / snapshot integrity;
|
||||
- public verify/audit boundary.
|
||||
|
||||
Минимум один независимый reviewer должен проверить security-sensitive change. Если уже есть `CRITICAL` или `HIGH`, найденный независимым reviewer, он считается открытым, пока отдельная повторная проверка не подтвердит `CLOSED` или главный агент не документирует осознанное исключение.
|
||||
|
||||
Исполнитель не может сам закрыть собственный security finding только формулировкой в отчёте — нужен код/tests/evidence, а для `CRITICAL/HIGH` предпочтительно независимое re-review.
|
||||
|
||||
## 8. Правило доказательности фаз
|
||||
|
||||
Фаза считается закрытой только когда одновременно выполнено:
|
||||
1. Definition of Done исходного задания;
|
||||
2. test/lint/build gate или явно принятая владельцем инфраструктурная оговорка;
|
||||
3. нет открытых release-blocking `CRITICAL/HIGH`;
|
||||
4. независимые review findings сведены и классифицированы;
|
||||
5. итоговый commit SHA зафиксирован;
|
||||
6. главный агент явно объявил фазу закрытой.
|
||||
|
||||
Наличие большого числа тестов само по себе не доказывает отсутствие уязвимости. Для найденного PoC обязательно добавляется regression test, воспроизводящий именно этот сценарий.
|
||||
|
||||
## 9. Секреты и реальные VK credentials
|
||||
|
||||
Никогда не коммитить и не помещать в review-архивы реальные:
|
||||
- VK access/refresh/service/community tokens;
|
||||
- `VK_CLIENT_SECRET`;
|
||||
- `TOKEN_ENCRYPTION_KEY`;
|
||||
- `AUTH_SECRET`;
|
||||
- `.env`, `.env.local`, private keys и credential files.
|
||||
|
||||
Реальные credentials используются только через локальные environment variables. В tests/docs применяются очевидно фальшивые marker tokens.
|
||||
|
||||
Логи, ошибки, API responses, AuditProof и review reports не должны содержать plaintext или encrypted credential values.
|
||||
|
||||
## 10. Review snapshots
|
||||
|
||||
Если reviewer не имеет прямого доступа к репозиторию, source of truth — архив, созданный `tools/export-review.ps1` из конкретного commit SHA.
|
||||
|
||||
Reviewer обязан указать, какой SHA он проверял. Нельзя незаметно подменять snapshot текущим GitHub `HEAD`.
|
||||
|
||||
Для небольшого исправления предпочтителен diff-review от явно указанного base SHA.
|
||||
|
||||
## 11. Архитектурные инварианты Randomayzer
|
||||
|
||||
Без отдельного задания нельзя нарушать следующие инварианты:
|
||||
- Giveaway принадлежит одному authenticated organizer; ownerless production giveaway запрещён.
|
||||
- Чужой organizer credential никогда не выбирается по client-supplied id.
|
||||
- SERVICE token предпочтителен для допустимых публичных VK операций; USER fallback только по явной whitelist-policy.
|
||||
- Rate-limit/network/timeout/temporary/validation errors не используются как причина переключения токена.
|
||||
- Expired/unknown USER credential не используется молча.
|
||||
- Token refresh не должен перезаписывать более новую credential state.
|
||||
- Public verification остаётся отделённой от private organizer/participant/credential данных.
|
||||
- VK auth/token metadata не входит в deterministic draw proof.
|
||||
- Partial participant import не может быть сохранён как полный результат без явного partial/error contract.
|
||||
|
||||
## 12. Новые call sites и trust boundaries
|
||||
|
||||
Любой новый route, background job или service, который вызывает `VkProvider`, `VkAuthContextResolver`, `TokenRefresher` или credential repository, обязан доказать происхождение `organizerId` из доверенного server-side контекста.
|
||||
|
||||
Запрещено передавать в credential resolution `organizerId`, `userId` или `vkUserId`, полученные напрямую из body/query/header клиента, без server-side authorization binding.
|
||||
|
||||
При добавлении нового call site необходимо добавить тест на cross-user/IDOR сценарий или явно объяснить, почему такой сценарий невозможен.
|
||||
|
||||
## 13. Отчётность о несоответствиях
|
||||
|
||||
Если документация, тест и production-код расходятся, source of truth — фактический production-код и реально выполненная проверка. Расхождение фиксируется отдельным finding; нельзя молча «считать», что документация описывает реализованное поведение.
|
||||
|
||||
Если один reviewer говорит `PASS`, а другой воспроизводит конкретный PoC, приоритет имеет воспроизводимый PoC до его опровержения или исправления.
|
||||
Loading…
Reference in a new issue