Актуализировать документацию и навигацию для агентов

This commit is contained in:
AidarKC
2026-11-05 22:50:31 +03:00
parent 3c6021a290
commit 4f8c2a72e9
31 changed files with 315 additions and 927 deletions
+20
View File
@@ -0,0 +1,20 @@
# Как поддерживать документацию
## При каждом изменении
1. Определите затронутые компоненты по [карте архитектуры](ARCHITECTURE.md) и прочитайте их локальные `AGENTS.md`.
2. Если меняются наблюдаемое поведение, операция API, формат данных, конфигурация или способ запуска, обновите профильную документацию в том же наборе изменений. Для DM проверьте также документы о доставке, технических вставках и файлах; для Solana — формат PDA и инструкции инициализации.
3. Если изменился состав компонентов или поток данных, обновите `ARCHITECTURE.md`; если появился новый раздел, обновите этот каталог. Публичный README меняйте при изменении возможностей, статуса или способа запуска.
4. Запустите `python3 scripts/check_docs.py` из корня репозитория: он проверяет локальные ссылки в документах и соответствие индекса зарегистрированным WS-операциям. Затем проверьте точность команд/путей вручную. Сравните утверждения с конкретными файлами кода или конфигурации. Непроверенное обозначьте как «требует сверки», планы — как «планируется».
5. В описании изменения укажите, какие документы обновлены и что проверено. Если документацию менять не требуется, кратко объясните почему.
Особые связки: изменение формата блоков требует обновления профильного файла в `Blockchain/` и `Blockchain/CHANGELOG.md`; изменение серверных операций — профильного файла в `API/` и индекса операций; изменение синхронизации Solana users — `Solana/SOLANA_USERS_SYNC_MODULE_DESIGN.md` и `../deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md`; изменение экранов ESP32 — спецификации устройства и скетча. В журнале блокчейна не требуйте хэш ещё не созданного коммита: фиксируйте дату и суть изменения, а ссылку на коммит добавляйте после его появления, если она нужна.
## Источники и статусы
- **Реализовано** — подтверждено кодом; укажите модуль и, если полезно, проверенный сценарий.
- **Тестовый контур** — работает только с тестовыми значениями, ключами или namespace; не обещайте production-поведение.
- **Планируется** — проектное решение, ещё не являющееся контрактом.
- **История/архив** — полезно для контекста, но не для новых интеграций.
Когда документы противоречат друг другу, сначала проверяйте код и тесты, затем правьте обе стороны противоречия. Точные форматы держите в профильной спецификации; обзорные файлы должны ссылаться на неё, а не копировать таблицы байтов или адреса. Для решений, меняющих протокол или требующих согласия на деплой, действуют ограничения из корневого и локальных `AGENTS.md`.