127 lines
5.9 KiB
Markdown
127 lines
5.9 KiB
Markdown
# Правила работы агента в проекте IoT
|
||
|
||
## ГЛАВНОЕ ПРАВИЛО
|
||
|
||
**НЕ "СОВЕРШЕНСТВОВАТЬ" РАБОЧИЙ КОД БЕЗ ЯВНОГО УКАЗАНИЯ.**
|
||
|
||
---
|
||
|
||
## ЗАПРЕТ НА ВЫДУМКИ
|
||
|
||
**КАТЕГОРИЧЕСКИ ЗАПРЕЩАЕТСЯ придумывать, догадываться или предполагать:**
|
||
- значения параметров, которые не видны в коде или документации
|
||
- допустимые значения enum/ролей/типов — если не взяты из реального источника
|
||
- поведение API, провайдеров, библиотек — если не подтверждено кодом или документацией
|
||
- любые факты о системе, которые агент "знает" из общих соображений
|
||
|
||
**Если информации нет — спросить у пользователя. Не угадывать.**
|
||
|
||
Если код работает — не трогать. Никаких:
|
||
- рефакторингов "попутно"
|
||
- улучшений стиля
|
||
- добавления комментариев / docstring
|
||
- переименований переменных
|
||
- "пока уж заодно поправлю"
|
||
|
||
Делай только то, о чём явно попросили. Ничего лишнего.
|
||
|
||
---
|
||
|
||
## О проекте
|
||
|
||
IoT managed service — отдельная репа, вынесенная из sless.
|
||
Go модуль: `gitea.services.ngcloud.ru/Nail/IoT`
|
||
Репа: https://gitea.services.ngcloud.ru/Nail/IoT
|
||
|
||
### Компоненты (3 бинарника из одного образа):
|
||
1. **iot-operator** (`cmd/iot-operator/`) — controller-manager (IoTDevice CRD) + REST API на :9090
|
||
2. **mqtt-bridge** (`cmd/mqtt-bridge/`) — MQTT (EMQX) → Kafka bridge
|
||
3. **kafka-consumer** (`cmd/kafka-consumer/`) — Kafka → Postgres pipeline
|
||
|
||
### Стек:
|
||
- Go 1.25, controller-runtime v0.14, gorilla/mux
|
||
- CRD: `iot.kube5s.ru/v1alpha1` (IoTDevice)
|
||
- EMQX — MQTT брокер, Kafka — очередь телеметрии
|
||
- PostgreSQL — per-tenant databases для телеметрии
|
||
- Docker Hub: `naeel/iot-operator`
|
||
|
||
### Структура:
|
||
```
|
||
cmd/iot-operator/ — точка входа (controller + API сервер)
|
||
cmd/mqtt-bridge/ — MQTT→Kafka bridge
|
||
cmd/kafka-consumer/ — Kafka→Postgres
|
||
api/v1alpha1/ — CRD Go types (IoTDevice)
|
||
controllers/ — IoTDevice reconciler
|
||
internal/api/ — REST handlers, router, middleware, UI (go:embed)
|
||
internal/storage/ — iotpg (per-tenant Postgres)
|
||
config/crd/ — CRD YAML manifests
|
||
deployments/k8s/ — k8s deployment YAMLs
|
||
doc/ — документация
|
||
examples/ — примеры (Terraform, handler.py)
|
||
```
|
||
|
||
---
|
||
|
||
## Комментарии в коде
|
||
|
||
Комментарии — обязательны:
|
||
- В начале каждого файла при создании или правке — дата и время изменения
|
||
- На каждой функции/методе — краткое назначение
|
||
- На нетривиальной логике — **почему** сделано именно так (не "что делает", а "зачем")
|
||
|
||
Цель: любой агент в новом чате должен понять логику без дополнительных вопросов.
|
||
|
||
---
|
||
|
||
## Темп работы
|
||
|
||
Не спешить. Перед каждым шагом — убедиться что предыдущий понят и согласован.
|
||
|
||
---
|
||
|
||
## Документация
|
||
|
||
Всё важное фиксировать в `doc/`:
|
||
- `doc/architecture/` — архитектура, стек, схемы
|
||
- `doc/api/` — дизайн API
|
||
- `doc/decisions/` — принятые решения с обоснованием
|
||
- `doc/infrastructure/` — инфраструктура, кластер, сервисы
|
||
- `doc/errors/` — ошибки и как решили
|
||
- `doc/progress.md` — трекер задач
|
||
|
||
Обновлять после каждого значимого изменения.
|
||
|
||
---
|
||
|
||
## Именование
|
||
|
||
Имена должны быть **уникальными и осмысленными по всему проекту**:
|
||
- имена файлов
|
||
- имена функций/методов
|
||
- имена переменных/констант
|
||
- имена ресурсов (Terraform, Kubernetes и т.д.)
|
||
|
||
Цель: чтобы поиск по проекту находил нужные сущности без неоднозначности, а имя сразу отражало назначение.
|
||
|
||
Запрещены безликие и повторяющиеся имена вида `handler.py`, `handle`, `data`, `value`, `temp` без контекста.
|
||
|
||
---
|
||
|
||
## Лог мышления (обязательно)
|
||
|
||
Каждый агент в каждом чате **обязан** вести лог своих рассуждений:
|
||
- Папка: `doc/thinking/`
|
||
- Файл: `ГГГГ-ММ-ДД.md` (по дате сессии)
|
||
- В начале файла указать имя агента и модель
|
||
- Если файл на текущую дату уже существует — дописывать в конец, добавив разделитель `---` и имя агента
|
||
- Записывать **полный** ход мыслей: что анализирую, какие гипотезы, что нашёл, что отбросил, к чему пришёл, почему
|
||
- Записывать **до** начала действий (план) и **после** (результат)
|
||
|
||
Цель: пользователь должен видеть весь процесс рассуждений в читаемом виде.
|
||
|
||
---
|
||
|
||
## Git
|
||
|
||
Коммитить и пушить после каждого завершённого этапа.
|