Како одржавати усклађеност спецификације, документације, демонстрације и кода

Основни проблем

Одступање производа ретко почиње драматичном грешком. Обично почиње малим неусклађеностима.

Примери:

• демонстрација дода нови ток рада, али се спецификација никада не ажурира
• документација описује функционалност која се више не понаша тако
• код имплементира згодну пречицу која крши правило производа
• валидационе провере спроводе само синтаксу, а не намеру производа

AI може убрзати све ово ако је ток усклађивања слаб.

Модел усклађивања

Користите овај редослед ауторитета:

1. спецификација производа
2. имплементационе смернице
3. документација тренутног стања
4. понашање демонстрације или апликације
5. тестови и валидациона правила

Нижи слојеви треба да подржавају више слојеве. Ако су у сукобу, ажурирајте ланац намерно уместо да подразумевано победи највидљивији артефакт.

Препоручени ток рада

1. Почните од промене у спецификацији

Ако се мења кориснику видљив ток рада или правило производа, прво ажурирајте одговарајућу спецификацију или смернице.

Користите:

• AGENTS.md за правила и токове рада на нивоу производа
• AGENTS-Implementation.md за тактичка правила репозиторијума и испоруке

2. Ажурирајте документацију тренутног стања

Ако промена утиче на оно што тренутно постоји, ажурирајте документацију која описује тренутно стање.

Типични примери:

• README.md
• docs/Development.md
• docs/Deployment.md
• нови или ревидирани садржај у learning/wiki/blog секцијама где је релевантно

3. Ажурирајте демонстрацију или имплементацију

Тек када је намера јасна, треба мењати демонстрацију или апликацију.

То помаже да се спречи чест образац у коме прототип тихо постаје извор истине.

4. Додајте или ажурирајте валидацију

Затим питајте шта може аутоматски да се провери.

Примери:

• потпуност локализационих кључева
• присуство обавезних фајлова
• генерисање метаподатака
• валидација линкова
• тестови специфични за ток рада

Не може свако правило одмах да се аутоматизује, али важна правила не би требало да остану зависна само од памћења.

5. Прегледајте у односу на спецификацију, не само на излаз

Када прегледате промене, немојте стати на питањима:

• да ли се покреће
• да ли изгледа добро
• да ли тестови пролазе

Питајте и:

• да ли се поклапа са документованим током рада
• да ли чува тражену границу производа
• да ли су документација и опис тренутног стања остали поштени

Како поступати са открићима из демонстрације

Понекад демонстрација научи тим нечему бољем од оригиналне спецификације.

То је корисно. Исправан одговор је:

1. документовати откриће
2. одлучити да ли је промена тока рада намерна
3. ажурирати спецификацију и документацију
4. одржати имплементацију усклађеном са ажурираном одлуком

Погрешан одговор је пустити да демонстрација тихо победи само зато што већ постоји.

Како поступати са имплементацијом уз помоћ AI

Са AI-јем овај ток рада постаје још важнији, јер асистенти често оптимизују локалну вероватноћу.

Добра петља усклађивања је:

1. напишите или ажурирајте спецификацију
2. генеришите имплементацију
3. упоредите излаз са спецификацијом
4. ажурирајте документацију ако се тренутно понашање променило
5. додајте валидацију где је то практично

Пример Let Books

Репозиторијум већ садржи користан ланац усклађивања:

• AGENTS.md за правац производа
• AGENTS-Implementation.md за тактичка правила
• README.md за приказ тренутног стања
• docs/ за правила знања и објављивања
• документацију о развоју и објављивању за смернице валидације

Ту структуру треба намерно користити кад год се додају нове функционалности, документација или јавна објашњења.

Контролна листа

Пре спајања значајне промене проверите:

1. Да ли је правило производа или ток рада јасно документован?
2. Да ли се документација тренутног стања и даље поклапа са стварношћу?
3. Да ли демонстрација или имплементација одражава намеравано правило?
4. Да ли постоји бар један валидациони или прегледни механизам који штити промену?
5. Да ли би нови сарадник касније могао да разуме ту одлуку?

Даље читање

• ../spec-driven-content-program.md
• ../wiki/sr-Cyrl/demo-spec-alignment.md
• ../wiki/sr-Cyrl/spec-driven-development.md
• ../blog/sr-Cyrl/spec-driven-development-in-let-books.md