estorozhenko
d426aa39ed
- AGENTS.md: правила проекта (структура доков, стек, статьи, деплой, git, openspec, проверки) - README.md: сокращён до введения + указателей на docs/ - docs/: DEPLOY_INSTRUCTIONS, ROADMAP, PAPERMOD_PARAMS, QWEN, gitea-setup, Telegram_frontend, ssh_setup, archive/PROJECT_SUMMARY (из .qwen/) - tools/: winscp_script.txt переехал из корня к deploy_sftp.py - Makefile и deploy_sftp.py: ссылки на docs/DEPLOY_INSTRUCTIONS.md
87 lines
5.3 KiB
Markdown
87 lines
5.3 KiB
Markdown
# AGENTS.md — правила работы с проектом dedinit.ru
|
||
|
||
## Общие принципы
|
||
|
||
1. Взаимодействие и документация — на русском языке.
|
||
2. Все важные решения и изменения фиксируются в README.md (кратко) и соответствующих документах в `docs/`.
|
||
3. Перед применением изменений проверяется корректность принятых решений.
|
||
4. Цель — максимально быстро публиковать контент без поломки сайта.
|
||
|
||
## Структура документации
|
||
|
||
- `README.md` — ТОЛЬКО краткое введение в проект для репозитория:
|
||
что это, стек, быстрый старт (сборка/деплой) и указатели на `docs/`.
|
||
Никакой подробной документации и истории изменений в README не держим.
|
||
- `docs/` — вся подробная документация проекта:
|
||
инструкции, справочники, дорожные карты, заметки об опыте настройки.
|
||
- `AGENTS.md` — правила работы для агентов (этот файл).
|
||
- Подробная эксплуатационная документация НЕ должна лежать в корне репозитория.
|
||
Новые документы создавать только в `docs/`.
|
||
|
||
## Технологический стек
|
||
|
||
| Параметр | Значение |
|
||
|----------|----------|
|
||
| Генератор | Hugo Extended 0.165.x |
|
||
| Тема | rDedInit (форк PaperMod) |
|
||
| Язык | Русский (ru-ru), timeZone Europe/Moscow |
|
||
| Формат статей | Bundle: `content/posts/<name>/index.md` (+ hero.svg и др.) |
|
||
| Git-хостинг | gitverse.ru — источник истины (kpa39l/dedinit.ru) |
|
||
| Деплой | SFTP на kpa39l.myjino.ru:2222 |
|
||
|
||
## Статьи (контент)
|
||
|
||
- Новые статьи: `content/posts/<YYYYMMDD - slug>/index.md`.
|
||
- Frontmatter: `date`, `lastmod` — в прошлом (Hugo молча не публикует
|
||
страницы с датой в будущем), `draft: false`, `title`, `slug`.
|
||
- hero.svg для статьи: `viewBox="0 0 1200 400"`, фон `#0a0c10`,
|
||
паттерн-гексагон `#1a2332`, заголовок моноширинный `#58a6ff`.
|
||
Копировать hero.svg из последнего поста как базу — единый стиль.
|
||
- Блочный код с подсветкой — обязателен там, где нужен (цель проекта).
|
||
|
||
## Сборка и деплой
|
||
|
||
```bash
|
||
# ЕДИНСТВЕННЫЙ способ деплоя — make deploy. Не заменять на rsync/ssh-exec:
|
||
# аккаунт Jino SFTP-only (exec request failed on channel 0).
|
||
export SSHPASS='<пароль SFTP>'
|
||
make deploy # hugo --minify + mirror public/ → /dedinit.ru
|
||
make deploy-dry-run # симуляция деплоя
|
||
make build # только сборка
|
||
make help # все команды
|
||
```
|
||
|
||
- `public/`, `.venv/`, `.hermes/` — в git не попадают (.gitignore).
|
||
- Пароль SFTP в открытом виде в репозиторий НЕ коммитить
|
||
(winscp_script.txt с паролем был вынесен из корня — см. `tools/`).
|
||
|
||
## Git
|
||
|
||
- Ветка `main`, источник истины — gitverse.ru, пуши через SSH
|
||
(`git@gitverse.ru:kpa39l/dedinit.ru.git`).
|
||
- Gitea (bigbox) — pull-mirror, туда отдельно не пушить.
|
||
- Коммиты — короткие, по смыслу изменений.
|
||
- Секреты и пароли в коммиты не добавлять.
|
||
|
||
## Процессы и планирование
|
||
|
||
- Планирование изменений — OpenSpec: `openspec/` (specs + changes).
|
||
Правки контента/кода — через openspec-скиллы из `.hermes/skills/`
|
||
(propose → design → apply → archive).
|
||
- Проверочные действия перед этапами: `hugo version`, `make build`,
|
||
контроль `hugo.toml`, `make deploy-dry-run`.
|
||
|
||
## Обязательные проверки перед публикацией статьи
|
||
|
||
1. `date` НЕ в будущем (иначе Hugo молча не публикует, без предупреждения).
|
||
2. `make build` проходит без ошибок.
|
||
3. Статья есть в сборке: `ls public/<год>/<slug>/index.html`,
|
||
`grep -o '<title>[^<]*</title>'`, `grep -o 'hero.svg'`.
|
||
4. `git push origin main`, затем при необходимости `make deploy`.
|
||
|
||
## Правила пользователя
|
||
|
||
- Краткие статус-отчёты на русском языке.
|
||
- Тихие watchdog'и: уведомлять только при реальной проблеме.
|
||
- НЕ удалять и не перезаписывать данные пользователя без явного подтверждения.
|
||
- Перед действиями — читать доки проекта (STATUS/PRD/WALKTHROUGH/TODO.md, openspec) и прошлые сессии. |