@dzhechkov/keysarium 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,564 @@
1
+ # Руководство администратора @dzhechkov/skills-feature-adr
2
+
3
+ Практическое руководство для тимлидов и администраторов проектов по установке, настройке, мониторингу и сопровождению пакета `@dzhechkov/skills-feature-adr` -- 9-шагового адаптивного pipeline для разработки фич с Complexity Router (S/M/L/XL).
4
+
5
+ ---
6
+
7
+ ## 1. Управление компонентами
8
+
9
+ ### Инвентаризация компонентов
10
+
11
+ Пакет устанавливает следующие компоненты в целевой проект:
12
+
13
+ | Компонент | Путь | Содержимое |
14
+ |-----------|------|------------|
15
+ | **SKILL.md** | `.claude/skills/feature-adr/SKILL.md` | Оркестратор pipeline (trigger-паттерны, DAG шагов, переменные) |
16
+ | **9 модулей** | `.claude/skills/feature-adr/modules/00-08` | Протокол для каждого шага pipeline |
17
+ | **4 reference-файла** | `.claude/skills/feature-adr/references/` | `complexity-matrix.md`, `adr-template.md`, `c4-template.md`, `qe-checklist.md` |
18
+ | **1 пример** | `.claude/skills/feature-adr/examples/` | `sample-feature-output.md` -- образец выхода для M-tier фичи |
19
+ | **Команда** | `.claude/commands/feature-adr.md` | Slash-команда `/feature-adr` |
20
+ | **Governance shard** | `.claude/shards/feature-adr.shard.md` | Quality gates, model routing, promise tags по шагам |
21
+ | **Правила** | `.claude/rules/feature-adr-conventions.md` | Конвенции именования, выходной директории, интеграции |
22
+
23
+ Манифест установки хранится в `.skills-feature-adr.json` в корне проекта. Он содержит версию пакета, список установленных компонентов и перечень всех файлов.
24
+
25
+ ### Проверка здоровья установки
26
+
27
+ Команда `doctor` выполняет набор проверок целостности:
28
+
29
+ ```bash
30
+ npx @dzhechkov/skills-feature-adr doctor
31
+ ```
32
+
33
+ Проверки включают:
34
+
35
+ | Проверка | Что проверяется |
36
+ |----------|-----------------|
37
+ | Files exist | Все файлы из манифеста присутствуют на диске |
38
+ | Feature ADR skill pack | SKILL.md, количество модулей и references |
39
+ | Pipeline modules (9 steps) | Наличие всех 9 модулей `00-complexity-router.md` ... `08-qe.md` |
40
+ | Feature ADR command | Наличие `feature-adr*.md` в `.claude/commands/` |
41
+ | Feature ADR rules | Наличие `feature-adr*.md` в `.claude/rules/` |
42
+ | Keysarium integration | Обнаружение `.keysarium.json` (standalone или integrated mode) |
43
+
44
+ При обнаружении проблем `doctor` выводит конкретные рекомендации по исправлению. Типичное решение -- запуск `update` для восстановления отсутствующих файлов.
45
+
46
+ ### Список установленных компонентов
47
+
48
+ ```bash
49
+ npx @dzhechkov/skills-feature-adr list
50
+ ```
51
+
52
+ Выводит таблицу с колонками: название компонента, статус (OK / Missing / Not installed), количество файлов. Также показывает интеграции с Keysarium и BTO, если обнаружены.
53
+
54
+ ---
55
+
56
+ ## 2. Настройка Complexity Router
57
+
58
+ Complexity Router (Step 0) классифицирует фичу по 6 измерениям и определяет tier (S/M/L/XL).
59
+
60
+ ### Настройка весов измерений
61
+
62
+ Оценка по умолчанию суммирует баллы по 6 измерениям с равным весом:
63
+
64
+ | Измерение | Диапазон баллов |
65
+ |-----------|-----------------|
66
+ | Files affected | 1-4 |
67
+ | Domains touched | 1-4 |
68
+ | New integrations | 1-4 |
69
+ | Breaking changes | 1-4 |
70
+ | New data models | 1-4 |
71
+ | Cross-cutting concerns | 1-4 |
72
+
73
+ Суммарный балл определяет tier: S (6-8), M (9-13), L (14-19), XL (20-24).
74
+
75
+ Для настройки под ваш проект отредактируйте `references/complexity-matrix.md`, изменив пороговые значения или добавив вес-множитель к определенным измерениям. Например, если в вашем проекте cross-cutting concern -- это всегда серьезная задача, увеличьте его вес:
76
+
77
+ ```
78
+ Cross-cutting concerns: score * 1.5 (rounded up)
79
+ ```
80
+
81
+ ### Добавление override-правил
82
+
83
+ Стандартные override-правила заданы в `modules/00-complexity-router.md`:
84
+
85
+ - Любое измерение = XL (4 балла) -- минимальный tier L
86
+ - Breaking changes > 0 -- минимальный tier M
87
+ - Пользователь явно задал tier -- использовать его
88
+
89
+ Для добавления проект-специфичных override-правил добавьте секцию в `modules/00-complexity-router.md`:
90
+
91
+ ```markdown
92
+ ### Project-Specific Overrides
93
+
94
+ - Любая миграция БД → минимальный tier M
95
+ - Изменения в модуле auth → минимальный tier L
96
+ - Фичи с изменением публичного API → минимальный tier M
97
+ ```
98
+
99
+ ### Пример: "В нашем проекте любая миграция БД -- это минимум M-tier"
100
+
101
+ Добавьте в секцию Override Rules файла `modules/00-complexity-router.md`:
102
+
103
+ ```markdown
104
+ - If feature involves database migration (new migration file, schema change) → minimum tier is M
105
+ Rationale: DB migrations require ADR (step 3), architecture review (step 5), and full QE
106
+ ```
107
+
108
+ После этого Complexity Router будет автоматически повышать tier при обнаружении миграций.
109
+
110
+ ---
111
+
112
+ ## 3. Настройка шагов
113
+
114
+ ### Кастомизация модулей
115
+
116
+ Каждый шаг pipeline определен в отдельном файле `modules/0N-*.md`. Модули можно настраивать под специфику проекта. Ключевые точки настройки:
117
+
118
+ | Модуль | Что можно настроить |
119
+ |--------|---------------------|
120
+ | `01-requirements.md` | Формат требований, обязательные секции (NFR, constraints) |
121
+ | `03-adr.md` | Шаблон ADR, обязательные секции, минимальное число альтернатив |
122
+ | `05-architecture.md` | Уровни C4 диаграмм, обязательные виды (sequence, deployment) |
123
+ | `06-implementation-plan.md` | Формат задач, поля (estimate, assignee, priority) |
124
+ | `07-code.md` | Конвенции кода, обязательные паттерны, запрещенные практики |
125
+ | `08-qe.md` | Глубина проверок по tiers, обязательные категории review |
126
+
127
+ ### Добавление проектных ADR-шаблонов
128
+
129
+ Файл `references/adr-template.md` содержит базовый шаблон ADR. Для адаптации под проект:
130
+
131
+ 1. Откройте `references/adr-template.md`
132
+ 2. Добавьте обязательные секции вашей команды (например, `## Security Impact`, `## Migration Plan`)
133
+ 3. Добавьте примеры, специфичные для вашего домена
134
+
135
+ ### Настройка QE-чеклистов
136
+
137
+ Файл `references/qe-checklist.md` определяет проверки по категориям и tiers. Для адаптации:
138
+
139
+ 1. Добавьте проект-специфичные проверки в нужную категорию (Security, Performance, Compatibility)
140
+ 2. Настройте глубину проверок по tiers в таблице `Tier-Specific Depth`
141
+ 3. Добавьте свои severity-правила, если стандартные (BLOCKER / WARNING / SUGGESTION) не подходят
142
+
143
+ ### Настройка quality gate thresholds
144
+
145
+ Quality gates определены в governance shard (`feature-adr.shard.md`). Можно ужесточить или ослабить пороги:
146
+
147
+ ```markdown
148
+ ## Step-Level Quality Gates (customized)
149
+
150
+ | Step | Gate |
151
+ |------|------|
152
+ | 3 | Every ADR has >= 3 alternatives (project policy: raised from 2) |
153
+ | 8 | Test coverage >= 80% for L/XL tiers (project policy) |
154
+ ```
155
+
156
+ ---
157
+
158
+ ## 4. Управление артефактами
159
+
160
+ ### Выходная директория
161
+
162
+ Все артефакты создаются в `features/<feature-slug>/`. Эта директория не пересекается с `researches/` (которая используется только pipeline `/casarium`).
163
+
164
+ ### Именование slug
165
+
166
+ - Формат: `kebab-case`, только латинские символы
167
+ - Максимальная длина: 40 символов
168
+ - Примеры: `add-user-auth`, `refactor-payment-flow`, `migrate-to-postgres`
169
+ - Запрещено: даты, номера тикетов в slug (размещайте их внутри артефактов)
170
+
171
+ ### Именование файлов
172
+
173
+ Все артефакты используют нумерованный префикс, соответствующий номеру шага:
174
+
175
+ ```
176
+ features/<feature-slug>/
177
+ 00_complexity_assessment.md
178
+ 01_requirements.md
179
+ 02_research.md # только L/XL
180
+ 03_adr/
181
+ 001-<decision-slug>.md # M+, нумерация сквозная
182
+ 002-<decision-slug>.md
183
+ 04_domain_model.md # только L/XL
184
+ 05_architecture.md # M+
185
+ 06_implementation_plan.md
186
+ 07_code_changes/
187
+ change_manifest.md
188
+ 08_qe_report.md
189
+ diagrams/
190
+ architecture-c4.mermaid # M+
191
+ sequence-<flow-name>.mermaid
192
+ domain-model.mermaid # L/XL
193
+ README.md
194
+ ```
195
+
196
+ ### Нумерация ADR
197
+
198
+ ADR нумеруются последовательно внутри фичи: `001-*.md`, `002-*.md` и т.д. Формат slug -- `kebab-case` с описанием решения. Примеры:
199
+
200
+ - `001-choose-message-queue.md`
201
+ - `002-auth-strategy.md`
202
+ - `003-database-schema-approach.md`
203
+
204
+ ### Именование диаграмм
205
+
206
+ Используйте описательный `kebab-case`: `architecture-c4.mermaid`, `sequence-payment-flow.mermaid`, `domain-model.mermaid`.
207
+
208
+ ### Архивирование завершенных фич
209
+
210
+ После завершения фичи и слияния PR артефакты в `features/<slug>/` остаются как документация. Для архивирования:
211
+
212
+ ```bash
213
+ # Перемещение в архив
214
+ mkdir -p features/_archive
215
+ mv features/<slug> features/_archive/<slug>
216
+ ```
217
+
218
+ ### Очистка незавершенных фич
219
+
220
+ Если pipeline был прерван и фича не будет доработана:
221
+
222
+ ```bash
223
+ # Удаление артефактов незавершенной фичи
224
+ rm -rf features/<slug>
225
+ ```
226
+
227
+ Незавершенные фичи не влияют на работу pipeline -- каждый запуск `/feature-adr` создает новую директорию.
228
+
229
+ ---
230
+
231
+ ## 5. Управление качеством
232
+
233
+ ### Quality gates по шагам
234
+
235
+ Каждый шаг pipeline имеет формальный quality gate, который должен быть пройден перед переходом к следующему шагу:
236
+
237
+ | Шаг | Quality Gate | Tier |
238
+ |-----|-------------|------|
239
+ | 0 -- Complexity Router | Tier обоснован баллами по 6 измерениям, override-правила проверены | All |
240
+ | 1 -- Requirements | Все требования имеют acceptance criteria | M+ |
241
+ | 2 -- Research | Исследования верифицированы, нет hallucinated источников | L/XL |
242
+ | 3 -- ADR | Каждый ADR содержит >= 2 альтернатив с trade-off анализом | M+ |
243
+ | 4 -- DDD | Доменная модель совместима с существующей кодовой базой | L/XL |
244
+ | 5 -- Architecture | Mermaid-диаграммы синтаксически корректны | M+ |
245
+ | 6 -- Implementation Plan | Зависимости задач формируют валидный DAG (нет циклов) | All |
246
+ | 7 -- Code | Код следует конвенциям кодовой базы проекта | All |
247
+ | 8 -- QE | Нет BLOCKER-находок, все MUST-требования имеют статус PASS | All |
248
+
249
+ ### Детализация по шагам
250
+
251
+ **Step 0 (Complexity Router):** Tier должен быть обоснован конкретными баллами по каждому измерению. Пользователь может повысить или понизить tier на checkpoint.
252
+
253
+ **Step 1 (Requirements):** Для M+ tiers каждое функциональное требование должно иметь формулировку acceptance criteria, пригодную для верификации на Step 8.
254
+
255
+ **Step 2 (Research):** Для L/XL tiers все ссылки на аналоги и паттерны должны быть верифицируемы. Применяется принцип PARANOID mode.
256
+
257
+ **Step 3 (ADR):** Минимум 2 альтернативы на каждый ADR. Каждая альтернатива содержит pros/cons и trade-off анализ. Выбранный вариант обоснован.
258
+
259
+ **Step 4 (DDD):** Доменная модель не противоречит существующим bounded contexts в кодовой базе. Ubiquitous language согласован.
260
+
261
+ **Step 5 (Architecture):** Все Mermaid-диаграммы рендерятся без ошибок. Компоненты на диаграммах соответствуют ADR-решениям.
262
+
263
+ **Step 6 (Implementation Plan):** Граф зависимостей задач -- валидный DAG. Нет циклических зависимостей. Каждая задача привязана к файлам.
264
+
265
+ **Step 7 (Code):** Код проходит линтер и type checker проекта. Соблюдаются существующие паттерны именования и структуры.
266
+
267
+ **Step 8 (QE):** Финальная проверка: ни один BLOCKER не остается открытым, все MUST-требования из Step 1 верифицированы с результатом PASS.
268
+
269
+ ---
270
+
271
+ ## 6. Мониторинг
272
+
273
+ ### Отслеживание completion rate
274
+
275
+ Отслеживайте долю фич, прошедших pipeline до конца (Step 8 с вердиктом READY FOR MERGE). Регулярно проверяйте директорию `features/`:
276
+
277
+ ```bash
278
+ # Подсчет завершенных фич (содержат 08_qe_report.md)
279
+ find features/ -name "08_qe_report.md" | wc -l
280
+
281
+ # Подсчет незавершенных (содержат 00_ но не 08_)
282
+ for d in features/*/; do
283
+ [ -f "$d/00_complexity_assessment.md" ] && [ ! -f "$d/08_qe_report.md" ] && echo "$d"
284
+ done
285
+ ```
286
+
287
+ ### Мониторинг распределения tiers
288
+
289
+ Анализируйте распределение tiers в `00_complexity_assessment.md`:
290
+
291
+ - Слишком много XL -- возможно, фичи недостаточно декомпозированы
292
+ - Слишком много S -- возможно, команда обходит полноценный pipeline для средних фич
293
+ - Оптимальное распределение зависит от проекта, но типично: 20% S, 50% M, 25% L, 5% XL
294
+
295
+ ### Анализ итераций на checkpoint
296
+
297
+ Если на одном и том же шаге пользователь регулярно запрашивает доработку (2+ итерации), это сигнализирует о проблемах:
298
+
299
+ - Частые итерации на Step 0: Complexity Router нуждается в калибровке
300
+ - Частые итерации на Step 3: ADR-шаблон недостаточно полный
301
+ - Частые итерации на Step 7: Конвенции кода недостаточно задокументированы
302
+ - Частые итерации на Step 8: Quality gate слишком строгий или требования размыты
303
+
304
+ ### Типичные паттерны обратной связи
305
+
306
+ | Паттерн | Причина | Действие |
307
+ |---------|---------|----------|
308
+ | "Повысь tier" на Step 0 | Router занижает сложность | Добавить override-правило |
309
+ | "Добавь альтернативу" на Step 3 | Недостаточно альтернатив | Увеличить минимум в gate |
310
+ | "Не соответствует конвенциям" на Step 7 | Конвенции не описаны | Дополнить `07-code.md` |
311
+ | "Исправь blocker" на Step 8 | QE находит проблемы | Ужесточить gate на Step 7 |
312
+
313
+ ---
314
+
315
+ ## 7. Интеграция с CI/CD
316
+
317
+ ### QE-отчет в code review
318
+
319
+ Файл `08_qe_report.md` содержит структурированный отчет: количество тестов, review findings по severity, покрытие acceptance criteria. Используйте его в PR:
320
+
321
+ ```markdown
322
+ ## QE Summary (from features/<slug>/08_qe_report.md)
323
+ - Tests: 42/42 passed
324
+ - Review: 0 blockers, 2 warnings, 5 suggestions
325
+ - Requirements: 8/8 covered
326
+ - Verdict: READY FOR MERGE
327
+ ```
328
+
329
+ ### ADR-файлы как часть PR-документации
330
+
331
+ Включайте ADR-файлы из `features/<slug>/03_adr/` в PR как обоснование архитектурных решений. Ревьюеры получают контекст: какие альтернативы рассматривались, почему выбран данный подход.
332
+
333
+ ### Архитектурные диаграммы в технической документации
334
+
335
+ Mermaid-диаграммы из `features/<slug>/diagrams/` рендерятся нативно в GitHub, GitLab и большинстве систем документации. Копируйте или ссылайтесь на них из технической документации проекта.
336
+
337
+ ### Implementation plan как описание PR
338
+
339
+ Файл `06_implementation_plan.md` содержит декомпозицию задач с зависимостями. Используйте его как описание PR или как чеклист для self-review:
340
+
341
+ ```markdown
342
+ ## Implementation Checklist
343
+ - [x] Task 1: Create migration (files: db/migrations/...)
344
+ - [x] Task 2: Add domain model (files: src/models/...)
345
+ - [x] Task 3: Implement API endpoint (files: src/api/...)
346
+ - [x] Task 4: Add tests (files: tests/...)
347
+ ```
348
+
349
+ ---
350
+
351
+ ## 8. Масштабирование
352
+
353
+ ### Параллельный запуск нескольких pipeline
354
+
355
+ Несколько `/feature-adr` pipeline могут работать параллельно, если каждый использует уникальный slug. Каждый pipeline создает изолированную директорию `features/<slug>/` и не конфликтует с другими.
356
+
357
+ Ограничения при параллельной работе:
358
+ - Код в Step 7 может изменять одни и те же файлы в разных pipeline -- координируйте на уровне git-веток
359
+ - Нумерация ADR независима внутри каждой фичи -- глобального реестра нет
360
+
361
+ ### Командные конвенции для slug
362
+
363
+ Установите командные правила именования slug:
364
+
365
+ ```
366
+ <team-prefix>-<feature-description>
367
+ ```
368
+
369
+ Примеры:
370
+ - `payments-add-stripe-webhook`
371
+ - `auth-migrate-to-oauth2`
372
+ - `ui-redesign-dashboard`
373
+
374
+ Это облегчает навигацию по `features/` при большом числе фич.
375
+
376
+ ### Нумерация ADR между фичами
377
+
378
+ ADR нумеруются локально внутри `features/<slug>/03_adr/`. Если вам нужна глобальная нумерация ADR в проекте, заведите центральный реестр (`docs/adrs/` или аналогичный) и копируйте ADR из `features/` после завершения pipeline.
379
+
380
+ ### Общие reference-материалы
381
+
382
+ Если несколько команд используют `@dzhechkov/skills-feature-adr`, синхронизируйте кастомизации reference-файлов:
383
+
384
+ 1. Храните кастомизированные `references/` в отдельном git-репозитории
385
+ 2. Используйте `scripts/sync-templates.js` для обновления шаблонов
386
+ 3. Или зафиксируйте кастомизации в `references/` и исключите их из `update` (см. раздел 10)
387
+
388
+ ---
389
+
390
+ ## 9. Кастомизация для домена
391
+
392
+ ### Банковский домен
393
+
394
+ Добавьте в `modules/03-adr.md` обязательную секцию:
395
+
396
+ ```markdown
397
+ ### Mandatory ADR Section: Security & Compliance
398
+ - [ ] ФЗ-152 impact assessment
399
+ - [ ] ФСТЭК requirements addressed
400
+ - [ ] On-premise deployment constraints documented
401
+ - [ ] Data residency compliance verified
402
+ - [ ] HITL policy for AI components defined
403
+ ```
404
+
405
+ Рекомендации:
406
+ - В Step 5 (Architecture): all LLM components -- on-premise (GigaChat, YandexGPT, open-source)
407
+ - В Step 8 (QE): обязательный security review с фокусом на данные клиентов
408
+ - Override-правило: любая фича с доступом к ПДн -- минимум tier L
409
+
410
+ ### Домен здравоохранения
411
+
412
+ Добавьте в `references/qe-checklist.md`:
413
+
414
+ ```markdown
415
+ ## Healthcare-Specific Checks
416
+ - [ ] ФЗ-323 compliance verified
417
+ - [ ] Patient data isolation confirmed
418
+ - [ ] HITL mandatory for all clinical decisions
419
+ - [ ] AI explainability documented for medical personnel
420
+ - [ ] Medical device regulation applicability assessed
421
+ ```
422
+
423
+ ### Ритейл и E-commerce
424
+
425
+ Дополните `modules/01-requirements.md`:
426
+
427
+ ```markdown
428
+ ### Retail-Specific NFR
429
+ - Latency budget: define max response time (target < 200ms for recommendations)
430
+ - A/B testing plan: how the feature will be validated in production
431
+ - Personalization vs. privacy balance: GDPR/ФЗ-152 compliance
432
+ - Seasonality handling: behavior during peak load
433
+ ```
434
+
435
+ В Step 8 (QE) добавьте: нагрузочное тестирование для L/XL tiers, проверку latency budget.
436
+
437
+ ### Enterprise и B2B
438
+
439
+ Дополните `references/adr-template.md`:
440
+
441
+ ```markdown
442
+ ## Change Management
443
+ - User training requirements
444
+ - Rollout strategy (big bang / phased / feature flag)
445
+ - Rollback plan
446
+
447
+ ## SLA Impact
448
+ - Uptime requirements affected
449
+ - Performance SLA changes
450
+ - Support team notification
451
+ ```
452
+
453
+ Override-правило: фичи с изменением публичного API или интеграций с legacy-системами -- минимум tier L.
454
+
455
+ ---
456
+
457
+ ## 10. Обновление и миграция
458
+
459
+ ### Команда update
460
+
461
+ ```bash
462
+ npx @dzhechkov/skills-feature-adr update
463
+ ```
464
+
465
+ Команда сравнивает установленные файлы с текущей версией шаблонов и показывает diff:
466
+
467
+ - `+ N file(s) to add` -- новые файлы, которых не было в предыдущей версии
468
+ - `~ N file(s) to update` -- измененные файлы с новым содержимым
469
+ - `= N file(s) unchanged` -- файлы без изменений
470
+
471
+ Для предварительного просмотра без записи:
472
+
473
+ ```bash
474
+ npx @dzhechkov/skills-feature-adr update --dry-run
475
+ ```
476
+
477
+ ### Версионирование шаблонов
478
+
479
+ Версия пакета записывается в манифест `.skills-feature-adr.json`. При обновлении:
480
+ 1. `version` обновляется до текущей версии пакета
481
+ 2. `updatedAt` фиксирует дату обновления
482
+ 3. `files` перестраивается на основе актуального содержимого
483
+
484
+ ### Сохранение кастомизаций при обновлении
485
+
486
+ Команда `update` **перезаписывает** измененные файлы. Если вы кастомизировали модули или references:
487
+
488
+ **Стратегия 1: Backup и merge**
489
+ ```bash
490
+ # Перед обновлением
491
+ cp -r .claude/skills/feature-adr/modules .claude/skills/feature-adr/modules.bak
492
+ npx @dzhechkov/skills-feature-adr update
493
+ # Вручную перенесите кастомизации из .bak
494
+ diff .claude/skills/feature-adr/modules/ .claude/skills/feature-adr/modules.bak/
495
+ ```
496
+
497
+ **Стратегия 2: Git diff**
498
+ ```bash
499
+ git stash
500
+ npx @dzhechkov/skills-feature-adr update
501
+ git diff # Посмотрите, что изменилось
502
+ git stash pop # Верните свои кастомизации
503
+ # Разрешите конфликты
504
+ ```
505
+
506
+ **Стратегия 3: Отдельные файлы для кастомизаций**
507
+
508
+ Вместо модификации стандартных файлов, добавляйте проект-специфичные расширения в отдельные файлы (например, `references/qe-checklist-project.md`) и ссылайтесь на них из модулей. Так `update` не затронет ваши кастомизации.
509
+
510
+ ### Миграция между мажорными версиями
511
+
512
+ При мажорном обновлении (1.x -> 2.x) возможны breaking changes:
513
+ 1. Прочитайте CHANGELOG в репозитории пакета
514
+ 2. Запустите `update --dry-run` для оценки масштаба изменений
515
+ 3. Запустите `doctor` после обновления для проверки целостности
516
+ 4. Проверьте кастомизации -- структура модулей или reference-файлов могла измениться
517
+
518
+ ---
519
+
520
+ ## 11. Устранение неполадок
521
+
522
+ ### Таблица типичных проблем
523
+
524
+ | Проблема | Причина | Решение |
525
+ |----------|---------|---------|
526
+ | Неверная классификация tier | Complexity Router неточно оценил измерения | На checkpoint Step 0 используйте "повысь" / "понизь" для явной коррекции. Добавьте override-правило в `modules/00-complexity-router.md` |
527
+ | Отсутствует ADR (нет `03_adr/`) | Step 3 пропущен для M-tier | Проверьте `{ACTIVE_STEPS}` в `00_complexity_assessment.md`. Для M-tier Step 3 должен быть в списке. Если нет -- перезапустите с явным tier M |
528
+ | QE находит BLOCKER-ы | Код не проходит quality gate | Откройте `08_qe_report.md`, найдите BLOCKER-записи. Исправьте каждую и запросите "повтори QE" |
529
+ | Конфликт параллельных агентов | Два агента пишут в один файл | Проверьте file write isolation. Для L/XL tiers агенты работают параллельно только на разных шагах (2||3, 4||5) или разных модулях (Step 7). Если конфликт -- перезапустите шаг |
530
+ | Pipeline прерван на середине | Сессия завершилась или произошла ошибка | Pipeline можно перезапустить с последнего checkpoint. Существующие артефакты не будут потеряны. Запустите `/feature-adr` и укажите продолжение с нужного шага |
531
+ | `doctor` показывает missing files | Файлы удалены или повреждены | Запустите `npx @dzhechkov/skills-feature-adr update` для восстановления |
532
+ | Mermaid-диаграммы не рендерятся | Синтаксическая ошибка в `.mermaid` | Quality gate Step 5 должен это ловить. Если пропущен -- откройте файл в Mermaid Live Editor и исправьте |
533
+ | Манифест поврежден | `.skills-feature-adr.json` содержит невалидный JSON | Удалите файл и запустите `npx @dzhechkov/skills-feature-adr init` заново |
534
+ | `update` перезаписал кастомизации | Не сделан backup перед обновлением | Восстановите из git: `git checkout -- .claude/skills/feature-adr/`. См. раздел 10 о стратегиях сохранения кастомизаций |
535
+ | Governance shard не загружается | Файл `feature-adr.shard.md` отсутствует | Запустите `doctor`, затем `update` для восстановления. Shard критичен для quality gates и model routing |
536
+ | Step 7 генерирует код, не соответствующий стилю проекта | Конвенции кода не описаны | Дополните `modules/07-code.md` примерами и конвенциями вашего проекта |
537
+
538
+ ### Полное удаление и переустановка
539
+
540
+ Если ничего не помогает:
541
+
542
+ ```bash
543
+ # Удаление
544
+ npx @dzhechkov/skills-feature-adr remove
545
+
546
+ # Чистая установка
547
+ npx @dzhechkov/skills-feature-adr init
548
+ ```
549
+
550
+ Команда `remove` удаляет все файлы, перечисленные в манифесте, и сам манифест. Директория `features/` с артефактами фич не затрагивается.
551
+
552
+ ---
553
+
554
+ ## Краткая справка по командам
555
+
556
+ | Команда | Назначение |
557
+ |---------|-----------|
558
+ | `npx @dzhechkov/skills-feature-adr init` | Установка пакета в проект |
559
+ | `npx @dzhechkov/skills-feature-adr doctor` | Проверка здоровья установки |
560
+ | `npx @dzhechkov/skills-feature-adr list` | Список установленных компонентов |
561
+ | `npx @dzhechkov/skills-feature-adr update` | Обновление до последней версии |
562
+ | `npx @dzhechkov/skills-feature-adr update --dry-run` | Предпросмотр обновления |
563
+ | `npx @dzhechkov/skills-feature-adr remove` | Удаление из проекта |
564
+ | `/feature-adr [описание фичи]` | Запуск pipeline (в Claude Code) |