AI தொடர் நேர்காணல் 16: ஒரு நல்ல spec coding எப்படி இருக்க வேண்டும்?

ஒரு நல்ல Spec Coding (விவரக்குறிப்பு சார்ந்த நிரலாக்கம்) இன் மையம், "தெளிவற்ற எண்ணங்களை" "துல்லியமான, சரிபார்க்கக்கூடிய, செயல்படுத்தக்கூடிய ஒப்பந்தங்களாக" மாற்றுவதாகும். இது ஒரு ஆவணத்தை எழுதுவது மட்டுமல்ல, மனிதர்களுக்கும் AI க்கும் (அல்லது மனிதர்களுக்கும் மனிதர்களுக்கும்) இடையேயான தெளிவின்மை இல்லா தகவல்தொடர்பு மொழியை உருவாக்குவதாகும். கீழே நான் விவரக்குறிப்பின் உள்ளடக்க அமைப்பு, எழுதும் கொள்கைகள், AI உடன் இணைந்து செயல்படும் செயல்முறை, தர சரிபார்ப்பு ஆகிய நான்கு பரிமாணங்களில் ஒரு நல்ல spec எப்படி இருக்க வேண்டும் என்பதை விளக்குகிறேன்.

一、规格文档的标准结构（以功能模块为例）

测试用例示例（内嵌在 spec 中）

好的 Spec 必须先写测试用例，因为 AI 可以根据它们直接生成单元测试，完成后自动验证。

二、编写 Spec 的核心原则（SMART 变体）

三、与 AI 协作时的 Spec Coding 流程

1. மனிதர் spec எழுதுகிறார் (மேலே உள்ள அமைப்பு, குறிப்பாக சோதனை வழக்குகள் மற்றும் செயல்பாட்டு கையொப்பங்களை நன்கு எழுதவும்).
2. spec ஐ AI க்கு ஒரே முறையில் வழங்கவும் (உரையாடல் முறையில் கூடுதல் தேவைகளைச் சேர்க்க வேண்டாம், vibe மாசுபாட்டைத் தவிர்க்க).
3. AI குறியீடு + அலகு சோதனைகளை வெளியிடுகிறது (AI spec இல் உள்ள சோதனை வழக்குகளைப் பயன்படுத்தி செயல்படுத்தக்கூடிய சோதனைகளை உருவாக்க வேண்டும்).
4. சோதனைகளை இயக்கவும்: அனைத்தும் தேர்ச்சி பெற்றால், அடுத்த கட்டத்திற்குச் செல்லவும்; தேர்ச்சி பெறவில்லை என்றால், spec ஐ மாற்றவும் அல்லது நேரடியாக குறியீட்டை சரிசெய்யவும் (இங்கு சிறிய சுழற்சியில் நுழையலாம், ஆனால் மாற்றங்களைப் பதிவு செய்யவும்).
5. மனித ஆய்வு: spec க்கு வெளியே உள்ள செயல்பாடுகள் சேர்க்கப்பட்டுள்ளதா (scope creep) என சரிபார்க்கவும், பாதுகாப்பு/செயல்திறனைச் சரிபார்க்கவும்.
6. நிரந்தரமாக்குதல்: spec ஆவணத்தையும் இறுதி குறியீட்டையும் களஞ்சியத்தில் ஒன்றாக சமர்ப்பிக்கவும், நிரந்தர ஆவணமாக வைக்கவும்.

முக்கிய நடைமுறை: Spec குறியீடாக்கம் — spec.md + test_spec.py பயன்படுத்தவும், இதில் சோதனை கோப்பு நேரடியாக spec இலிருந்து எடுக்கப்பட்ட எடுத்துக்காட்டுகளைக் கொண்டிருக்கும், பின்னர் குறியீட்டை மாற்றும் போது சோதனைகளை இயக்கி spec மீறப்பட்டதா என சரிபார்க்கலாம்.

四、好的 Spec 带来的效果（可作为验收标准）

• நிச்சயமான தன்மை: ஒரே spec வெவ்வேறு AI களுக்கு (அல்லது வெவ்வேறு நபர்களுக்கு) கொடுக்கப்பட்டால், ஒத்த செயலாக்கங்களை உருவாக்கும்.
• சோதனைத்திறன்: குறியீடு எழுதியவுடன் 90% சரியான தன்மையை தானாக சரிபார்க்க முடியும்.
• பராமரிப்புத் திறன்: ஆறு மாதங்களுக்குப் பிறகு எவரும் spec ஐப் பார்த்தால், ஆரம்ப வடிவமைப்பின் நோக்கத்தைப் புரிந்து கொள்ள முடியும்.
• குறைந்த தகவல் செலவு: குழு விவாதங்களில் spec பற்றி மட்டுமே விவாதிக்கவும், குறிப்பிட்ட குறியீட்டு வரிகளைப் பற்றி அல்ல.
• பாதுகாப்பு/தரம் உள்நிலையில்: பாதுகாப்புத் தேவைகள் (அளவுருவாக்கப்பட்ட வினவல் போன்றவை) மற்றும் எல்லை நிபந்தனைகள் spec இல் எழுதப்பட்டுள்ளன, 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 மூலம் குறியாக்கம் செய்து சேமிக்கவும், உப்பு செலவு 10
- தரவுத்தளத்தில் சேமிப்பதற்கு முன் email ஏற்கனவே இருந்தால் → 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 只负责填充实现，而人始终掌控质量与方向。