Si të mbani të përafruara specifikimin, dokumentacionin, demonstrimin dhe kodin

Përmbledhje

Ky udhëzues përshkruan një rrjedhë pune praktike për t’i mbajtur të përafruara me kalimin e kohës specifikimin e produktit, dokumentacionin, sjelljen e demonstrimit dhe punën e implementimit.

Problemi kryesor

Devijimi i produktit rrallë fillon me një gabim dramatik. Zakonisht fillon me mospërputhje të vogla.

Shembuj:

• demonstrimi shton një rrjedhë të re pune, por specifikimi nuk përditësohet kurrë
• dokumentacioni përshkruan një veçori që nuk sillet më në atë mënyrë
• kodi implementon një shkurtore të përshtatshme që shkel një rregull të produktit
• kontrollet e validimit zbatojnë vetëm sintaksën, jo synimin e produktit

AI mund t’i përshpejtojë edhe më shumë të gjitha këto nëse rrjedha e përafrimit është e dobët.

Modeli i përafrimit

Përdoreni këtë rend autoriteti:

1. specifikimi i produktit
2. udhëzimet e implementimit
3. dokumentacioni i gjendjes aktuale
4. sjellja e demonstrimit ose e aplikacionit
5. testet dhe rregullat e validimit

Shtresat më të ulëta duhet t’i mbështesin shtresat më të larta. Nëse bien në konflikt, përditësojeni zinxhirin në mënyrë të qëllimshme në vend që të lejoni që artefakti më i dukshëm të fitojë automatikisht.

Rrjedhë pune e rekomanduar

1. Filloni me ndryshimin në specifikim

Nëse ndryshon një rrjedhë pune e dukshme për përdoruesin ose një rregull produkti, përditësojeni së pari specifikimin ose udhëzimin përkatës.

Përdorni:

• AGENTS.md për rregulla dhe rrjedha pune në nivel produkti
• AGENTS-Implementation.md për rregulla taktike të depos dhe dorëzimit

2. Përditësoni dokumentacionin e gjendjes aktuale

Nëse ndryshimi prek atë që ekziston tani, përditësojeni dokumentacionin që përshkruan gjendjen aktuale.

Shembuj tipikë:

• README.md
• docs/Development.md
• docs/Deployment.md
• përmbajtje e re ose e rishikuar te learning/wiki/blog kur është e rëndësishme

3. Përditësoni demonstrimin ose implementimin

Vetëm pasi qëllimi të jetë i qartë duhet të ndryshohet demonstrimi ose aplikacioni.

Kjo ndihmon të shmanget modeli i zakonshëm ku një prototip bëhet në heshtje burimi i së vërtetës.

4. Shtoni ose përditësoni validimin

Pastaj pyesni çfarë mund të kontrollohet automatikisht.

Shembuj:

• plotësia e çelësave të lokalizimit
• prania e skedarëve të kërkuar
• gjenerimi i metadatave
• validimi i lidhjeve
• teste specifike për rrjedhën e punës

Jo çdo rregull mund të automatizohet menjëherë, por rregullat e rëndësishme nuk duhet të varen vetëm nga kujtesa.

5. Rishikoni kundrejt specifikimit, jo vetëm rezultatit

Kur rishikoni ndryshimet, mos u ndalni te pyetjet:

• a ekzekutohet
• a duket mirë
• a kalojnë testet

Pyesni gjithashtu:

• a përputhet me rrjedhën e punës së dokumentuar
• a e ruan kufirin e kërkuar të produktit
• a mbetën të ndershme dokumentacioni dhe përshkrimi i gjendjes aktuale

Si të trajtoni zbulimet nga demonstrimi

Ndonjëherë demonstrimi i mëson ekipit diçka më të mirë se specifikimi fillestar.

Kjo është e dobishme. Përgjigjja e saktë është:

1. dokumentoni zbulimin
2. vendosni nëse ndryshimi i rrjedhës së punës është i qëllimshëm
3. përditësoni specifikimin dhe dokumentacionin
4. mbajeni implementimin të përafruar me vendimin e përditësuar

Përgjigjja e gabuar është të lejoni që demonstrimi të fitojë në heshtje vetëm sepse tashmë ekziston.

Si të trajtoni implementimin me ndihmë nga AI

Me AI, kjo rrjedhë pune bëhet edhe më e rëndësishme sepse ndihmësit shpesh optimizojnë besueshmërinë lokale.

Një cikël i mirë përafrimi është:

1. shkruani ose përditësoni specifikimin
2. gjeneroni implementimin
3. krahasoni rezultatin me specifikimin
4. përditësoni dokumentacionin nëse sjellja aktuale ka ndryshuar
5. shtoni validim kur është praktike

Shembull nga Let Books

Depoja tashmë përmban një zinxhir të dobishëm përafrimi:

• AGENTS.md për drejtimin e produktit
• AGENTS-Implementation.md për rregulla taktike
• README.md për paraqitjen e gjendjes aktuale
• docs/ për rregulla njohurie dhe publikimi
• dokumentacion zhvillimi dhe vendosjeje për udhëzime validimi

Kjo strukturë duhet të përdoret me qëllim sa herë shtohen veçori të reja, dokumentacion ose shpjegime publike.

Listë kontrolli

Përpara bashkimit të një ndryshimi me rëndësi, kontrolloni:

1. A u dokumentua qartë rregulli i produktit ose rrjedha e punës?
2. A përputhet ende dokumentacioni i gjendjes aktuale me realitetin?
3. A e pasqyrojnë demonstrimi ose implementimi rregullin e synuar?
4. A ka të paktën një mekanizëm validimi ose rishikimi që e mbron ndryshimin?
5. A mund ta kuptonte një kontribuues i ri këtë vendim më vonë?

Lexim i mëtejshëm

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