Hagnaður:
- Geta til að framleiða README, docstring og breytingaskrá uppkast byggð á markhópi og uppruna með gervigreind
- Geta til að aðgreina „hvað/hvernig“ og „af hverju“ lögin í skjölum og bæta við „af hverju“ sem manneskja
- Staðfesta uppsetningarskrefin með því að keyra þau persónulega og gera skjalið að hluta af kóðabreytingunni
Sá hluti hugbúnaðar sem oftast er vanræktur en langvarandi er skjöl. Kóðinn er læsilegur jafnvel eftir mánuði; Sá sem skrifaði það er horfinn, samhengið er gleymt og eftir stendur aðeins það sem skrifað var. Gott README (kynningarskjal sem útskýrir hvað verkefni er og hvernig á að setja það upp og keyra það), skýringarkóða athugasemdir og uppfærð API skjöl (tilvísun sem útskýrir hvernig á að nota viðmót) ákvarðar beint hraða teymisins. AI tekur mikið af „skrifþreytu“ úr skjölum - en það kemur með gildru: AI getur ályktað af kóða hvað það gerir, en getur oft ekki vitað hvers vegna það er gert þannig.
Í þessari einingu muntu læra hvernig á að búa til README, kóða athugasemd, docstring (comment blokk skrifuð eftir aðgerð/flokki), API skjal og breytingaskrá með gervigreind; og hvernig á að varðveita dýrmætasta hluta skjala: „af hverju.
Munur á "Hvað" og "Af hverju"
Það eru tvö lög af skjölum. Hið fyrsta er hvað/hvernig: "þessi aðgerð flokkar lista", "keyrðu þessa skipun til að setja upp". Þetta er hægt að draga úr kóðanum og uppbyggingunni; AI skarar framúr hér. Í öðru lagi, hvers vegna: "af hverju gerðum við þessa þjónustu ósamstillta frekar en samstillta", "af hverju er þetta viðmiðunargildi 30 sekúndur", "af hverju völdum við þetta safn fram yfir hitt". Þetta er ekki skrifað í kóðann; Það er afurð hönnunarákvarðana, takmarkana og fyrri sársauka.
AI veit ekki "af hverju"; Í besta falli er það skynsamleg ágiskun - sem er hættuleg, því röng ástæða er verri en engin. Þannig að verkaskiptingin er skýr: gervigreind semur „hvað/hvernig“, þú bætir við „af hverju“. Verðmætasta athugasemdin er sú sem segir það sem kóðinn getur ekki sagt.
Ábending: Ekki endurtaka með athugasemd það sem kóðinn sjálfur segir skýrt (eins og i = i + 1 // aukið i um einn). AI framleiðir stundum svona óþarfa athugasemdir; Útrýmdu þeim og eyddu orku þinni í „af hverju“ athugasemdir.
Skref fyrir skref: Skjalagerð með gervigreind
- Tilgreindu markhópinn. „Hönnuði að byrja,“ „ytra teymi sem mun nota þetta API,“ „framtíðar ég“ – áhorfendur gefa tóninn fyrir tungumál og dýpt.
- Gefðu upp heimildina. Bættu viðeigandi kóða, núverandi README, dæmi um notkun við hvetjunni. Óheimilt skjal er boð um tilbúning.
- Álagningaruppbygging. Staðlaðir hlutar fyrir README (tilgangur, uppsetning, notkun, stillingar, framlag), verkefnissnið fyrir docstring.
- Merktu við „af hverju“ bilin. Biddu gervigreindina um að merkja ákvarðanir sem hann þekkir ekki rökin fyrir sem „þarf „af hverju“ athugasemd hér“; Þá fyllir þú út í eyðurnar.
- Staðfestu. Reyndu að keyra uppsetningarskrefin; prófaðu sýnishornskóðann. README sem virkar ekki er verra en engin README yfirleitt.
Þrjú Mini Cass
Tilfelli 1 — README flýtt um borð. README fyrir opinn uppspretta tól vantaði; Nýir þátttakendur áttu í erfiðleikum með uppsetninguna í að meðaltali 2 klukkustundir. Teymið gaf gervigreind uppsetningarforskriftirnar og package.json og samdi uppbyggt README, keyrði síðan skrefin sjálf á hreinni vél og bætti við tveimur ósjálfstæðum. Uppsetningartími fyrir síðari þátttakendur minnkaði í 25 mínútur að meðaltali.
Tilfelli 2 — Tilbúna „af hverju“ gildran. Hönnuður bað gervigreindina um athugasemd við hliðina á tímamörkum (timeout=30). Gervigreindin skrifaði sanngjarna en ranga rökstuðning „til að þola mikla netleynd“; Raunveruleg ástæðan var samningsbundin 30 sekúndna hámark eftirþjónustu. Rangtúlkunin varð til þess að síðari framkvæmdaraðili hækkaði verðmæti að óþörfu, sem leiddi til atviks. Lexía: eigandi kóðans verður að staðfesta rökstuðninginn.
Tilfelli 3 - Docstring staðallinn er orðinn sjálfvirkur. Hjálpareining með 40 aðgerðum hafði enga docstrings. Gervigreindin fékk verkefnissniðið (Google stíll) og framleiddi færibreytur, skil og undantekningarlýsingar fyrir hverja aðgerð; Framkvæmdaraðilinn fór yfir þetta og lagaði nokkrar rangar gerðaryfirlýsingar. Skráning 40 aðgerða fór úr um hálfum degi í klukkutíma.
Fjögur afritanleg sniðmát
Skipulögð README drög:
Markhópur: {{t.d. nýr þátttakandi}}. Skrifaðu drög að README byggt á skránum hér að neðan. Hlutar: Tilgangur, Eiginleikar, Kröfur, Uppsetning, Rekstur, Stillingar, Prófanir, Framlag. Dragðu út uppsetningar-/keyrsluskipanir úr raunverulegum skrám; PASSA. Merktu staðina sem þú ert ekki viss um með „[VERIFY]“. Heimild: {{package.json / scripts / sample code}}
Docstring/API tilvísun:
Skrifaðu docstring í þessar aðgerðir á {{verkefnisstíl: Google/NumPy/JSDoc}} sniði: stutt samantekt, breytur (tegund + merking), skil, undantekningar kastað, 1 stutt dæmi. Ekki endurtaka það sem kóðinn segir GJÖRLEGA. Merktu hönnunarákvarðanir sem krefjast "hvers vegna" sem "[HVERS VEGNA ÞARF]", ekki skrifa uppspuna rökstuðning.{{kóði}}
Fjarlægðu bil fyrir "af hverju" athugasemd:
Í þessum kóða gæti næsti verktaki spurt "af hverju er þetta svona?" (töfratölur, óvenjulegar ákvarðanir, lausnir). Gefðu athugasemd BEINAGREIÐ fyrir hvern, en láttu rökstuðninginn vera AUT; Ég mun fylla út rökstuðninginn.{{code}}
Breytingaskrá/PR yfirlýsing:
Skrifaðu {{changelog entry / PR description}} úr muninum hér að neðan. Snið: Hvað breyttist (á notandamáli), Hvers vegna (mál: {{...}}), Brotandi breyting (ef einhver er), Hefur það verið prófað. Aðlaga tæknilegt hrognamál að markhópi.{{diff}}
Veik kvaðning / Sterk kvaðning
Veik: "Skrifaðu README fyrir þetta verkefni."
Strong: "Markhópur: þróunaraðili sem klónar þessa endursölu í fyrsta skipti. Byggt á meðfylgjandi package.json, docker-compose.yml og scripts/ möppu, skrifaðu drög að README með tilgangi, kröfum, uppsetningu, rekstri, prófun, framlagshlutum. Dragðu út skipanirnar úr þessum skrám, ekki gera þær upp]; merktu hvar sem þú ert ekki viss um]."
Sterka útgáfan gefur áhorfendum, uppsprettu, uppbyggingu og „gera það, merktu það“ regluna; þannig að skjalið byggist á raunverulegum skrám og staðirnir sem á að sannreyna sjást vel.
Skjaltegund
AI gengur vel
Manneskjan bætir við/staðfestir
README uppsetning
skref útlínur
Keyrðu skrefin og staðfestu
Docstring/API
Uppbygging, færibreyta, gerð
Rétt gerð og „af hverju“
Kóða athugasemd
„Hvað er hann að gera“ samantekt
„Af hverju er þetta“ rökstuðningur
Breytingaskrá/PR
fyrstu drög
Áhrif og nákvæmni
Ákvörðun um byggingarlist (ADR)
beinagrind
Raunverulegar ákvarðanir og málamiðlanir
Skjöl krefjast viðhalds
Hættulegasti þáttur skjals er þegar það virðist satt þótt það sé rangt. Þegar kóðinn breytist og skjalið er ekki uppfært villir það virkan afvega fyrir lesandanum. Gervigreind auðveldar uppfærslur: gefðu út mismun og spyrðu „hvaða hluta skjalsins hefur þessi breyting áhrif á? þú gætir spurt. En það er ferlið sem tryggir uppfærslu – gerðu uppfærslu skjala hluta af kóðabreytingunni (viðmiðunarviðmiðun PR). AI hraðar; Liðið byggir upp aga.
Varúð: Ekki birta án þess að staðfesta uppsetningarskrefin í README. „Líklega vinnu“ skjal getur eyðilagt fyrsta dag nýs þróunaraðila og rýrt traust. Keyrðu skrefin sjálfur í hreinu umhverfi.
Algeng mistök
- Að fá „af hverju“ til að passa gervigreind. Fölsk réttlæting er verri en engin réttlæting; Kóðaeigandinn ætti að skrifa ástæðu hönnunarinnar.
- Ekki staðfesta uppsetningarskrefin. README sem virkar ekki eyðileggur traust.
- Óþarfa athugasemd sem endurtekur kóðann. Það framleiðir hávaða, hylja raunverulegar „af hverju“ túlkanir.
- Ekki tilgreint markhópinn. Skjal sem er óljóst hverjum það er skrifað kemur hvorki nýliði né sérfræðingi að gagni.
- Aðskilja uppfærsluna frá ferlinu. Ef skjalið er ekki uppfært með kóðanum verður það fljótt villandi.
Í stuttu máli
Gervigreind tekur mikið af vélrænni byrði af skjölum: fljótleg drög README, docstring, API tilvísun, breytingaskrá og PR lýsingar. En það getur ekki vitað "af hverju", sem er verðmætasta lagið, og það er hættulegt að gera það upp. Verkaskiptingin er skýr: gervigreind framleiðir „hvað/hvernig,“ þú bætir við „af hverju. Tilgreindu áhorfendur, útvegaðu auðlindir, settu uppbyggingu, merktu staði til að passa og staðfestu hvert uppsetningarskref með því að keyra það sjálfur. Gerðu skjöl að órjúfanlegum hluta af kóðabreytingunni.
Umsóknarverkefni
Veldu einingu eða lítið verkefni þar sem skjöl vantar eða eru úrelt. Búðu fyrst til útlínur frá gervigreind með „skipulögðu README drögum“ (eða docstring) sniðmátinu; Vertu viss um að gefa upp heimildina og markhópinn. Farðu síðan í gegnum hvern punkt þar sem gervigreindin hefur merkt [STAFNA] eða [HVERS VEGNA ÞARF]: keyrðu í raun uppsetningarskrefin og fylltu út hönnunina „af hverju“ með þinni eigin þekkingu. Athugaðu hversu mörg skref þarf að laga og hversu mörgum „af hverju“ þú bættir við.
gátlisti
- [ ] Í skjölunum geri ég greinarmun á „hvað/hvernig“ og „af hverju“ lögin.
- [ ] Ég læt gervigreindina ekki búa til „af hverju“, ég bæti því við sjálfur.
- [ ] Ég gef hvetjunni markhópnum og raunverulegum upprunaskrám.
- [ ] Ég sannreyna [VERIFY] punktana sem merktir eru af gervigreindinni með því að framkvæma þá persónulega.
- [ ] Ég útrýma óþarfa athugasemdum sem endurtaka kóðann.
- [ ] Ég er að gera uppfærslu skjala hluta af kóðabreytingunni.