metaagent: install v3.0.0, migrate docs/arch/* → .agent/

- install.sh: .agent/src/ (PROTOCOLS, COMMANDS, TEMPLATES, install.sh/ps1, GUIDE)
- .temp/ добавлен в .gitignore
- .agent/checkpoints.json: phases.init=completed, project_type=existing
- .agent/rules/project-rules.md: R1-R5 (инварианты, ловушки, куда лезть, проверки)
- .agent/context/analysis-report.md: стек, архитектура, конвенции, кандидаты CI
- .agent/context/project-state.md: сжатый слепок (хосты, сервисы, ADR)
- .agent/roadmap/sources.md: открытые вопросы слоёв 0-11 (бывший invariants.md)
- .agent/tasks/manifest.{json,md}: 16 задач A1-F + 23 в backlog
- .agent/decisions/0001-sops-secrets-paths.md: ADR для инварианта S1
- AGENTS.md: metaagent-шапка + сжатая выжимка nixos (yaml frontmatter сохранён)
- удалены docs/arch/{map,invariants,todo}.md
This commit is contained in:
2026-10-09 20:37:14 +03:00
parent 7c9aa24779
commit 16644fcc0b
48 changed files with 4389 additions and 916 deletions
+95
View File
@@ -0,0 +1,95 @@
# ADR — Architecture Decision Record
## Назначение
Зафиксировать архитектурное решение в `.agent/decisions/NNN-slug.md` так, чтобы будущий агент (или человек) мог понять: что решили, почему, какие альтернативы рассматривали, какие последствия.
ADR создаются по явной команде пользователя: «запиши это как решение», «/adr», «сделай ADR для текущего подхода».
## Когда вызывать
- Принято неочевидное архитектурное решение (выбор БД, паттерна, библиотеки, структуры модулей).
- Решение может измениться в будущем — стоит зафиксировать контекст.
- Есть trade-off, который нужно объяснить следующему агенту.
Не вызывать для очевидных вещей: «используем pytest», «классы называем в PascalCase».
## Вход
- Контекст решения: что обсуждалось, какие варианты сравнивались, что выбрали.
- `.agent/decisions/index.json` — текущий список ADR (для нумерации).
- `.agent/context/project-state.md` — текущее состояние проекта.
## Шаги
### 1. Определить номер
Прочитать `.agent/decisions/index.json`. Следующий номер = max существующих + 1. Если файла нет — создать, начать с 001.
### 2. Slug
Короткое имя в kebab-case, отражающее суть: `use-sqlite-for-mvp`, `auth-via-jwt-cookies`, `modular-monolith`.
### 3. Записать ADR
Создать `.agent/decisions/{NNN}-{slug}.md` по шаблону `TEMPLATES/adr-NNNN.md`:
```markdown
# {NNN}. {Заголовок}
**Дата:** {YYYY-MM-DD}
**Статус:** Accepted | Superseded by {NNN} | Deprecated
## Контекст
{Что за проблема. Какие ограничения. Что нужно было решить.}
## Решение
{Что выбрали. Коротко и конкретно.}
## Альтернативы, которые рассмотрели
### {Альтернатива 1}
{Описание. Почему не выбрали.}
### {Альтернатива 2}
{Описание. Почему не выбрали.}
## Последствия
### Положительные
- {что становится лучше}
### Отрицательные
- {что становится хуже или сложнее}
### Инварианты
- {что не должно сломаться, чтобы решение оставалось валидным}
```
### 4. Обновить index.json
```json
{
"version": "3.0.0",
"decisions": [
{ "id": "001", "title": "Использовать SQLite для MVP", "file": "001-use-sqlite-for-mvp.md", "status": "Accepted" }
],
"last_updated": "{timestamp}"
}
```
### 5. Если есть supersession
Если новый ADR отменяет старый — в старом ADR поставить `Статус: Superseded by {NNN}` и добавить ссылку. В новом — в контексте упомянуть, что отменяет.
## Выход
- `.agent/decisions/{NNN}-{slug}.md`
- Обновлённый `.agent/decisions/index.json`
## Связанные команды
- **/invariant-tests** — после ADR можно зафиксировать инварианты как задачи в manifest.
- **/alt-arch** — если хочется явно зафиксировать альтернативу до решения.