mirror of https://github.com/oqyude/nixos.git synced 2026-10-09 21:47:12 +03:00

Files

T

oqyude 16644fcc0b 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

2026-10-09 20:37:14 +03:00

3.8 KiB

Raw Blame History

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:

# {NNN}. {Заголовок}

**Дата:** {YYYY-MM-DD}
**Статус:** Accepted | Superseded by {NNN} | Deprecated

## Контекст

{Что за проблема. Какие ограничения. Что нужно было решить.}

## Решение

{Что выбрали. Коротко и конкретно.}

## Альтернативы, которые рассмотрели

### {Альтернатива 1}
{Описание. Почему не выбрали.}

### {Альтернатива 2}
{Описание. Почему не выбрали.}

## Последствия

### Положительные
- {что становится лучше}

### Отрицательные
- {что становится хуже или сложнее}

### Инварианты
- {что не должно сломаться, чтобы решение оставалось валидным}

4. Обновить index.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 — если хочется явно зафиксировать альтернативу до решения.

3.8 KiB Raw Blame History