ሰነድ፣ README እና ኮድ አስተያየቶች

ትርፍ፡

• በዒላማ ታዳሚዎች እና በ AI ምንጭ ላይ በመመስረት README ፣ docstring እና changelog ረቂቆችን የማምረት ችሎታ
• በሰነድ ውስጥ ያሉትን 'ምን/እንዴት' እና 'ለምን' ያሉትን ንብርብሮች የመለየት እና እንደ ሰው 'ለምን' የሚለውን የመጨመር ችሎታ
• እነሱን በግል በማስኬድ እና ሰነዱን የኮዱ ለውጥ አካል በማድረግ የመጫኛ ደረጃዎችን ማረጋገጥ

በጣም በተደጋጋሚ ችላ የተባለ ነገር ግን ለረጅም ጊዜ የሚቆይ የሶፍትዌር ክፍል ሰነድ ነው። ኮዱ ከወራት በኋላ እንኳን ሊነበብ ይችላል; የጻፈው ሰው ጠፋ፣ ዐውደ ጽሑፉ ተረሳ፣ የተጻፈውም ብቻ ይቀራል። ጥሩ README (ፕሮጀክት ምን እንደሆነ እና እንዴት እንደሚጫን እና እንደሚያስኬድ የሚያብራራ የመግቢያ ሰነድ)፣ የማብራሪያ ኮድ አስተያየቶች እና ወቅታዊ የኤፒአይ ሰነዶች (በይነገጽ እንዴት እንደሚጠቀሙ የሚያብራራ ማጣቀሻ) የቡድኑን ፍጥነት በቀጥታ ይወስናል። AI ብዙ “የመፃፍ ድካም”ን ከሰነድ ያወጣል - ግን ወጥመድ ይዞ ይመጣል፡ AI የሚሰራውን ከኮድ መረዳት ይችላል፣ ነገር ግን ለምን በዚህ መንገድ እንደተደረገ ብዙ ጊዜ ማወቅ አይችልም።

በዚህ ክፍል ውስጥ፣ README፣ code comment፣ docstring (የአስተያየት እገዳ በአንድ ተግባር/ክፍል የተፃፈ)፣ የኤፒአይ ሰነድ እና የለውጥ ሎግ ከ AI ጋር እንዴት እንደሚሰራ ይማራሉ። እና በጣም ጠቃሚ የሆነውን የሰነድ ክፍል እንዴት በሰው ልጅ መጠበቅ እንደሚቻል፡ “ለምን”።

በ "ምን" እና "ለምን" መካከል ያለው ልዩነት

ሁለት የሰነድ ንብርብሮች አሉ. የመጀመሪያው ምን/እንዴት ነው፡- “ይህ ተግባር ዝርዝርን ያዘጋጃል”፣ “ይህንን ትዕዛዝ ለመጫን” ያሂዱ። እነዚህ ከኮዱ እና መዋቅር ሊወጡ ይችላሉ; AI እዚህ የላቀ ነው። በሁለተኛ ደረጃ፣ ለምንድነው፡- “ይህን አገልግሎት ከተመሳሰለው ይልቅ ለምን አልተመሳሰለም”፣ “ለምን ይህ ገደብ ዋጋ 30 ሰከንድ ነው”፣ “ይህን ቤተ-መጽሐፍት ከሌላው ለምን መረጥነው”። እነዚህ በኮዱ ውስጥ አልተጻፉም; የንድፍ ውሳኔዎች, ገደቦች እና ያለፈ ህመም ውጤት ነው.

AI "ለምን" አያውቅም; በጥሩ ሁኔታ, ምክንያታዊ ግምትን ያቀርባል-ይህም አደገኛ ነው, ምክንያቱም የተሳሳተ ምክንያት ከምንም ምክንያት የከፋ ነው. ስለዚህ የሥራ ክፍፍሉ ግልጽ ነው፡ AI “ምን/እንዴት” የሚለውን ረቂቅ ያዘጋጃል፣ “ለምን” የሚለውን ይጨምራሉ። በጣም ጠቃሚው አስተያየት ኮዱ ሊናገር የማይችለውን የሚናገር ነው.

ጠቃሚ ምክር፡ ኮዱ ራሱ በግልፅ የሚናገረውን በአስተያየት አይደግሙ (እንደ i = i + 1 // i ጨምር)። AI አንዳንድ ጊዜ እንደዚህ ያሉ ተደጋጋሚ አስተያየቶችን ይፈጥራል; አስወግዷቸው እና ጉልበትህን "ለምን" አስተያየቶች ላይ አውጣ።

ደረጃ በደረጃ፡ የሰነድ ማመንጨት ከ AI ጋር

1. የታለመውን ታዳሚ ይግለጹ። “አንድ ገንቢ ገና እየጀመረ፣” “ይህን ኤፒአይ የሚጠቀመው የውጪ ቡድን”፣ “የወደፊቱ እኔ” - ተመልካቾች የቋንቋ እና የጥልቀት ቃና ያዘጋጃሉ።
2. ምንጩን ስጡ። ተገቢውን ኮድ፣ ያለውን README፣ ለምሳሌ አጠቃቀምን ወደ መጠየቂያው ያክሉ። ምንጭ ያልሆነ ሰነድ የፈጠራ ግብዣ ነው።
3. የመጫን መዋቅር. መደበኛ ክፍሎች ለ README (ዓላማ ፣ ጭነት ፣ አጠቃቀም ፣ ውቅር ፣ አስተዋፅዖ) ፣ የፕሮጀክት ቅርጸት።
4. "ለምን" ቦታዎችን ምልክት አድርግባቸው። ምክንያቱን የማያውቅባቸውን ውሳኔዎች "ለምን" ማስታወሻ እዚህ እንደሚያስፈልግ ምልክት እንዲያደርግ AI ጠይቅ። ከዚያ ባዶዎቹን ይሞሉ.
5. አረጋግጥ። በእውነቱ የመጫኛ ደረጃዎችን ያሂዱ; የናሙና ኮዱን ይሞክሩ። የማይሰራ README ከምንም ነገር የከፋ ነው።

ሶስት ሚኒ ጉዳዮች

ጉዳይ 1 — README የተፋጠነ የቦርድ ጉዞ። ክፍት ምንጭ መሣሪያ README ጠፍቷል; አዲስ አስተዋጽዖ አበርካቾች በአማካይ ለ2 ሰአታት ከመጫኑ ጋር ታግለዋል። ቡድኑ የመጫኛ ስክሪፕቶችን እና pack.jsonን ለ AI ሰጠ እና የተዋቀረ README አዘጋጅቷል፣ ከዚያም እርምጃዎቹን እራሳቸው በንጹህ ማሽን ላይ በማካሄድ ሁለቱን የጎደሉትን ጥገኞች ጨምረዋል። ለቀጣይ አስተዋጽዖ አበርካቾች የመጫኛ ጊዜ በአማካይ ወደ 25 ደቂቃዎች ቀንሷል።

ጉዳይ 2 - የተሰራው "ለምን" ወጥመድ. አንድ ገንቢ በጊዜ ማብቂያ ዋጋ (የጊዜ ማብቂያ=30) አጠገብ አስተያየት እንዲሰጥ AI ን ጠየቀ። AI “ከፍተኛ የአውታረ መረብ መዘግየትን መታገስ” ምክንያታዊ ግን ትክክል ያልሆነ ማረጋገጫ ጽፏል። ትክክለኛው ምክንያት የታችኛው አገልግሎት ውል የ30 ሰከንድ ገደብ ነበር። የተሳሳተ ትርጓሜው ተከታይ የሆነ ገንቢ ሳያስፈልግ እሴቱን እንዲጨምር አድርጓል፣ ይህም ወደ አንድ ክስተት አመራ። ትምህርት፡ የኮዱ ባለቤት ማረጋገጫውን ማረጋገጥ አለበት።

ጉዳይ 3 — የሰነድ ስታንዳርድ አውቶማቲክ ሆኗል። 40 ተግባራት ያለው ረዳት ሞጁል ምንም ሰነዶች አልነበረውም። AI የፕሮጀክት ቅርፀት (ጎግል ዘይቤ) ተሰጥቶ ለእያንዳንዱ ተግባር መለኪያ ፣ መመለሻ እና ልዩ መግለጫዎችን አዘጋጅቷል ። ገንቢው እነዚህን ገምግሞ ጥቂት የተሳሳቱ መግለጫዎችን አስተካክሏል። 40 ተግባራትን ማስመዝገብ ከግማሽ ቀን ወደ አንድ ሰዓት ያህል ወርዷል.

አራት ሊገለበጡ የሚችሉ አብነቶች

የተዋቀረ README ረቂቅ፡-

ዒላማ ታዳሚ፡ {{ለምሳሌ፡ new contributor}}.ከታች ባሉት ፋይሎች መሰረት README ረቂቅ ይጻፉ። ክፍሎች: ዓላማ, ባህሪያት, መስፈርቶች, መጫን, ክወና, ውቅር, ሙከራ, አስተዋጽዖ. የመጫኛ / አሂድ ትዕዛዞችን ከትክክለኛ ፋይሎች ማውጣት; ተስማሚ። እርግጠኛ ያልሆኑባቸውን ቦታዎች በ"[VERIFY]" ምልክት ያድርጉባቸው። ምንጭ፡ {{package.json / scripts / sample code}}

ሰነድ/ኤፒአይ ማጣቀሻ፡

ዶክትሪን ለእነዚህ ተግባራት በ{{ፕሮጀክት ዘይቤ፡ Google/NumPy/JSDoc}} ቅርጸት ይፃፉ፡ አጭር ማጠቃለያ፣ ግቤቶች (አይነት + ትርጉም)፣ መመለስ፣ የተጣሉ የማይካተቱ፣ 1 አጭር ምሳሌ። ኮዱ በግልጽ የሚናገረውን አይድገሙ። የንድፍ ውሳኔዎችን "ለምን" እንደ "[ለምን አስፈለገ]" ብለው ምልክት ያድርጉበት፣ የፈጠራ ማረጋገጫ አይጻፉ።{{code}}

ለ"ለምን" አስተያየት ክፍተቶችን ያስወግዱ፡-

በዚህ ኮድ ውስጥ፣ ቀጣዩ ገንቢ "ለምንድን ነው?" (አስማት ቁጥሮች, ያልተለመዱ ውሳኔዎች, መፍትሄዎች). ለእያንዳንዳቸው SKELETON አስተያየት ይስጡ፣ ግን ምክንያታዊውን ባዶ ይተዉት። ማረጋገጫውን እሞላለሁ።{{code}}

Changelog/PR መግለጫ፡-

ከታች ካለው ልዩነት {{changelog entry / PR description}} ይፃፉ። ቅርጸት፡ ምን ተለወጠ (በተጠቃሚ ቋንቋ)፣ ለምን (እትም {{...}})፣ ለውጥ መስበር (ካለ)፣ ተፈትኗል። ቴክኒካዊ ቃላትን ወደ ኢላማ ታዳሚ አስተካክል።{{diff}}

ደካማ ጥያቄ / ጠንካራ ጥያቄ

ደካማ፡ "ለዚህ ፕሮጀክት README ይፃፉ።"

ጠንካራ፡ "የዒላማ ታዳሚ፡ ይህን ሬፖ ለመጀመሪያ ጊዜ የሚዘጋው ገንቢ። በተያያዙት ጥቅል.json፣ docker-compose.yml እና scripts/folder ላይ በመመስረት ረቂቅ README ከዓላማ፣ መስፈርቶች፣ ጭነት፣ አሠራር፣ ሙከራ፣ አስተዋጽዖ ክፍሎች ጋር ይፃፉ። ከእነዚህ ፋይሎች ውስጥ ትእዛዞቹን ያውጡ፣ እርግጠኛ ካልሆኑ በማንኛውም ቦታ ላይ ምልክት ያድርጉባቸው።"

ጠንካራው ስሪት ለተመልካቾች, ምንጩ, አወቃቀሩ እና "አድርገው, ምልክት ያድርጉበት" የሚለውን ደንብ ይሰጣል; ስለዚህ ሰነዱ በእውነተኛ ፋይሎች ላይ የተመሰረተ እና የሚረጋገጡ ቦታዎች በግልጽ የሚታዩ ናቸው.

የሰነድ አይነት

AI ጥሩ ይሰራል

የሰው ልጅ ይጨምራል/ያረጋግጣል

README ጭነት

የእርምጃ ንድፍ

ደረጃዎቹን ያሂዱ እና ያረጋግጡ

ሰነድ/ኤፒአይ

መዋቅር, መለኪያ, ዓይነት

ትክክለኛው ዓይነት እና "ለምን"

ኮድ አስተያየት

"እሱ ምን እያደረገ ነው" ማጠቃለያ

"ለምንድን ነው" ጽድቅ

Changelog/PR

የመጀመሪያው ረቂቅ

ተፅዕኖ እና ትክክለኛነት

የስነ-ህንፃ ውሳኔ (ADR)

አጽም

እውነተኛ ውሳኔዎች እና ስምምነት

ሰነዶች ጥገና ያስፈልገዋል

በጣም አደገኛው የሰነድ ገጽታ ውሸት ቢሆንም እውነት ሆኖ ሲገኝ ነው። ኮዱ ሲቀየር እና ሰነዱ ካልተዘመነ አንባቢን በንቃት ያሳስታል። AI ማዘመንን ቀላል ያደርገዋል፡ ልዩነት አውጥተህ “ይህ ለውጥ በየትኞቹ የሰነዱ ክፍሎች ላይ ተጽዕኖ ያሳድራል?” ብለህ ጠይቅ። ብለህ ትጠይቅ ይሆናል። ግን ወቅታዊነትን የሚያረጋግጥ ሂደት ነው - የሰነድ ማሻሻያውን የኮድ ለውጥ አካል ያድርጉት (የPR ተቀባይነት መስፈርት)። AI ያፋጥናል; ቡድኑ ዲሲፕሊን ይገነባል።

ማስጠንቀቂያ፡ የመጫኛ ደረጃዎችን በ README ውስጥ ሳያረጋግጡ አያትሙ። የ"ምናልባት ስራ" ሰነድ የአዲሱን ገንቢ የመጀመሪያ ቀን ሊያበላሽ እና እምነትን ሊሽር ይችላል። እርምጃዎችን እራስዎ በንጹህ አከባቢ ውስጥ ያካሂዱ።

የተለመዱ ስህተቶች

• ከ AI ጋር እንዲመጣጠን "ለምን" ማግኘት. የውሸት መጽደቅ ካለመጽደቅ የከፋ ነው; የኮዱ ባለቤት የንድፍ ምክንያቱን መጻፍ አለበት.
• የመጫን ደረጃዎችን አለማረጋገጥ. አንብብ የማይሰራ እምነትን ያጠፋል።
• ኮዱን በመድገም ላይ አላስፈላጊ አስተያየት። የ"ለምን" ትርጉሞችን በማደብዘዝ ጫጫታ ይፈጥራል።
• የታለመውን ታዳሚ አለመግለጽ። ለማን እንደተጻፈ ግልጽ ያልሆነ ሰነድ ለጀማሪም ሆነ ለባለሞያው ምንም ፋይዳ የለውም።
• ዝመናውን ከሂደቱ መለየት። ሰነዱ በኮዱ ካልተዘመነ በፍጥነት አሳሳች ይሆናል።

በማጠቃለያው

AI አብዛኛው የሜካኒካል ሸክሙን ከሰነድ ውጭ ይወስዳል፡ ፈጣን ረቂቆች README፣ docstring፣ API ማጣቀሻ፣ የለውጥ ሎግ እና የህዝብ ግንኙነት መግለጫዎች። ነገር ግን "ለምን" የሚለውን ማወቅ አይችልም, እሱም በጣም ዋጋ ያለው ንብርብር ነው, እና እሱን ማዘጋጀት አደገኛ ነው. የሥራ ክፍፍሉ ግልጽ ነው፡ AI “ምን/እንዴት” የሚለውን ያመነጫል፣ “ለምን” የሚለውን ጨምረዋቸዋል። ተመልካቾችን ይግለጹ፣ ግብዓቶችን ያቅርቡ፣ መዋቅርን ይጫኑ፣ የሚስማሙ ቦታዎችን ምልክት ያድርጉ እና እያንዳንዱን የመጫኛ ደረጃ እራስዎ በማስኬድ ያረጋግጡ። ሰነዶች የኮዱ ለውጥ ዋና አካል አድርገው።

የመተግበሪያ ተግባር

ሰነዱ የጎደለ ወይም ያለፈበት ሞጁል ወይም ትንሽ ፕሮጀክት ይምረጡ። በመጀመሪያ ከ "የተዋቀረ README ረቂቅ" (ወይም ዶክትሪን) አብነት ጋር ከኤአይአይ ላይ ንድፍ ይፍጠሩ; ምንጩን እና የታለመውን ታዳሚ መስጠትዎን እርግጠኛ ይሁኑ። ከዚያ AI (አረጋግጥ) ወይም (ለምን አስፈለገ) የሚል ምልክት ባደረገበት በእያንዳንዱ ነጥብ ይሂዱ፡ በእውነቱ የማዋቀር እርምጃዎችን ያሂዱ እና ንድፉን በእራስዎ እውቀት “ለምን” ይሙሉ። ምን ያህል እርምጃዎች መስተካከል እንዳለባቸው እና ምን ያህል "ለምን" እንዳከሉ ልብ ይበሉ.

የማረጋገጫ ዝርዝር

• [ ] በሰነዱ ውስጥ "ምን/እንዴት" እና "ለምን" የሚለውን ንብርቦችን እለያለሁ።
• [] AI "ለምን" አላደርገውም ፣ እኔ ራሴ እጨምራለሁ ።
• [ ] መጠየቂያውን ለታለመላቸው ታዳሚዎች እና ትክክለኛው የምንጭ ፋይሎችን እሰጣለሁ።
• [] በ AI ምልክት የተደረገባቸውን [VERIFY] ነጥቦችን በግሌ በማስፈጸም አረጋግጣለሁ።
• [] ኮዱን የሚደግሙ አላስፈላጊ አስተያየቶችን አስወግዳለሁ።
• [ ] የሰነድ ማሻሻያውን የኮዱ ለውጥ አካል እያደረግሁ ነው።