कागजात, README र कोड टिप्पणीहरू

लाभ:

• AI सँग लक्षित दर्शक र स्रोतमा आधारित README, docstring र changelog ड्राफ्टहरू उत्पादन गर्ने क्षमता
• कागजातमा 'के/कसरी' र 'किन' तहहरू छुट्याउन र मानवको रूपमा 'किन' थप्न सक्ने क्षमता
• स्थापना चरणहरूलाई व्यक्तिगत रूपमा चलाएर र कागजातलाई कोड परिवर्तनको अंश बनाएर प्रमाणित गर्दै

सफ्टवेयरको प्रायः उपेक्षित तर सबैभन्दा लामो समयसम्म चल्ने भाग कागजात हो। कोड महिना पछि पनि पढ्न योग्य छ; लेख्ने मान्छे बिर्सियो, प्रसङ्ग बिर्सियो र जे लेखियो त्यही रह्यो। राम्रो README (परिचयात्मक कागजात जसले परियोजना के हो र यसलाई कसरी स्थापना गर्ने र कसरी चलाउने भनेर बताउँछ), व्याख्यात्मक कोड टिप्पणीहरू र अप-टु-डेट एपीआई कागजातहरू (इन्टरफेस कसरी प्रयोग गर्ने भनेर व्याख्या गर्ने सन्दर्भ) ले टोलीको गति सीधै निर्धारण गर्दछ। AI ले कागजातबाट धेरै "लेखन थकान" लिन्छ - तर यो एउटा जालको साथ आउँछ: AI ले कोडबाट अनुमान लगाउन सक्छ कि यसले के गर्छ, तर प्राय: किन यो यस तरिकाले गरिन्छ भनेर थाहा हुँदैन।

यस एकाईमा, तपाईंले README, कोड टिप्पणी, docstring (प्रति कार्य/वर्ग लेखिएको टिप्पणी ब्लक), API कागजात र AI सँग चेन्जलग कसरी उत्पादन गर्ने सिक्नुहुनेछ; र कसरी मानवीय रूपमा कागजातको सबैभन्दा मूल्यवान भाग सुरक्षित गर्ने: "किन।"

"के" र "किन" बीचको भिन्नता

कागजातका दुई तहहरू छन्। पहिलो के/कसरी: "यस प्रकार्यले सूची क्रमबद्ध गर्दछ", "स्थापना गर्न यो आदेश चलाउनुहोस्"। यी कोड र संरचनाबाट निकाल्न सकिन्छ; AI यहाँ उत्कृष्ट छ। दोस्रो, किन: "हामीले यो सेवालाई सिंक्रोनसको सट्टा एसिन्क्रोनस किन बनायौं", "किन यो सीमा मान 30 सेकेन्ड हो", "हामीले यो पुस्तकालयलाई अर्कोमा किन रोज्यौं"। यी कोडमा लेखिएका छैनन्; यो डिजाइन निर्णयहरू, अवरोधहरू, र विगतको पीडाको उत्पादन हो।

AI लाई "किन" थाहा छैन; सबै भन्दा राम्रो, यसले एक उचित अनुमान बनाउँछ - जुन खतरनाक छ, किनभने गलत कारण कुनै कारण भन्दा खराब छ। त्यसैले श्रमको विभाजन स्पष्ट छ: एआईले "के/कसरी" को मस्यौदा बनाउँछ, तपाईंले "किन" थप्नुहुन्छ। सबैभन्दा मूल्यवान टिप्पणी भनेको कोडले भन्न नसक्ने कुरा हो।

सुझाव: कोड आफैंले स्पष्ट रूपमा के भन्छ टिप्पणीको साथ दोहोर्याउनुहोस् (जस्तै i = i + 1 // i वृद्धि गर्नुहोस्)। AI ले कहिलेकाहीं यस्ता अनावश्यक टिप्पणीहरू उत्पादन गर्छ; तिनीहरूलाई हटाउनुहोस् र "किन" टिप्पणीहरूमा आफ्नो ऊर्जा समर्पित गर्नुहोस्।

स्टेप बाइ स्टेप: एआईसँग दस्तावेजीकरण जेनेरेसन

1. लक्षित दर्शकहरू निर्दिष्ट गर्नुहोस्। "एक विकासकर्ता भर्खरै सुरु हुँदैछ," "यो API प्रयोग गर्ने बाह्य टोली," "भविष्य म" — दर्शकहरूले भाषा र गहिराइको लागि टोन सेट गर्दछ।
2. स्रोत दिनुहोस्। प्रम्प्टमा सान्दर्भिक कोड, अवस्थित README, उदाहरण प्रयोग थप्नुहोस्। एक असुरक्षित कागजात बनावट को निमन्त्रणा हो।
3. लागू गर्ने संरचना। README को लागि मानक खण्डहरू (उद्देश्य, स्थापना, उपयोग, कन्फिगरेसन, योगदान), docstring को लागी परियोजना ढाँचा।
4. "किन" खाली ठाउँहरू चिन्ह लगाउनुहोस्। AI लाई "यहाँ 'किन' नोट आवश्यक छ" भनेर तर्क थाहा नभएका निर्णयहरू चिन्ह लगाउन सोध्नुहोस्; त्यसपछि ती खाली ठाउँहरू भर्नुहोस्।
5. प्रमाणित गर्नुहोस्। वास्तवमा स्थापना चरणहरू चलाउनुहोस्; नमूना कोड प्रयास गर्नुहोस्। काम नगर्ने README कुनै README भन्दा खराब छ।

तीन मिनी केसहरू

केस १ — README ले अनबोर्डिङलाई गति दियो। खुला स्रोत उपकरणको README हराइरहेको थियो; नयाँ योगदानकर्ताहरूले औसत 2 घण्टाको लागि स्थापनाको साथ संघर्ष गरे। टोलीले AI लाई स्थापना स्क्रिप्ट र package.json दिए र एक संरचित README को मस्यौदा तयार गर्यो, त्यसपछि सफा मेसिनमा स्टेपहरू चलायो र दुई हराइरहेको निर्भरताहरू थप्यो। पछिका योगदानकर्ताहरूको लागि स्थापना समय 25 मिनेटको औसतमा घट्यो।

केस २ - बनाइएको "किन" जाल। एक विकासकर्ताले AI लाई टाइमआउट मान (टाइमआउट = 30) को छेउमा टिप्पणीको लागि सोध्यो। AI ले एक उचित तर गलत औचित्य "उच्च नेटवर्क विलम्बता सहन" लेख्यो; वास्तविक कारण एक डाउनस्ट्रीम सेवाको अनुबंधात्मक 30-सेकेन्ड सीमा थियो। गलत व्याख्याले पछिको विकासकर्तालाई अनावश्यक रूपमा मूल्य बढाउनको लागि नेतृत्व गर्‍यो, जसले घटना निम्त्याउँछ। पाठ: कोड मालिकले औचित्य प्रमाणित गर्नुपर्छ।

केस 3 - Docstring मानक स्वचालित भएको छ। 40 प्रकार्यहरू भएको सहायक मोड्युलमा कुनै कागजातहरू थिएनन्। AI लाई परियोजना ढाँचा (Google शैली) दिइएको थियो र प्रत्येक प्रकार्यको लागि प्यारामिटर, फिर्ता र अपवाद विवरणहरू उत्पादन गरियो; विकासकर्ताले यी समीक्षा गर्नुभयो र केही गलत प्रकारका घोषणाहरू फिक्स गर्नुभयो। डकुमेन्टिङ 40 प्रकार्यहरू लगभग आधा दिनबाट एक घण्टामा घट्यो।

चार प्रतिलिपि गर्न मिल्ने टेम्प्लेटहरू

संरचित README मस्यौदा:

लक्षित दर्शक: {{जस्तै नयाँ योगदानकर्ता}} तलका फाइलहरूमा आधारित README ड्राफ्ट लेख्नुहोस्। खण्डहरू: उद्देश्य, सुविधाहरू, आवश्यकताहरू, स्थापना, सञ्चालन, कन्फिगरेसन, परीक्षण, योगदान। वास्तविक फाइलहरूबाट स्थापना / चलिरहेको आदेशहरू निकाल्नुहोस्; फिटिङ। तपाईं निश्चित नभएका ठाउँहरूलाई "[VERIFY]" द्वारा चिन्ह लगाउनुहोस्। स्रोत: {{package.json/scripts/sample code}}

Docstring/API सन्दर्भ:

{{project style: Google/NumPy/JSDoc}} ढाँचामा यी प्रकार्यहरूमा docstring लेख्नुहोस्: छोटो सारांश, प्यारामिटरहरू (प्रकार + अर्थ), फिर्ता, अपवादहरू फ्याँकिएको, 1 छोटो उदाहरण। कोडले स्पष्ट रूपमा भनेको कुरा दोहोर्याउनुहोस्। "किन" आवश्यक पर्ने डिजाइन निर्णयहरूलाई "[किन आवश्यक]" को रूपमा चिन्ह लगाउनुहोस्, बनावटी औचित्य नलेख्नुहोस्।{{code}}

"किन" टिप्पणीको लागि खाली ठाउँहरू हटाउनुहोस्:

यस कोडमा, अर्को विकासकर्ताले सोध्न सक्छ "किन यस्तो छ?" (जादू संख्या, असामान्य निर्णय, workarounds)। प्रत्येकको लागि SKELETON टिप्पणी दिनुहोस्, तर तर्कलाई खाली छोड्नुहोस्; म औचित्य भर्नेछु।{{code}}

Changelog/PR कथन:

तलको भिन्नताबाट {{changelog entry / PR description}} लेख्नुहोस्। ढाँचा: के परिवर्तन भयो (प्रयोगकर्ताको भाषामा), किन (समस्या: {{...}}), ब्रेकिङ परिवर्तन (यदि छ भने), के यो परीक्षण गरिएको छ। लक्षित दर्शकहरूमा प्राविधिक शब्दावली समायोजन गर्नुहोस्।{{diff}}

कमजोर प्रम्प्ट / बलियो प्रम्प्ट

कमजोर: "यस परियोजनाको लागि README लेख्नुहोस्।"

बलियो: "लक्ष्य दर्शक: पहिलो पटक यो रेपो क्लोन गर्ने विकासकर्ता। संलग्न प्याकेज.json, docker-compose.yml र स्क्रिप्ट्स/ फोल्डरमा आधारित, उद्देश्य, आवश्यकताहरू, स्थापना, सञ्चालन, परीक्षण, योगदान खण्डहरू सहितको मस्यौदा README लेख्नुहोस्। यी फाइलहरूबाट आदेशहरू निकाल्नुहोस्, तपाईंले कुनै पनि फाइलहरूसँग चिन्ह लगाउनुहुन्न भन्ने निश्चित गर्नुहोस्; [प्रमाणित]।"

बलियो संस्करणले दर्शकहरूलाई, स्रोत, संरचना, र "यसलाई बनाउनुहोस्, चिन्ह लगाउनुहोस्" नियम दिन्छ; ताकि कागजात वास्तविक फाइलहरूमा आधारित छ र स्थानहरू प्रमाणित गर्न स्पष्ट रूपमा देखिने छन्।

कागजात प्रकार

AI ले राम्रो गर्छ

मानव थप्छ/प्रमाणित गर्दछ

README स्थापना

चरण रूपरेखा

चरणहरू चलाउनुहोस् र पुष्टि गर्नुहोस्

Docstring/API

संरचना, मापदण्ड, प्रकार

सही प्रकार र "किन"

कोड टिप्पणी

"उहाँ के गर्दै हुनुहुन्छ" सारांश

"यो किन" औचित्य

Changelog/PR

पहिलो मस्यौदा

प्रभाव र शुद्धता

वास्तु निर्णय (ADR)

कंकाल

वास्तविक निर्णय र सम्झौताहरू

कागजात मर्मत आवश्यक छ

कागजातको सबैभन्दा खतरनाक पक्ष त्यो हो जब यो गलत भएता पनि सत्य देखिन्छ। जब कोड परिवर्तन हुन्छ र कागजात अद्यावधिक हुँदैन, यसले सक्रिय रूपमा पाठकलाई बहकाउँछ। AI ले अपडेट गर्न सजिलो बनाउँछ: एउटा भिन्नता जारी गर्नुहोस् र सोध्नुहोस् "कागजातका कुन भागहरूलाई यो परिवर्तनले असर गर्छ?" तपाईले सोध्न सक्नुहुन्छ। तर यो प्रक्रिया हो जसले अप-टु-डेटनेस सुनिश्चित गर्दछ — कागजात अपडेटलाई कोड परिवर्तनको अंश बनाउनुहोस् (PR को स्वीकृति मापदण्ड)। एआई गति; टोलीले अनुशासन निर्माण गर्छ।

सावधानी: README मा स्थापना चरणहरू प्रमाणित नगरी प्रकाशित नगर्नुहोस्। एउटा "सम्भवतः काम" कागजातले नयाँ विकासकर्ताको पहिलो दिनलाई बर्बाद गर्न सक्छ र विश्वासलाई कम गर्न सक्छ। सफा वातावरणमा पाइलाहरू आफैं चलाउनुहोस्।

सामान्य गल्तीहरू

• AI मा फिट हुनको लागि "किन" प्राप्त गर्दै। झूटो औचित्य कुनै औचित्य भन्दा खराब छ; कोड मालिकले डिजाइनको कारण लेख्नुपर्छ।
• स्थापना चरणहरू प्रमाणीकरण गर्दैन। README जसले काम गर्दैन विश्वासलाई नष्ट गर्दछ।
• कोड दोहोर्याउँदै अनावश्यक टिप्पणी। यसले आवाज उत्पन्न गर्छ, वास्तविक "किन" व्याख्याहरूलाई अस्पष्ट पार्छ।
• लक्षित दर्शकहरू निर्दिष्ट गर्दैन। एउटा कागजात जुन अस्पष्ट छ कि यो कसलाई लेखिएको हो कि त नौसिखिया वा विशेषज्ञ को लागी कुनै कामको छैन।
• प्रक्रियाबाट अद्यावधिक अलग गर्दै। यदि कागजात कोडको साथ अद्यावधिक गरिएको छैन भने यो चाँडै भ्रामक हुन्छ।

संक्षेपमा

AI ले कागजातबाट धेरै मेकानिकल बोझ लिन्छ: द्रुत ड्राफ्टहरू README, docstring, API सन्दर्भ, changelog र PR विवरणहरू। तर यसले "किन" जान्न सक्दैन, जुन सबैभन्दा मूल्यवान तह हो, र यसलाई बनाउन खतरनाक छ। श्रमको विभाजन स्पष्ट छ: एआईले "के/कसरी" उत्पादन गर्छ, तपाईंले "किन" थप्नुहुन्छ। दर्शकहरू निर्दिष्ट गर्नुहोस्, स्रोतहरू प्रदान गर्नुहोस्, संरचना लागू गर्नुहोस्, फिट हुनका लागि ठाउँहरू चिन्ह लगाउनुहोस्, र यसलाई आफैं चलाएर प्रत्येक स्थापना चरण प्रमाणित गर्नुहोस्। कागजातलाई कोड परिवर्तनको अभिन्न अंग बनाउनुहोस्।

आवेदन कार्य

एउटा मोड्युल वा सानो परियोजना छान्नुहोस् जसको कागजात हराइरहेको वा पुरानो छ। पहिले AI बाट "संरचित README ड्राफ्ट" (वा docstring) टेम्प्लेटको साथ रूपरेखा उत्पन्न गर्नुहोस्; स्रोत र लक्षित दर्शक दिन निश्चित हुनुहोस्। त्यसपछि प्रत्येक बिन्दुमा जानुहोस् जहाँ AI ले चिन्ह लगाएको छ [verify] वा [किन आवश्यक छ]: वास्तवमा सेटअप चरणहरू चलाउनुहोस् र तपाईंको आफ्नै ज्ञानको साथ डिजाइन "किन" भर्नुहोस्। ध्यान दिनुहोस् कि कति चरणहरू निश्चित गर्न आवश्यक छ र कतिवटा "किन" तपाईंले थप्नुभयो।

चेकलिस्ट

• [] कागजातमा, म "के/कसरी" र "किन" तहहरू छुट्याउँछु।
• [ ] म AI लाई "किन" मेक अप गर्दिन, म आफैं थप्छु।
• [ ] म प्रम्प्टलाई लक्षित दर्शकहरू र वास्तविक स्रोत फाइलहरू दिन्छु।
• [ ] म AI द्वारा चिन्हित [VERIFY] बिन्दुहरूलाई व्यक्तिगत रूपमा कार्यान्वयन गरेर प्रमाणित गर्छु।
• [ ] म कोड दोहोर्याउने अनावश्यक टिप्पणीहरू हटाउँछु।
• [ ] म कोड परिवर्तनको कागजात अद्यावधिक अंश बनाउँदैछु।