AI Series Interview 16: Unsa ang maayong spec coding?

Ang maayong Spec Coding (spec-driven programming) mao ang paghimog 'libog nga ideya' nga mahimong 'tukma, mapamatud-an, ug mapatuman nga kontrata'. Dili lang kini dokumento, kondili usa ka walay kalibog nga pinulongan sa komunikasyon tali sa tawo ug AI (o tawo ug tawo). Sa ubos, akong i-detalye ang estruktura sa sulod, prinsipyo sa pagsulat, proseso sa kolaborasyon sa AI, ug pag-validate sa kalidad aron mahatagan kag maayong spec.

1. Standard Structures sa Spec Document (Pananglitan: Feature Module)

Sekyon	Gikinahanglan nga Nilalaman	Pananglitan
1. Tumong ug Sakop	1 sentence unsay buhaton, klarohon ang dili buhaton	'Ipatuman ang API sa pagrehistro sa user, dili apil ang email verification'
2. Input/Output nga Kontrata	Data structure, type, required/optional fields, sample values	`POST /register` request body `{email: string, password: string}`, response `201` or `400` nga adunay error code
3. Gawi ug Lohika	Business rules, boundary conditions, state transitions	'Password length 8-20, kinahanglan adunay labing menos usa ka numero; kung ang email nag-eksist na, ibalik ang `409`'
4. Pag-atubang sa sayop	Tanang posibling exception scenarios ug katugbang nga error code/message	'Database connection naputol → ibalik `503`, ayaw i-expose ang stack trace'
5. Non-functional nga mga Kinahanglanon	Performance (response time < 200ms), security (parameterized queries), logging, observability	'Tanang SQL kinahanglan mogamit ug pre-compiled; i-log ang `email` pero dili ang `password`'
6. Test Cases (Importante)	Labing menos 3 typical input + 2 boundary/exception input, ihatag ang expected output	Tan-awa ang lamesa sa ubos
7. Dependencies ug Constraints	Unsa nga library, version, environment variables	'Python 3.10+, FastAPI, environment variable `DB_URL`'

Test Cases Pananglitan (I-embed sa spec)

Scenario	Input	Expected Output
Normal nga pagrehistro	email: `a@b.com`, pwd: `Pass1234`	`201`, ibalik `user_id`
Mubo kaayo ang password	pwd: `Ab1`	`400`, error code `WEAK_PASSWORD`
Nag-eksist nga email	parehas nga email sa taas	`409`, error code `EMAIL_EXISTS`

Ang maayong Spec kinahanglan mosulat una og test cases, kay ang AI magamit kini sa direktang paghimo og unit tests, dayon awtomatikong i-validate.

2. Pangunang mga Prinsipyo sa Pagsulat og Spec (SMART nga variant)

Prinsipyo	Pagpasabot	Dili maayong pananglitan
Tukma (Precise)	Gamit ang piho nga numero, type, boolean condition; likayi ang 'kutob sa mahimo', 'kasagaran'	❌ 'Ang password kinahanglan igo nga luwas' → ✅ 'Ang password labing menos 8 ka karakter, adunay uppercase, lowercase, numero'
Mamatuod (Verifiable)	Ang matag kinahanglanon mahimong mahukman pinaagi sa automated test o manual check kung pasado o napakyas	❌ 'Ang code kinahanglan elegante' → ✅ 'Ang function cyclomatic complexity ≤ 10, walay duplicate code blocks'
Walay Kalibog (Unambiguous)	Ang parehas nga termino adunay makanunayon nga kahulugan sa tibuok dokumento; kung gikinahanglan, i-glossary	❌ 'Kung wala ang user, ibalik ang error' → ✅ 'User wala → ibalik `404` ug `{code: 'USER_NOT_FOUND'}`'
Kompleto (Complete)	Nagtabon sa happy path, tanang exception path, ug non-functional requirements	❌ Gisulat lang ang success scenario → ✅ Naglakip sa database timeout, kulang nga permiso, ug uban pa
Atomic (Atomic)	Usa ka spec naghulagway lang sa usa ka independenteng ihatag nga feature (para sayon sa AI usa ka buhat)	❌ Gamit ang usa ka spec para sa 'entire payment system' → ✅ Bahina ngadto sa 'generate payment order', 'callback verification', 'refund'

3. Proseso sa Spec Coding Kung Magtinabangay sa AI

Tawo mosulat og spec (sa estruktura sa ibabaw, ilabi na ang test cases ug function signature).
I-feed ang spec sa AI sa usa ka higayon (ayaw pagdugang og requirements pinaagi sa dialogue aron malikayan ang vibe contamination).
AI mogawas og code + unit tests (ang AI kinahanglan mosunod sa test cases sa spec aron makagama og ma-execute nga tests).
Padagana ang tests: Kung puros passed, adto sa sunod nga lakang; kung dili, i-edit ang spec o direkta nga i-correct ang code (niadto nga punto, mahimo nga moadto sa gamay nga loop, pero irekord ang mga kausaban).
Human review: Susiha kung adunay mga feature nga wala sa spec (scope creep), susiha ang seguridad/performance.
I-fix: I-submit ang spec document ug final code ngadto sa repository isip permanenteng dokumento.

Mahinungdanong praktis: I-code ang spec — gamit ang spec.md + test_spec.py, diin ang test file direktang gikan sa mga examples sa spec, aron sa pag-usab sa code sa ulahi, padagan lang ang tests aron ma-validate kung nadaot ba ang spec.

4. Epekto sa Maayong Spec (Mahimong Acceptance Criteria)

Kasigurohan: Ang parehas nga spec maghatag ug susamang implementasyon bisag lain-laing AI (o lain-laing tawo).
Ma-test: Human masulat ang code, dayon nga ma-autovalidate ang 90% sa correctness.
Ma-maintain: Human unom ka bulan, bisan kinsa makakita sa spec, makasabot sa orihinal nga design intention.
Ubos nga gasto sa komunikasyon: Sa diskusyon sa team, ang spec lang ang hisgotan, dili ang piho nga code lines.
Seguridad/kalidad nga na-embed: Ang security requirements (sama sa parameterized queries) ug boundary conditions gi-encode sa spec, AI kinahanglan motuman.

5. Pananglitan sa Maayong Spec (Simplified Version)

# Spec: User Registration API

## Sakop
- Makadawat og email, password
- Dili magpadala og verification email, dili mag-check sa email authenticity

## 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 kinahanglan mosunod sa RFC 5322 basic format (a@b.c)
- password: length 8-20, labing menos usa ka numero ug usa ka uppercase
- Gamit ang bcrypt encryption sa pagtipig, salt cost 10
- Kung sa wala pa i-save sa database nakit-an nga nag-eksist ang email → 409

## Test Cases (input -> expected status code + response field)
| Input email | password | Expected |
|-------------|----------|----------|
| test@x.com | Pass1234  | 201, adunay user_id |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (nag-eksist nga email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Non-functional
- SQL kinahanglan mogamit ug parameterized queries (kontra sa injection)
- I-log ang source IP sa pagrehistro, dili i-log ang password
- Response time 95% sa requests < 100ms (walay bcrypt)

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

Ang maayong Spec Coding = himoong 'design decisions' sa tawo nga mahimong 'test cases + type signatures + behavioral constraints' sa makina, aron ang AI maoy mag-fill sa implementasyon, samtang ang tawo magpabilin nga nagkontrol sa kalidad ug direksyon.