Gen Adr Assist

Навык 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.md
• assets/review-checklist.md
• assets/tech-radar.json
• references/question-flows.md
• references/adr-types.md
• references/adr-guide.md
• references/tech-radar-guide.md

Обязательное поведение

1. Проанализируй достаточность информации для заполнения шаблона: assets/adr-template.md.
2. Если информации недостаточно задай не более 3 вопросов из references/question-flows.md.
3. Чётко разделяй:
   • факты;
   • допущения (assumptions);
   • варианты (options / alternatives);
   • решение (decision);
   • последствия (consequences).
4. Один ADR = одно решение. Если решений несколько, предлагай разделить их на несколько ADR.
5. Если пользователь назвал конкретную технологию, сначала проверь её в assets/tech-radar.json.
6. Если технология найдена и её ring = hold, отвергни решение и прямо скажи, что технология находится в статусе hold в tech-radar.json навыка.
7. Если технология не найдена в assets/tech-radar.json, обязательно спроси, нужно ли добавить её в tech-radar.json навыка. До ответа пользователя не считай её согласованной по радару.
8. Если технология имеет ring = trial или assess, допускай её только с явной пометкой о риске, ограничении области применения и необходимости дополнительного обоснования.
9. tech-radar.json — это ограничение и источник governance-контекста, но не замена архитектурному мышлению.

Порядок работы

Шаг 0. Проверка упомянутых технологий в tech-radar.json

До архитектурных вопросов проверь, назвал ли пользователь конкретные продукты, frameworks, brokers, databases, platforms или tools.

Если технология названа:

1. найди её в assets/tech-radar.json;
2. примени правила из references/tech-radar-guide.md;
3. только после этого переходи к формированию 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;
• обязательные поля обычно включают:
  • name
  • ring
  • quadrant
  • isNew
  • description
• дополнительное поле status можно использовать для движения между ring.

Интерпретация ring:

• adopt — предпочтительный вариант по умолчанию, если он подходит по драйверам;
• trial — допустимо в ограниченном scope с явным описанием риска;
• assess — допустимо как исследуемый вариант, обычно не как массовый стандарт;
• hold — вариант должен быть отклонён.

Правило для явно названной технологии

Если пользователь прямо называет технологию:

1. сначала проверь её в assets/tech-radar.json;
2. если hold — отвергни решение;
3. если записи нет — спроси, нужно ли создать дополнение к tech-radar.json; сформируй файл дополнения
4. до подтверждения не называй её «согласованной» или «рекомендованной» по радару.

Как писать об отклонении

Если технология в 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 обычно:

• описывает тему, но не решение;
• содержит только один вариант;
• скрывает компромиссы;
• смешивает несколько решений;
• не даёт понять, что делать дальше.

Предпочтительный формат ответа модели

Если данных мало

1. кратко сформулируй, какое решение ты видишь;
2. задай 3–5 вопросов;
3. если пользователь уже назвал технологию — сначала обработай tech-radar.json.

Если данных достаточно для short draft

1. выдай короткий ADR по шаблону;
2. отдельно покажи assumptions и open questions;
3. предложи review по checklist.

Если есть подтверждение

1. раскрой документ в полный ADR;
2. сохрани решение и основные trade-offs;
3. добавь детали implementation / migration / governance только там, где они уместны.

Краткий чек-лист перед сохранением

Используй assets/review-checklist.md для проверки решения