የAI ተከታታይ ቃለ-መጠይቅ 16፡ ጥሩ spec coding ምን መምሰል አለበት？

ጥሩ Spec Coding (Specification-Driven Programming) ዋናው ትኩረቱ “ግልጽ ያልሆነ ሃሳብ” ወደ “ትክክለኛ፣ ሊረጋገጥ የሚችል፣ ተፈጻሚ ውል” መቀየር ነው። የተወሰነ ሰነድ ብቻ አይደለም፣ ነገር ግን በሰዎች እና AI (ወይም በሰዎች መካከል) ግልጽ ያልሆነ የመግባቢያ ቋንቋን ይፈጥራል። ከታች ከይዘት መዋቅር፣ የመጻፍ መርሆዎች፣ ከ AI ጋር የትብብር ሂደት፣ የጥራት ማረጋገጫ አራት ልኬቶች ጥሩ spec ምን መምሰል እንዳለበት እንመለከታለን።

አንድ. የSpec ሰነድ መደበኛ መዋቅር (በተግባራዊ ክፍል ምሳሌ)

ክፍል	የግድ ይዘት	ምሳሌ
1. ዓላማ እና ወሰን	አንድ ዓረፍተ-ነገር ምን እንደሚሰራ ይግለጹ፣ ምን እንደማይሰራ ግልጽ ያድርጉ	“የተጠቃሚ ምዝገባ API ይተግብሩ፣ የኢሜል ማረጋገጫን አያካትትም”
2. ግብዓት/ውጤት ውል	የውሂብ አወቃቀር፣ አይነት፣ የግድ/አማራጭ መስኮች፣ የምሳሌ እሴቶች	`POST /register` የጥያቄ አካል `{email: string, password: string}`፣ ምላሽ `201` ወይም `400` የስህተት ኮድ ይዞ
3. ባህሪ እና ሎጂክ	የንግድ ህጎች፣ የድንበር ሁኔታዎች፣ የሁኔታ ለውጦች	“የይለፍ ቃል ርዝመት 8-20 ቁምፊዎች፣ ቢያንስ አንድ ቁጥር ይይዛል፤ ኢሜል ቀድሞ ካለ `409` ይመልሳል”
4. የስህተት አያያዝ	ሁሉም ሊሆኑ የሚችሉ ያልተለመዱ ሁኔታዎች እና ተጓዳኝ የስህተት ኮድ/መልዕክቶች	“የውሂብ ጎታ ግንኙነት ከተቋረጠ → `503` ይመልሳል፣ የቁልል አሻራ አያሳይም”
5. ተግባራዊ ያልሆኑ መስፈርቶች	አፈጻጸም (የምላሽ ጊዜ < 200ms)፣ ደህንነት (መለኪያ የተደረገ ጥያቄ)፣ ምዝግብ (logging)፣ ታዛቢነት	“ሁሉም 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 እነሱን በመጠቀም የክፍል ሙከራዎችን በቀጥታ ማፍራት ስለሚችል እና ሲጠናቀቅ በራስ-ሰር ማረጋገጥ ይችላል።

ሁለት. Spec የመጻፍ ዋና መርሆዎች (SMART ልዩነት)

መርህ	ማብራሪያ	ተቃራኒ ምሳሌ
ትክክለኛ (Precise)	የተወሰኑ ቁጥሮች፣ አይነቶች፣ ቡሊያን ሁኔታዎችን ይጠቀሙ፣ “በተቻለ መጠን”፣ “በተለምዶ” ከመጠቀም ይቆጠቡ	❌ “የይለፍ ቃል በቂ ደህንነት ያለው መሆን አለበት” → ✅ “የይለፍ ቃል ቢያንስ 8 ቁምፊዎች፣ ትልቅ፣ ትንሽ ፊደል እና ቁጥር ይይዛል”
ሊረጋገጥ የሚችል (Verifiable)	እያንዳንዱ መስፈርት በራስ-ሰር ሙከራ ወይም በእጅ ምርመራ እንደ ማለፍ/አለማለፍ ሊፈረድበት ይችላል	❌ “ኮዱ ውብ መሆን አለበበት” → ✅ “የተግባር ዑደት ውስብስብነት ≤ 10፣ ተደጋጋሚ የኮድ ብሎኮች የሉም”
ያለ አሻሚነት (Unambiguous)	አንድ ቃል በሙሉ ሰነድ ውስጥ ተመሳሳይ ትርጉም አለው፣ አስፈላጊ ከሆነ የቃላት መፍቻ ይስጡ	❌ “ተጠቃሚው ከሌለ ስህተት ይመልሱ” → ✅ “ተጠቃሚው ከሌለ → `404` እና `{code: 'USER_NOT_FOUND'}` ይመልሱ”
ሙሉ (Complete)	ደስተኛ መንገድ፣ ሁሉንም ያልተለመዱ መንገዶች፣ ተግባራዊ ያልሆኑ ፍላጎቶችን ይሸፍኑ	❌ የስኬት ሁኔታን ብቻ ጻፉ → ✅ የውሂብ ጎታ ጊዜ ማባከን፣ ፈቃድ አለማግኘትን ያካትቱ
አቶማዊ (Atomic)	አንድ spec አንድ ተለይቶ ሊደርስ የሚችል የተግባር ነጥብ ብቻ ይገልጻል (AI በአንድ ጊዜ እንዲያጠናቅቅ ያመቻቻል)	❌ አንድ spec “ሙሉ የክፍያ ስርዓት” ይጻፉ → ✅ “የክፍያ ትዕዛዝ መፍጠር”፣ “መልሶ መጥሪያ ፊርማ ማረጋገጥ”፣ “መመለስ” ይባላል

ሶስት. ከ AI ጋር በመተባበር Spec Coding ሂደት

ሰው ስፔክ ይጽፋል (ከላይ ያለው መዋቅር፣ በተለይ የሙከራ ጉዳዮችን እና የተግባር ፊርማዎችን በጥሩ ሁኔታ ይጽፉ)።
ስፔክን በአንድ ጊዜ ለAI ይስጡ (በንግግር መልክ ተጨማሪ ፍላጎቶችን አይጨምሩ፣ የቪቤ ብክለትን ያስወግዱ)።
AI ኮድ + የክፍል ሙከራዎችን ያፈራል (AI በስፔክ ውስጥ በተጠቀሱት የሙከራ ጉዳዮች መሰረት ተፈጻሚ የሆኑ ሙከራዎችን ማፍራት አለበት)።
ሙከራዎችን አሂዱ፡ ሁሉም ካለፉ ወደ ቀጣይ ደረጃ ይሂዱ፤ ካላለፉ ስፔክን ያስተካክሉ ወይም ኮዱን በቀጥታ ያርሙ (በዚህ ጊዜ ትንሽ ዑደት ሊጀምር ይችላል፣ ነገር ግን ለውጦቹን መመዝገብ ያስፈልጋል)።
የሰው ግምገማ፡ ከስፔክ ውጪ የሆነ ተግባር (scope creep) መኖሩን፣ ደህንነት/አፈጻጸምን ያረጋግጡ።
ማስተካከል፡ የስፔክ ሰነዱን እና የመጨረሻውን ኮድ አንድ ላይ ወደ ማከማቻ (repository) ያስገቡ፣ እንደ ቋሚ ሰነድ።

ቁልፍ ልምምድ፡ Spec ኮድ ማድረግ — spec.md + test_spec.py ይጠቀሙ፣ የሙከራ ፋይሉ በቀጥታ ከስፔክ ውስጥ ካሉት ምሳሌዎች የተገኘ ነው፤ በኋላ ኮዱን ሲያስተካክሉ ሙከራውን በማሂድ ስፔኩ መጣሱን ማረጋገጥ ይችላሉ።

አራት. ጥሩ Spec የሚያስገኛቸው ውጤቶች (እንደ ተቀባይነት መስፈርት ሊያገለግሉ ይችላሉ)

ትክክለኛነት፡ ተመሳሳይ ስፔክ ለተለያዩ AI (ወይም ለተለያዩ ሰዎች) ተመሳሳይ አፈጻጸም ያስገኛል።
ሊሞከር የሚችልነት፡ ኮዱ ከተጻፈ በኋላ ወዲያውኑ 90% ትክክለኛነትን በራስ-ሰር ማረጋገጥ ይቻላል።
ሊጠበቅ የሚችልነት፡ ከስድስት ወር በኋላ ማንም ሰው ስፔኩን በማየት የመጀመሪያውን የዲዛይን ዓላማ መረዳት ይችላል።
ዝቅተኛ የመግባቢያ ወጪ፡ ቡድኑ በሚወያይበት ጊዜ ስለ ስፔኩ ብቻ ይወያያል፣ ስለ ኮድ መስመሮች አይወያይም።
ደህንነት/ጥራት አብሮ የተሰራ፡ የደህንነት መስፈርቶች (እንደ መለኪያ የተደረገ ጥያቄ) እና የድንበር ሁኔታዎች በስፔክ ውስጥ ተጽፈዋል፣ AI መከተል ይጠበቅበታል።

አምስት. የጥሩ Spec ምሳሌ (በጣም አጭር ስሪት)

# Spec: የተጠቃሚ ምዝገባ API

## ወሰን
- email, password ይቀበላል
- የማረጋገጫ ኢሜል አይልክም፣ የኢሜል ትክክለኛነት አይፈትሽም

## ውል
POST /register
Content-Type: application/json
Request: { "email": string, "password": string }
Response 201: { "user_id": string }
Response 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Response 409: { "code": "EMAIL_ALREADY_EXISTS" }

## ባህሪ
- email ቢያንስ የRFC 5322 መሰረታዊ ቅርጸትን (a@b.c) ማሟላት አለበት
- password: ርዝመት 8-20፣ ቢያንስ አንድ ቁጥር እና አንድ ትልቅ ፊደል ይይዛል
- bcrypt በመጠቀም ይመሰጠራል፣ የጨው (salt) ወጪ 10
- ወደ ውሂብ ጎታ ከማስገባት በፊት ኢሜል ቀድሞ ካለ → 409

## የሙከራ ጉዳዮች (ግብዓት -> የሚጠበቀው የሁኔታ ኮድ+የምላሽ መስክ)
| ግብዓት email | password | የሚጠበቀው |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id አለ |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (ቀድሞ ያለ ኢሜል) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## ተግባራዊ ያልሆኑ
- SQL መለኪያ የተደረገ ጥያቄን መጠቀም አለበት (መርፌን ለመከላከል)
- ምዝግብ ማስታወሻ የምዝገባ ምንጭ IP ይመዝግባል፣ የይለፍ ቃል አይመዝግብም
- የምላሽ ጊዜ 95% ጥያቄዎች < 100ms (bcrypt ሳይጨምር)

## ጥገኞች
- Python 3.10+, FastAPI, bcrypt, asyncpg

ጥሩ Spec Coding = የሰውን “የዲዛይን ውሳኔ” ወደ ማሽን “የሙከራ ጉዳዮች + የአይነት ፊርማ + የባህሪ ገደቦች” መቀየር ነው፣ AI አፈጻጸሙን ብቻ እንዲሞላ ሲያደርግ፣ ሰው ደግሞ ጥራትን እና አቅጣጫን ይቆጣጠራል።