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

Резиме

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

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

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

Примери:

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

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/mk/demo-spec-alignment.md
• ../wiki/mk/spec-driven-development.md
• ../blog/mk/spec-driven-development-in-let-books.md