AI පර්යේෂණ සාකච්ඡා 16: හොඳ spec coding එකක් කෙසේ විය යුතුද?

හොඳ Spec Coding (Specification-Driven Programming) එකක මූලික අරමුණ වන්නේ "නොපැහැදිලි අදහස්" "නිවැරදි, සත්‍යාපනය කළ හැකි, ක්‍රියාත්මක කළ හැකි ගිවිසුමක්" බවට පරිවර්තනය කිරීමයි. එය හුදෙක් ලේඛනයක් ලිවීම නොව, මිනිසුන් සහ AI (හෝ මිනිසුන් අතර) අපැහැදිලි භාෂාවක් නොමැති සන්නිවේදන භාෂාවක් ස්ථාපිත කිරීමකි. පහත දැක්වෙන්නේ spec හි අන්තර්ගත ව්‍යුහය, ලිවීමේ මූලධර්ම, AI සමඟ සහයෝගීතා ක්‍රියාවලිය, තත්ත්‍ව සත්‍යාපනය යන මාන හතරෙන් හොඳ spec එකක ස්වරූපයයි.

1. පිරිවිතර ලේඛනයේ සම්මත ව්‍යුහය (ක්‍රියාකාරී මොඩියුලයක් උදාහරණයට)

පරිච්ඡේදය	අනිවාර්ය අන්තර්ගතය	උදාහරණය
1. ඉලක්කය සහ විෂය පථය	එක් වාක්‍යයකින් කුමක් කරන්නේද යන්න, නොකරන්නේ කුමක්ද යන්න පැහැදිලි කරන්න	"පරිශීලක ලියාපදිංචි API ක්‍රියාත්මක කරන්න, ඊමේල් සත්‍යාපනය ඇතුළත් නොවේ"
2. ආදාන/ප්‍රතිදාන ගිවිසුම	දත්ත ව්‍යුහය, වර්ගය, අනිවාර්ය/විකල්ප ක්ෂේත්‍ර, උදාහරණ අගය	`POST /register` ඉල්ලීම් ශරීරය `{email: string, password: string}`, ප්‍රතිචාරය `201` හෝ `400` දෝෂ කේතය සහිතව
3. හැසිරීම සහ තර්කනය	ව්‍යාපාර රීති, සීමා කොන්දේසි, තත්ත්ව සංක්‍රමණ	"මුරපදයේ දිග 8-20 අක්ෂර, අවම වශයෙන් එක් ඉලක්කමක් අඩංගු විය යුතුය; ඊමේල් දැනට පවතී නම් `409` ආපසු දෙන්න"
4. දෝෂ හැසිරවීම	සියලු විය හැකි අසාමාන්‍ය අවස්ථා සහ ඒවාට අනුරූප දෝෂ කේත/පණිවිඩ	"දත්ත සමුදා සම්බන්ධතා අසාර්ථක වීම → `503` ආපසු දෙන්න, ගොඩගැසීම හෙළි නොකරන්න"
5. ක්‍රියාකාරී නොවන අවශ්‍යතා	කාර්ය සාධනය (ප්‍රතිචාර කාලය < 200ms), ආරක්ෂාව (පරාමිතිකරණය කළ විමසුම්), ලොග් කිරීම, නිරීක්ෂණය කිරීමේ හැකියාව	"සියලු SQL පූර්ව සම්පාදනය කළ යුතුය; `email` ලොග් කරන්න නමුත් `password` ලොග් නොකරන්න"
6. පරීක්ෂණ අවස්ථා (ප්‍රධාන)	අවම වශයෙන් සාමාන්‍ය ආදාන 3ක් + සීමා/අසාමාන්‍ය ආදාන 2ක්, අපේක්ෂිත ප්‍රතිදානය දෙන්න	පහත වගුව බලන්න
7. පරායත්තතා සහ සීමාකිරීම්	භාවිතා කරන පුස්තකාල, අනුවාද, පරිසර විචල්‍ය	"Python 3.10+, FastAPI, පරිසර විචල්‍ය `DB_URL`"

පරීක්ෂණ අවස්ථා උදාහරණ (spec තුළ කාවැද්දූ)

අවස්ථාව	ආදානය	අපේක්ෂිත ප්‍රතිදානය
සාමාන්‍ය ලියාපදිංචිය	email: `a@b.com`, pwd: `Pass1234`	`201`, `user_id` ආපසු දෙන්න
මුරපදය කෙටි වැඩිය	pwd: `Ab1`	`400`, දෝෂ කේතය `WEAK_PASSWORD`
ඊමේල් දැනට පවතී	ඉහත email	`409`, දෝෂ කේතය `EMAIL_EXISTS`

හොඳ Spec එකක් මුලින්ම පරීක්ෂණ අවස්ථා ලිවිය යුතුය, මන්ද AI ඒවා සෘජුවම ඒකක පරීක්ෂණ ජනනය කිරීමට භාවිතා කරයි, පසුව ස්වයංක්‍රීයව සත්‍යාපනය කරයි.

2. Spec ලිවීමේ මූලික මූලධර්ම (SMART විචලනය)

මූලධර්මය	පැහැදිලි කිරීම	ප්‍රතිවිරුද්ධ උදාහරණය
නිවැරදි (Precise)	නිශ්චිත සංඛ්‍යා, වර්ග, බූලියන් කොන්දේසි භාවිතා කරන්න, "හැකිතාක්", "සාමාන්‍යයෙන්" වළකින්න	❌ "මුරපදය ප්‍රමාණවත් තරම් ආරක්ෂිත විය යුතුය" → ✅ "මුරපදය අවම වශයෙන් අක්ෂර 8ක්, ලොකු අකුරක්, කුඩා අකුරක්, ඉලක්කමක් අඩංගු විය යුතුය"
සත්‍යාපනය කළ හැකි (Verifiable)	සෑම අවශ්‍යතාවයක්ම ස්වයංක්‍රීය පරීක්ෂණයකින් හෝ අතින් පරීක්ෂා කිරීමෙන් සමත්/අසමත් ලෙස තීරණය කළ හැකි විය යුතුය	❌ "කේතය අලංකාර විය යුතුය" → ✅ "ශ්‍රිත චක්‍රීය සංකීර්ණත්වය ≤ 10, පුනරාවර්තන කේත කොටස් නොමැත"
අපැහැදිලි නොවන (Unambiguous)	එකම පදය සමස්ත ලේඛනය පුරා එකම අර්ථයක් දිය යුතුය, අවශ්‍ය නම් පදමාලාවක් දෙන්න	❌ "පරිශීලකයා නොපවතී නම්, දෝෂයක් ආපසු දෙන්න" → ✅ "පරිශීලකයා නොපවතී → `404` සහ `{code: 'USER_NOT_FOUND'}` ආපසු දෙන්න"
සම්පූර්ණ (Complete)	සාමාන්‍ය මාර්ගය, සියලු අසාමාන්‍ය මාර්ග, ක්‍රියාකාරී නොවන අවශ්‍යතා ආවරණය කරන්න	❌ සාර්ථක අවස්ථා පමණක් ලියා ඇත → ✅ දත්ත සමුදා කල් ඉකුත්වීම, අවසර නොමැතිකම ආදිය ඇතුළත්
පරමාණුක (Atomic)	එක් spec එකක් විස්තර කරන්නේ ස්වාධීනව ලබා දිය හැකි එක් ක්‍රියාකාරී ලක්ෂ්යයක් පමණි (AI එකවර සම්පූර්ණ කිරීමට පහසු)	❌ "සම්පූර්ණ ගෙවීම් පද්ධතිය" සඳහා එක් spec එකක් → ✅ "ගෙවීම් ස්ලිපයක් ජනනය කිරීම", "කැබ්බැක් අත්සන් සත්‍යාපනය", "ආපසු ගෙවීම" ලෙස බෙදන්න

3. AI සමඟ සහයෝගීතාවයේ Spec Coding ක්‍රියාවලිය

මිනිසා spec ලියයි (ඉහත ව්‍යුහය, විශේෂයෙන් පරීක්ෂණ අවස්ථා සහ ශ්‍රිත අත්සන් හොඳින් ලියන්න).
spec එකවර AI වෙත ලබා දෙන්න (සංවාදයක් ලෙස අමතර අවශ්‍යතා එකතු නොකරන්න, vibe දූෂණය වළක්වා ගන්න).
AI කේතය + ඒකක පරීක්ෂණ නිපදවයි (AI විසින් spec හි පරීක්ෂණ අවස්ථා අනුව ක්‍රියාත්මක කළ හැකි පරීක්ෂණ ජනනය කළ යුතුය).
පරීක්ෂණ ධාවනය කරන්න: සියල්ල සමත් වුවහොත්, ඊළඟ පියවරට යන්න; අසමත් වුවහොත්, spec වෙනස් කරන්න හෝ කේතය සෘජුවම නිවැරදි කරන්න (මෙම අවස්ථාවේ කුඩා චක්‍රයකට ඇතුළු විය හැකි නමුත් වෙනස්කම් සටහන් කරන්න).
මිනිස් පරීක්ෂාව: spec වලින් පිටත ක්‍රියාකාරීත්වයක් හඳුන්වා දී ඇත්දැයි (scope creep) පරීක්ෂා කරන්න, ආරක්ෂාව/කාර්ය සාධනය පරීක්ෂා කරන්න.
ස්ථාවර කිරීම: spec ලේඛනය සහ අවසාන කේතය ගබඩාවට එකට යොමු කරන්න, ස්ථාවර ලේඛනයක් ලෙස.

ප්‍රධාන භාවිතය: Spec කේතීකරණය කිරීම – spec.md + test_spec.py භාවිතා කරන්න, එහිදී පරීක්ෂණ ගොනුව spec හි උදාහරණ වලින් සෘජුවම පැමිණේ, එමඟින් පසුව කේතය වෙනස් කිරීමේදී පරීක්ෂණ ධාවනය කිරීමෙන් spec බිඳී ඇත්දැයි සත්‍යාපනය කළ හැක.

4. හොඳ Spec එකකින් ලැබෙන ප්‍රතිඵල (පිළිගැනීමේ නිර්ණායක ලෙස භාවිතා කළ හැක)

නිශ්චිතතාව: එකම spec විවිධ AI (හෝ විවිධ පුද්ගලයින්) වෙත ලබා දුන් විට සමාන ක්‍රියාත්මක කිරීම් ලැබේ.
පරීක්ෂා කිරීමේ හැකියාව: කේතය ලිවීමෙන් පසු වහාම ස්වයංක්‍රීයව නිවැරදි බව 90% ක් සත්‍යාපනය කළ හැක.
නඩත්තු කිරීමේ හැකියාව: මාස හයකට පසු ඕනෑම කෙනෙකුට spec බැලීමෙන් මුල් සැලසුම් අභිප්‍රාය තේරුම් ගත හැක.
අඩු සන්නිවේදන පිරිවැය: කණ්ඩායම් සාකච්ඡාවේදී කේත පේළි ගැන නොව spec ගැන පමණක් සාකච්ඡා කරන්න.
ආරක්ෂාව/තත්ත්වය ගොඩනඟා ඇත: ආරක්ෂක අවශ්‍යතා (පරාමිතිකරණය කළ විමසුම් වැනි) සහ සීමා කොන්දේසි spec හි ලියා ඇති බැවින් AI ඒවා අනුගමනය කළ යුතුය.

5. හොඳ Spec එකක උදාහරණයක් (ඉතා සරල)

# Spec: පරිශීලක ලියාපදිංචි API

## විෂය පථය
- email, password ලබා ගන්න
- සත්‍යාපන ඊමේල් එවන්නේ නැත, ඊමේල් සත්‍යතාව පරීක්ෂා නොකරන්න

## ගිවිසුම
POST /register
Content-Type: application/json
ඉල්ලීම: { "email": string, "password": string }
ප්‍රතිචාරය 201: { "user_id": string }
ප්‍රතිචාරය 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
ප්‍රතිචාරය 409: { "code": "EMAIL_ALREADY_EXISTS" }

## හැසිරීම
- email RFC 5322 මූලික ආකෘතියට (a@b.c) අනුකූල විය යුතුය
- password: දිග 8-20, අවම වශයෙන් එක් ඉලක්කමක් සහ එක් ලොකු අකුරක් අඩංගු විය යුතුය
- bcrypt භාවිතා කර ලුණු පිරිවැය 10 ක් සමඟ ගබඩා කරන්න
- දත්ත සමුදායට ගබඩා කිරීමට පෙර email දැනට පවතී නම් → 409

## පරීක්ෂණ අවස්ථා (ආදානය -> අපේක්ෂිත තත්ත්ව කේතය+ප්‍රතිචාර ක්ෂේත්‍රය)
| ආදාන email | password | අපේක්ෂාව |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id පවතී |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (දැනට පවතින email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## ක්‍රියාකාරී නොවන
- SQL පරාමිතිකරණය කළ විමසුම් භාවිතා කළ යුතුය (එන්නත් ප්‍රතිරෝධය)
- ලියාපදිංචි වන IP මූලාශ්‍රය ලොග් කරන්න, මුරපදය ලොග් නොකරන්න
- ප්‍රතිචාර කාලය 95% ඉල්ලීම් < 100ms (bcrypt හැර)

## පරායත්තතා
- Python 3.10+, FastAPI, bcrypt, asyncpg

හොඳ Spec Coding = මිනිසාගේ "සැලසුම් තීරණ" යන්ත්‍රයේ "පරීක්ෂණ අවස්ථා + වර්ග අත්සන් + හැසිරීම් සීමා" බවට පරිවර්තනය කිරීම, AI හට ක්‍රියාත්මක කිරීම පමණක් පුරවන්නට ඉඩ දීම, මිනිසා සැමවිටම තත්ත්වය සහ දිශාව පාලනය කරයි.