AI Serye Panayam 16: Ano ang dapat na maging isang magandang spec coding?

Ang isang magandang Spec Coding (spec-driven programming), ang pangunahing layunin ay gawing "eksaktong, mapapatunayan, at maipapatupad na kontrata" ang "malabong ideya". Hindi lamang ito pagsulat ng dokumento, kundi pagtatag ng isang walang kalabuan na wika sa pagitan ng tao at AI (o tao at tao). Sa ibaba, tatalakayin ko ang apat na dimensyon: kaayusan ng nilalaman ng spec, prinsipyo sa pagsulat, proseso ng pakikipagtulungan sa AI, at pagpapatunay ng kalidad, upang maipakita kung ano ang anyo ng isang magandang spec.

I. Pamantayang Istruktura ng Dokumento ng Spec (Halimbawa: Functional Module)

Seksyon	Pangkailangang Nilalaman	Halimbawa
1. Layunin at Saklaw	Isang pangungusap na naglalarawan kung ano ang ginagawa, at malinaw na kung ano ang hindi ginagawa	"Gagawa ng API para sa pagrehistro ng user, hindi kasama ang pagpapatunay ng email"
2. Input/Output na Kontrata	Istruktura ng datos, uri, kinakailangan/hindi kinakailangan na field, halimbawa ng halaga	`POST /register` request body `{email: string, password: string}`, response `201` o `400` na may error code
3. Gawi at Lohika	Mga patakaran sa negosyo, kondisyon ng hangganan, pagbabago ng estado	"Ang haba ng password ay 8-20 na karakter, dapat naglalaman ng kahit isang numero; kung ang email ay mayroon na, magreturn ng `409`"
4. Paghawak ng Error	Lahat ng posibleng sitwasyon ng exception at kaukulang error code/mensahe	"Pagkabigo ng koneksyon sa database → magreturn ng `503`, huwag ilantad ang stack"
5. Hindi-functional na Kinakailangan	Pagganap (oras ng response < 200ms), seguridad (parameterized query), log, observability	"Lahat ng SQL ay dapat gumamit ng precompiled; itala ang `email` ngunit huwag itala ang `password`"
6. Mga Test Case (Mahalaga)	Hindi bababa sa 3 tipikal na input + 2 boundary/exception na input, bigyan ang inaasahang output	Tingnan ang talahanayan sa ibaba
7. Dependencies at Constraints	Anong library, bersyon, environment variable ang gagamitin	"Python 3.10+, FastAPI, environment variable `DB_URL`"

Halimbawa ng Test Case (Inilagay sa spec)

Scenario	Input	Inaasahang Output
Normal na pagrehistro	email: `a@b.com`, pwd: `Pass1234`	`201`, magreturn ng `user_id`
Masyadong maikling password	pwd: `Ab1`	`400`, error code `WEAK_PASSWORD`
Mayroon nang email	Tulad ng email sa itaas	`409`, error code `EMAIL_EXISTS`

Ang magandang Spec ay dapat unang isulat ang test case, dahil ang AI ay maaaring direktang bumuo ng unit test batay dito, at pagkatapos ay awtomatikong patunayan.

II. Pangunahing Prinsipyo sa Pagsulat ng Spec (SMART Variation)

Prinsipyo	Paliwanag	Halimbawa ng Hindi Maganda
Tumpak (Precise)	Gumamit ng tiyak na numero, uri, at boolean na kondisyon; iwasan ang "kahit na", "karaniwan"	❌ "Dapat sapat ang seguridad ng password" → ✅ "Ang password ay dapat hindi bababa sa 8 na karakter, may malaki at maliit na letra, at numero"
Maaaring Patunayan (Verifiable)	Bawat kinakailangan ay dapat na mapatunayan sa pamamagitan ng awtomatikong test o manu-manong inspeksyon kung ito ay pumasa o nabigo	❌ "Dapat elegante ang code" → ✅ "Ang cyclomatic complexity ng function ay ≤ 10, walang duplicate na code block"
Walang Kalabuan (Unambiguous)	Ang parehong termino ay dapat may iisang kahulugan sa kabuuan ng dokumento, magbigay ng glossary kung kinakailangan	❌ "Kung wala ang user, magreturn ng error" → ✅ "Kung wala ang user → magreturn ng `404` at `{code: 'USER_NOT_FOUND'}`"
Kumpleto (Complete)	Sumasaklaw sa happy path, lahat ng exception path, at hindi-functional na kinakailangan	❌ Isinulat lamang ang success scenario → ✅ Kasama ang database timeout, kulang na pahintulot, atbp.
Atomiko (Atomic)	Isang spec lamang ang naglalarawan ng isang maaaring i-deliver nang malaya na feature (upang madali para sa AI na matapos ito nang sabay)	❌ Gumamit ng isang spec para isulat ang "buong sistema ng pagbabayad" → ✅ Hatiin sa "gumawa ng payment order", "callback signature verification", "refund"

III. Proseso ng Spec Coding Kapag Nakikipagtulungan sa AI

Sumulat ng spec ang tao (gamit ang istruktura sa itaas, lalo na ang pagsulat ng test case at function signature).
Ibigay ang spec sa AI nang isang beses (huwag magdagdag ng mga kinakailangan sa paraan ng pag-uusap, iwasan ang vibe contamination).
Mag-output ang AI ng code + unit test (Dapat sundin ng AI ang test case sa spec para gumawa ng executable na test).
Patakbuhin ang test: Kung lahat ay pumasa, pumunta sa susunod na hakbang; kung hindi, baguhin ang spec o direktang itama ang code (maaaring pumasok sa maliit na loop ngunit dapat itala ang mga pagbabago).
Manual review: Suriin kung may nadagdag na functionality sa labas ng spec (scope creep), suriin ang seguridad/performance.
Permanenteng dokumentasyon: Isumite ang spec document at huling code sa repository bilang permanenteng dokumento.

Mahalagang kasanayan: I-code ang spec — gamitin ang spec.md + test_spec.py, kung saan ang test file ay direktang galing sa halimbawa sa spec, upang sa susunod na pagbabago ng code ay patakbuhin lamang ang test para mapatunayan kung nasira ang spec.

IV. Epekto ng Magandang Spec (Maaaring Gamitin bilang Acceptance Criteria)

Katiyakan: Ang parehong spec na ibinigay sa iba't ibang AI (o iba't ibang tao) ay makagagawa ng magkatulad na implementasyon.
Kakayahang Subukan: Pagkatapos isulat ang code, agad na maaaring awtomatikong patunayan ang 90% ng kawastuhan.
Kakayahang Mapanatili: Kahit makalipas ang kalahating taon, sinumang titingin sa spec ay maiintindihan ang orihinal na intensyon ng disenyo.
Mababang Gastos sa Komunikasyon: Sa talakayan ng koponan, spec lamang ang pag-uusapan, hindi ang partikular na linya ng code.
Nakalakip ang Seguridad/Kalidad: Ang mga kinakailangan sa seguridad (tulad ng parameterized query) at boundary condition ay nakasulat sa spec, at dapat sundin ng AI.

V. Halimbawa ng Magandang Spec (Napakasimpleng Bersyon)

# Spec: User Registration API

## Saklaw
- Tumatanggap ng email, password
- Hindi nagpapadala ng verification email, hindi tinitingnan ang authenticity ng email

## Kontrata
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" }

## Gawi
- Ang email ay dapat sumunod sa pangunahing format ng RFC 5322 (a@b.c)
- password: haba 8-20, dapat naglalaman ng kahit isang numero at isang malaking letra
- Gumamit ng bcrypt para sa encryption storage, salt cost 10
- Kung bago i-save sa database ay natuklasang mayroon nang email → 409

## Test Case (input -> inaasahang status code + response field)
| Input email | password | Inaasahan |
|------------|----------|------|
| test@x.com | Pass1234  | 201, may user_id |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (mayroon nang email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Non-functional
- Ang SQL ay dapat gumamit ng parameterized query (anti-injection)
- I-log ang IP address ng registration, huwag i-log ang password
- Oras ng response: 95% na request < 100ms (hindi kasama ang bcrypt)

## Dependencies
- Python 3.10+, FastAPI, bcrypt, asyncpg

Ang magandang Spec Coding = isulat ang "desisyon sa disenyo" ng tao bilang "test case + type signature + behavior constraint" ng makina, upang ang AI ay responsable lamang sa pagpuno ng implementasyon, habang ang tao ay palaging kumokontrol sa kalidad at direksyon.