@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.
- package/README.md +7 -2
- package/package.json +2 -2
- package/templates/.claude/commands/brain-export.md +97 -20
- package/templates/.claude/commands/brain-import.md +75 -4
- package/templates/CLAUDE.md +20 -14
- package/templates/docs/feature-adr/01-architecture.md +750 -0
- package/templates/docs/feature-adr/02-functionality.md +712 -0
- package/templates/docs/feature-adr/03-deployment-guide.md +614 -0
- package/templates/docs/feature-adr/04-admin-guide.md +564 -0
- package/templates/docs/feature-adr/05-user-guide.md +508 -0
- package/templates/docs/feature-adr/06-user-flows.md +1101 -0
- package/templates/docs/keysarium-core/01-architecture.md +559 -0
- package/templates/docs/keysarium-core/02-functionality.md +953 -0
- package/templates/docs/keysarium-core/03-deployment-guide.md +625 -0
- package/templates/docs/keysarium-core/04-admin-guide.md +529 -0
- package/templates/docs/keysarium-core/05-user-guide.md +599 -0
- package/templates/docs/keysarium-core/06-user-flows.md +804 -0
- package/templates/lib/memory-protocol.md +127 -22
|
@@ -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) |
|