Аудитованість і відстежуваність змін

1. Команді недостатньо просто «робочого PR»

Коли ви працюєте самі, а правка маленька, здається, що достатньо одного зеленого PR і пари тестів. Але щойно з’являються команда, рев’ю, ризик і пам’ять довша за один день, цього вже замало. Зміна має бути не лише робочою, а й зрозумілою: інша людина збагне, що сталося, без читання ваших думок і допиту з ліхтариком.

Тут корисно розвести три близькі терміни, бо їх часто змішують в одне «ну там про логи й історію». Насправді це три різні речі.

Хороша аналогія — служба доставки. Коли посилка загубилася, вам не потрібен запис кожної секунди з усіх камер складу. Вам потрібні контрольні точки: хто прийняв посилку, коли її відсортували, в якій машині вона поїхала, хто підписав видачу. У розробці так само: повний transcript сесії Claude цікавий, але команді цінніший короткий ланцюжок рішень.

Тому traceability — це не бюрократія заради бюрократії, а спосіб відповісти на дуже практичні запитання. Що хотіли змінити? На якому коді та доказах будувалося рішення? Що реально змінили? Чим перевірили? Хто сказав фінальне «так»? Відповідаєте «ну ми тоді в чаті обговорювали» — traceability у вас декоративна.

2. Ланки traceability chain

Якщо дивитися на traceability без паніки й корпоративного туману, це просто ланцюжок уже знайомих вам артефактів. Жодних п’яти нових файлів на кожен вдих: ви зв’язуєте те, що і так робите, — просто тепер зв’язок явний і читабельний.

flowchart TD
    A[Задача] --> B[TASK_SPEC.md]
    B --> C[EVIDENCE_LOG.md]
    C --> D[Diff і коміти]
    D --> E[Тести і REVIEW_NOTES.md]
    E --> F[PR_DESCRIPTION.md]
    F --> G[Фінальне рішення]

У цього ланцюжка є дуже корисна властивість: кожен його шматок відповідає на своє запитання, а разом вони складають повну картину.

TASK_SPEC.md

CODEBASE_INVENTORY.md

API_MAP.md

EVIDENCE_LOG.md

git diff

PR_DESCRIPTION.md

REVIEW_NOTES.md

QUALITY_GATES.md

Дуже важливо помітити одну річ: ланцюжок починається не в момент 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, і команді важлива її історія.

Починається все не з коду, а з 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 додано регресійний тест для ORDER-482
# a21c9e4 стабілізовано вторинне сортування в запиті замовлень
# 73bf012 оновлено нотатки до PR і підсумок ризиків

Навіть із цих трьох рядків видно, що робота йшла акуратно: спочатку регресійний тест, потім мінімальна правка запиту, потім оновлення нотаток. А якби замість цього був один коміт fix stuff — traceability уже помітно просіла б. Git не зобов’язаний бути літературним шедевром, але він має дозволяти реконструювати хід задачі без телепатії.

У PR_DESCRIPTION.md команда потім бачить не лише список файлів, а й короткий curated блок:

## Нотатки щодо AI-assisted workflow
- Claude Code використовувався для аналізу модуля orders і чернетки тесту.
- План було підтверджено людиною до зміни запиту.
- Перевірка: регресійний тест, review diff, API contract не змінено.
- Залишковий ризик: timezone-case для гостьових замовлень поза поточним scope.

Тепер тому, хто робить review, взагалі не потрібно гадати, де допоміг AI і де лишилася відповідальність людини. Запитають за два тижні про гостьові timezone-case — відповідь уже є в нотатці: їх винесли за межі scope, а не забули.

І нарешті, фінальне рішення має бути видимим, а не розчиненим у безкінечній гілці коментарів:

## Фінальне рішення
Merge схвалено @irina.
Докази: регресійний тест зелений, API contract не змінено, diff у межах 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.