| name | gen-adr-assist |
| description | Creates, refines, reviews, and expands Architectural Decision Records (ADR) using project templates and tech-radar.json. Use when the user asks for ADRs, turns notes or requirements into ADR, compares architecture options, documents technology or integration choices. |
Навык gen-adr-assist
Используй этот навык, когда пользователь хочет создать, доработать, проверить или расширить архитектурное решение (ADR, Architectural Decision Record)
Когда применять навык
Применяй навык, если пользователь просит:
- написать ADR с нуля;
- превратить заметки, переписку или требования в ADR;
- сравнить варианты и зафиксировать решение;
- оформить выбор технологии, интеграционного подхода, модели данных, платформы, средства безопасности, варианта deployment;
- сначала сделать краткий draft, а затем полный документ;
- учитывать ограничения из
tech-radar.json.
Не применяй навык, если нужен:
- просто текст про архитектуру без фиксируемого решения;
- генерация кода без документирования решения;
- общее описание системы без выбора между альтернативами.
Именование файлов
- Файлы ADR должны именоваться по шаблону
adr-{номер:04d}-{slugify(заголовок)}.md, где slugify преобразует заголовок в нижний регистр, заменяет пробелы и знаки препинания на дефисы. Пример: adr-0001-ispolzovanie-postgresql.md.
- Папка для принятых ADR:
adr/ Не создавай в ней никаких файлов, кроме начинающхся с adr и файлов adr/history.log,adr/INDEX.md
- Папка для новых проектов ADR
adr/proposed
- Папка для устаревших ADR
adr/deprecated
- Папка для замененных ADR
adr/superseded
Добавляй в файл adr/history.log записи о создании ADR и изменении его статуса (переноса в соответствующий подкаталог) в формате YYYY-MM-DD {имя adr файла} {новый статус}
Структура навыка
Основные материалы лежат в двух каталогах:
assets/ — рабочие артефакты: шаблоны, checklist, tech-radar.json;references/ — краткие руководства и справочные материалы.
Используй прежде всего:
assets/adr-template.mdassets/review-checklist.mdassets/tech-radar.jsonreferences/question-flows.mdreferences/adr-types.mdreferences/adr-guide.mdreferences/tech-radar-guide.md
Обязательное поведение
- Проанализируй достаточность информации для заполнения шаблона:
assets/adr-template.md.
- Если информации недостаточно задай не более 3 вопросов из
references/question-flows.md.
- Чётко разделяй:
- факты;
- допущения (assumptions);
- варианты (options / alternatives);
- решение (decision);
- последствия (consequences).
- Один ADR = одно решение. Если решений несколько, предлагай разделить их на несколько ADR.
- Если пользователь назвал конкретную технологию, сначала проверь её в
assets/tech-radar.json.
- Если технология найдена и её
ring = hold, отвергни решение и прямо скажи, что технология находится в статусе hold в tech-radar.json навыка.
- Если технология не найдена в
assets/tech-radar.json, обязательно спроси, нужно ли добавить её в tech-radar.json навыка. До ответа пользователя не считай её согласованной по радару.
- Если технология имеет
ring = trial или assess, допускай её только с явной пометкой о риске, ограничении области применения и необходимости дополнительного обоснования.
tech-radar.json — это ограничение и источник governance-контекста, но не замена архитектурному мышлению.
Порядок работы
Шаг 0. Проверка упомянутых технологий в tech-radar.json
До архитектурных вопросов проверь, назвал ли пользователь конкретные продукты, frameworks, brokers, databases, platforms или tools.
Если технология названа:
- найди её в
assets/tech-radar.json;
- примени правила из
references/tech-radar-guide.md;
- только после этого переходи к формированию ADR.
Шаг 1. Определи тип ADR
Сопоставь запрос с одним из типовых решений:
- выбор технологии (technology choice);
- интеграция (integration style / API / messaging / file exchange);
- данные (data design / storage / ownership);
- безопасность (security / IAM / compliance);
- развертывание (deployment / runtime / platform);
- build vs buy;
- архитектурный принцип или правило.
Если тип неочевиден, используй references/question-flows.md.
Шаг 2. Задай минимум уточняющих вопросов
Задавай вопросы только о том, что меняет решение.
Обычно это:
- предмет решения;
- границы и затрагиваемые системы;
- драйверы решения (decision drivers);
- ограничения и стандарты;
- сроки или delivery pressure;
- ключевые quality attributes;
- варианты;
- риски и влияние на migration.
Нормальный объём — 3–5 сильных вопросов, а не длинная анкета.
Шаг 3. Подготовь ADR
Как только основы понятны, создай короткий draft по assets/adr-template.md.
Он должен содержать:
- заголовок;
- статус;
- краткий context;
- decision drivers;
- варианты с плюсами и минусами;
- предлагаемое решение;
- последствия;
- допущения и открытые вопросы.
Шаг 4. Отдай draft на review
После короткого draft попроси проверить:
- корректность формулировки решения;
- полноту вариантов;
- не пропущены ли ограничения;
- реалистичность последствий;
- можно ли раскрывать draft в полный ADR.
Используй assets/review-checklist.md.
Как задавать уточняющие вопросы
Руководствуйся references/question-flows.md и следующими правилами:
- задавай вопросы по важности для решения, а не по порядку разделов документа;
- предпочитай вопросы, на которые можно ответить коротко;
- там, где можно, предлагай варианты ответа;
- не спрашивай то, что уже можно вывести из контекста;
- не повторяй то, что пользователь уже сказал ранее.
Хорошие примеры:
- «Что именно выбираем: СУБД (database), способ интеграции (integration style) или границу владения данными (ownership boundary)?»
- «Что важнее: time-to-market, reliability, latency, cost или compliance?»
- «Есть ли ограничения по cloud, stack, data residency, support skills или стандартам безопасности?»
Плохие примеры:
- просить сразу заполнить все разделы ADR;
- задавать абстрактные вопросы без влияния на решение;
- требовать полный prose-текст до короткого draft.
Правила для tech-radar.json
Используй assets/tech-radar.json в формате Thoughtworks Build Your Own Radar.
Ожидаемая форма:
- корневое значение — JSON array;
- каждый элемент — blip / entry;
- обязательные поля обычно включают:
nameringquadrantisNewdescription
- дополнительное поле
status можно использовать для движения между ring.
Интерпретация ring:
adopt — предпочтительный вариант по умолчанию, если он подходит по драйверам;trial — допустимо в ограниченном scope с явным описанием риска;assess — допустимо как исследуемый вариант, обычно не как массовый стандарт;hold — вариант должен быть отклонён.
Правило для явно названной технологии
Если пользователь прямо называет технологию:
- сначала проверь её в
assets/tech-radar.json;
- если
hold — отвергни решение;
- если записи нет — спроси, нужно ли создать дополнение к
tech-radar.json; сформируй файл дополнения
- до подтверждения не называй её «согласованной» или «рекомендованной» по радару.
Как писать об отклонении
Если технология в hold, формулируй примерно так:
- решение в текущем виде отклоняется;
- причина — технология находится в ring
hold в tech-radar.json навыка;
- предложи альтернативы из
adopt, trial или assess, если они есть;
- отрази это в ADR как ограничение или как отклонённую альтернативу.
Как писать о технологии, которой нет в радаре
Если технологии нет в assets/tech-radar.json:
- явно скажи, что она отсутствует в skill radar;
- спроси, нужно ли добавить её в
tech-radar.json навыка;
- если работу надо продолжать сразу, зафиксируй это как open governance question.
Требования к качеству ADR
Хороший ADR, созданный этим навыком:
- формулирует решение одной фразой;
- объясняет, почему вопрос возник сейчас;
- показывает реальные альтернативы;
- связывает аргументацию с decision drivers;
- честно отражает trade-offs;
- фиксирует последствия, включая негативные;
- определяет scope и impact;
- описывает migration / rollout, если это важно.
Слабый ADR обычно:
- описывает тему, но не решение;
- содержит только один вариант;
- скрывает компромиссы;
- смешивает несколько решений;
- не даёт понять, что делать дальше.
Предпочтительный формат ответа модели
Если данных мало
- кратко сформулируй, какое решение ты видишь;
- задай 3–5 вопросов;
- если пользователь уже назвал технологию — сначала обработай
tech-radar.json.
Если данных достаточно для short draft
- выдай короткий ADR по шаблону;
- отдельно покажи assumptions и open questions;
- предложи review по checklist.
Если есть подтверждение
- раскрой документ в полный ADR;
- сохрани решение и основные trade-offs;
- добавь детали implementation / migration / governance только там, где они уместны.
Краткий чек-лист перед сохранением
Используй assets/review-checklist.md для проверки решения
