1. Команде недостаточно просто «рабочего PR»
Когда вы работаете один и правка маленькая, кажется, что достаточно одного зелёного PR и пары тестов. Но как только появляется команда, ревью, риск и память длиннее одного дня, этого уже мало. Изменение должно быть не только рабочим, но и объяснимым: другой человек поймёт, что произошло, без чтения ваших мыслей и допроса с фонариком.
Здесь полезно развести три близких термина, потому что их часто смешивают в одно «ну там про логи и историю». На самом деле это три разные вещи.
| Термин | Простыми словами |
|---|---|
| Auditability | изменение можно внешне проверить и разобрать по артефактам |
| Traceability | можно пройти по цепочке от задачи до результата |
| Chain of accountability | понятно, кто принял какое решение и на основании чего |
Хорошая аналогия — служба доставки. Когда посылка потерялась, вам не нужна запись каждой секунды со всех камер склада. Вам нужны контрольные точки: кто принял посылку, когда её отсортировали, в какой машине она поехала, кто подписал выдачу. В разработке так же: полный transcript сессии Claude любопытен, но команде ценнее короткая цепочка решений.
Поэтому traceability — это не бюрократия ради бюрократии, а способ ответить на очень практичные вопросы. Что хотели изменить? На каком коде и доказательствах строилось решение? Что реально поменяли? Чем проверили? Кто сказал финальное «да»? Отвечаете «ну мы тогда в чате обсуждали» — traceability у вас декоративная.
2. Звенья traceability chain
Если смотреть на traceability без паники и корпоративного тумана, это просто цепочка уже знакомых вам артефактов. Никаких пяти новых файлов на каждый вдох: вы связываете то, что и так делаете, — просто теперь связь явная и читаемая.
flowchart TD
A[Issue] --> B[TASK_SPEC.md]
B --> C[EVIDENCE_LOG.md]
C --> D[Diff и commits]
D --> E[Tests и REVIEW_NOTES.md]
E --> F[PR_DESCRIPTION.md]
F --> G[Final decision]
У этой цепочки есть очень полезное свойство: каждый её кусок отвечает на свой вопрос, а вместе они собирают полную картину.
| Вопрос | Где искать ответ |
|---|---|
| Что хотели изменить и зачем? | |
| На что опирались при анализе? | |
| Что реально поменяли? | |
| Чем доказали корректность? | тесты, логи проверок, |
| Кто принял решение? | approvers в PR, decision gate, комментарий о финальном решении |
Очень важно заметить одну вещь: цепочка начинается не в момент PR, а в момент постановки задачи. Открыли PR без ясного TASK_SPEC.md — первое звено размазано: команда видит diff, но не понимает договорённости. Есть spec, но нет следов проверки — история рвётся в конце.
Именно поэтому traceability — по сути карта маршрута изменения. Не художественный рассказ, не хроника каждого клика мыши. Маршрут.
3. Curated notes вместо археологии по transcript
Здесь у многих возникает соблазн: «А давайте приложим полный transcript Claude, чтобы точно всё было видно». Звучит честно, а на практике почти всегда делает только хуже. Transcript шумный, с тупиками, старыми гипотезами, иногда с чувствительными данными. Коллеге приходится не проверять изменение, а раскапывать культурный слой вашего дня.
Нормальная командная практика — не публиковать transcript, а делать curated notes, человеческую выжимку. Это как не тащить на ретро весь сетевой дамп за сутки, а показать три строки, на которых держится диагноз. Для этого есть блок AI-assisted workflow notes внутри PR_DESCRIPTION.md или EVIDENCE_LOG.md.
Например:
## Заметки по AI-assisted workflow
- Claude Code использовался для анализа кода и черновика теста.
- План был подтверждён человеком до правок.
- Проверка: регрессионный тест и чтение diff.
- Остаточный риск: крайний случай с часовыми поясами вне текущего scope.
Коротко, но уже очень полезно. Команда может сделать блок обязательным через policy или PR template, а он отвечает сразу на четыре вопроса: где AI действительно помог, где человек явно не отдал управление, чем результат проверили и что осталось риском, а не замели под ковёр.
Полный transcript полезен как локальный след, особенно пока вы сами разбираетесь с задачей. Curated notes, наоборот, читаются за минуту, понятны через месяц и не превращают PR в литературный альманах. Коллеги благодарны, когда вместо 2000 строк терминала видят четыре строчки по делу.
4. Это в реальной задаче Commerce OS
Чтобы traceability не казалась абстракцией, давайте пройдём один небольшой, но вполне реальный по духу сценарий в Commerce OS. Задача ORDER-482: на странице списка заказов иногда появляются дубли при переходе между страницами. Не катастрофа уровня «роняем продакшен», но и не косметика. Затрагивается публичный /api/orders, значит изменение review-required, и команде важна его история.
Начинается всё не с кода, а с TASK_SPEC.md:
# TASK_SPEC.md
## Цель
Убрать дубли заказов в `/api/orders` при постраничной загрузке.
## Ограничения
Не менять публичный API и схему БД.
## Приёмка
Регрессионный тест ловит дубль; страницы 1 и 2 не пересекаются.
Уже на этом этапе другой разработчик видит: задача не про «улучшить запросы в целом», а про конкретный баг с жёстким ограничением — не ломать API и не трогать базу. Без этого потом любой diff на сортировку выглядит как «почему вы вообще туда полезли?».
Дальше появляется EVIDENCE_LOG.md. Он не обязан быть романом — достаточно короткого блока по задаче:
## ORDER-482
- context: `orders/OrderQueryService.java`, `API_MAP.md` → `/api/orders`
- symptom: дубли ID на второй странице после быстрого переключения
- hypothesis: нестабильная вторичная сортировка в запросе
- plan approved by @irina before edits
- check: `./gradlew test --tests *OrderQuery*`
Посмотрите, что здесь уже видно: контекст, наблюдаемый симптом, рабочая гипотеза, факт согласования плана и намеченная проверка. Это и есть traceability в действии: не «я что-то правил в orders», а конкретный след, по которому можно пройти.
Потом начинается стадия фактического изменения. Здесь вашим лучшим другом становится Git, потому что traceability без понятной истории коммитов быстро превращается в гадание по осадкам. Маленькие внятно подписанные коммиты восстанавливают путь за минуту.
git log --oneline --decorate -3
# c91a8b2 add regression test for ORDER-482
# a21c9e4 stabilize secondary sorting in order query
# 73bf012 update PR notes and risk summary
Даже из этих трёх строк видно, что работа шла аккуратно: сначала регрессионный тест, затем минимальная правка запроса, потом обновление заметок. А будь вместо этого один коммит fix stuff — traceability уже заметно просела бы. Git не обязан быть литературным шедевром, но он должен позволять реконструировать ход задачи без телепатии.
В PR_DESCRIPTION.md команда затем видит не только список файлов, но и короткий curated блок:
## Заметки по AI-assisted workflow
- Claude Code использовался для анализа модуля orders и черновика теста.
- План был подтверждён человеком до изменения запроса.
- Проверка: регрессионный тест, diff review, API contract unchanged.
- Остаточный риск: timezone-case для гостевых заказов вне текущего scope.
Теперь тому, кто делает review, вообще не нужно гадать, где помог AI и где осталась ответственность человека. Спросят через две недели про гостевые timezone-case — ответ уже есть в заметке: их вынесли за пределы scope, а не забыли.
И наконец, финальное решение должно быть видимым, а не растворённым в бесконечной ветке комментариев:
## Финальное решение
Merge approved by @irina.
Evidence: regression test green, API contract unchanged, diff within scope.
Вот здесь traceability замыкается: исходная задача, наблюдения, путь изменения, доказательства, человеческое решение. Всплывёт после релиза новый крайний случай — разбор не начнётся с «а кто вообще это мерджил?». След уже есть.
5. Traceability без утечки секретов и данных
После прошлого модуля про sensitive data очень легко скатиться в другую крайность: либо ничего не фиксировать, чтобы не утечь, либо фиксировать всё подряд «ради полной картины». Traceability не даёт лицензии копировать в PR .env.production, реальные e-mail клиентов и сырые логи с персональными данными. Это уже не аккуратность, а маленькое самостоятельное происшествие.
Поэтому хорошая traceability всегда проходит через фильтр санитарии данных. Анализировали реальный заказ — в заметках синтетический ID. Воспроизводили на боевых логах — в evidence только структура ошибки и очищенные поля. Claude прочитал вывод с чувствительным фрагментом — не тащите его в PR_DESCRIPTION.md ради полноты.
Короткая заметка:
## Заметка о чувствительных данных
- Реальные order ID заменены на синтетические.
- `.env.production` не открывался Claude.
- E-mail клиента удалён из приложенного лога перед публикацией.
Команда видит, что вы не забыли о приватности, и одновременно понимает, какие границы вы соблюдали. Хорошая traceability не обязана быть сырой. Она должна быть достаточной: чтобы восстановить решение, но не устроить утечку под видом прозрачности.
6. Traceability как часть обычного workflow
Самая частая причина, почему traceability не работает, довольно прозаична: её пытаются добавлять после всей работы, как отдельный скучный ритуал. В этот момент разработчик уже устал, хочет закрыть задачу и пишет «исправил баг, тесты ок». Понятно, что такая система долго не живёт. Гораздо лучше сделать traceability побочным эффектом нормальной дисциплины.
Хорошая новость в том, что большая часть следов у вас уже есть, если вы работаете маленькими шагами: коммиты создают историю сами, spec отвечает на «что и зачем», evidence-блок фиксирует контекст и гипотезу. Traceability не надо строить сверху как небоскрёб. Её надо просто не ломать.
Из практических мелочей помогают три команды:
git diff origin/main...HEAD # что реально уедет в PR
git log --oneline --decorate -5 # история задачи по коммитам
git show --stat HEAD # какие файлы задел последний шаг
Если вы выполняете их перед финальным ревью, то за минуту увидите, не расползлась ли задача и не осталось ли случайного в ветке. Обновите тут же PR_DESCRIPTION.md, при нужде допишите строку в EVIDENCE_LOG.md — traceability получается почти автоматически.
Есть и приятный побочный эффект. Маленький diff — traceability дёшева. Гигантский — никакой шаблон не спасёт: история расползётся, объяснения станут похожи на оправдания. Поэтому traceability очень хорошо дружит с главным принципом курса — small diffs. Маленькая правка почти сама рассказывает свою историю; огромная требует объяснять, почему вы решились на авантюру.
В итоге вы приходите к очень спокойной рабочей модели. У каждой задачи есть TASK_SPEC.md, у рискованных шагов — след в EVIDENCE_LOG.md, у PR — curated notes вместо археологии по transcript, у Git — понятная история, у команды — явное финальное решение. Merge перестаёт быть гаданием на уверенности автора и становится инженерной процедурой, где по следам можно пройти назад в любой момент — быстро, без драмы и без раскопок в древнем Slack.
Заметьте: все артефакты этой лекции живут вокруг одного изменения — одного issue, одной ветки, одного PR. Но даже идеальный PR-след не спасёт, если команда каждый раз заново спорит, что считать нормой, где проходят общие границы для AI и как оформлять эти следы одинаково. Для этого нужны долгоживущие правила и shared assets Workflow Kit.
ПЕРЕЙДИТЕ В ПОЛНУЮ ВЕРСИЮ