mirror of
https://github.com/oqyude/nixos.git
synced 2026-10-10 05:55:24 +03:00
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:
@@ -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** — если хочется явно зафиксировать альтернативу до решения.
|
||||
Reference in New Issue
Block a user