Igal dokumentatsioonimeeskonnal, keda ma tean, on stiilijuhend. Mõni on eelmiselt omanikult päritud neljakümneleheküljeline PDF, mõni on vikileht, mis on kasvanud ühe vaidluse kaupa korraga. Kõik ütlevad umbes sama laadi asju. Pealkirjas on suur algustäht ainult esimesel sõnal. Kirjutame "vali", mitte "klõpsa". Toote nimi on Launchpad, mitte "Launchpadi rakendus" ega "LP". Hoiatus tuleb enne sammu, mitte pärast seda.
Uus kirjutaja õpib need kuuga selgeks, peamiselt ülevaatuse kommentaaride kaudu. Tehisaru assistent ei õpi neid kunagi ja suur osa pettumusest tehisaru mustandite vastu tuleb just sealt.
Miks mustand kõlab nagu keegi teine
Palu vestlusassistendil teha muudatuste logist väljalaskemärkmed ja saad teksti, mis loeb hästi ja ei kõla nagu ükski su kolleeg. Pealkirjad Inglise Moodi Suurte Tähtedega. "Klõpsa nuppu." Toote nimi ühe lehe peal kolmel eri kujul. Mudel ei kirjuta halvasti. Talle lihtsalt pole öeldud ja tal pole põhjust arvata ära just sinu maja reegleid tuhande teise hulgast, mida ta on näinud.
Nii teevad kirjutajad ilmse asja ja kleebivad stiilijuhendi vestlusse. See toimib vestluse või kaks. Siis läheb vestlus pikaks ja alguse juhised kaaluvad vähem, või alustad neljapäeval uut vestlust ja unustad kleepida, ja ülevaatuse kommentaarid tulevad tagasi. Stiilijuhendist saab asi, mida pead meeles pidama kaasa panna, ehkki just see töö pidi sinult ära võetama.
Enamik stiilijuhendist ei pea agendini jõudma
Siin tasub aus olla, millised reeglid loevad. Pikk stiilijuhend katab asju, mida agent puudutab harva: kuidas nimetada ekraanipildi faile, kes kinnitab uue termini, millal lokaliseerijatele pilet teha.
Mustandisse jõuavad reeglid on vähem arvukad ja konkreetsemad. Toote ja funktsioonide nimed täpselt õigesti kirjutatuna. Käputäis sõnu, mida sa kunagi ei kasuta, ja mida ütled nende asemel. Pealkirjade suurtähed. Kuidas kirjutad kasutajaliidese silte (paksus kirjas, jutumärkides või lihtsalt). Kas pöördud lugeja poole sinatades või teietades. Kuhu lähevad märkused ja hoiatused. Ühe lausega, kellele see dokumentatsioon on. Tavaliselt mahub see ühele lehele, vahel vähemale.
Fail dokumentatsiooni kausta juures
Koodiagendid otsivad juba praegu lihtsat tekstifaili kausta juurest, milles nad töötavad. Claude Code loeb faili CLAUDE.md, Codex ja OpenCode loevad faili AGENTS.md. Mis seal kirjas on, on kontekstis juba enne, kui esimese küsimuse kirjutad. Arendajad hoiavad seal ehituskäske ja koodireegleid. Tehnilise kirjutaja jaoks on see loomulik koht sellele ühele lehele maja reeglitele.
Ritemarkis on see fail kaustas sinu dokumentide kõrval ja Agent Library näitab seda projekti all agendi põhiseadistusena, nii et saad selle avada ja muuta nagu iga teise dokumendi. Kui sul seda veel pole, võid paluda agendil kirjutada esimese versiooni selle põhjal, mida ta kaustast leiab, ja siis lõigata see lühemaks, jättes alles ainult selle, mis sulle päriselt oluline on. Aken on kaust, nii et iga vestlus, mida selles aknas alustad, olgu Claude Code, Codex või OpenCode, algab samade reeglitega. Teine toode teise stiilijuhendiga saab oma kausta ja oma faili, oma aknas.
Pärast seda võib palve olla lühike. "Tee muudatuste logist 3.2 väljalaskemärkmete mustand, sama ülesehitusega nagu 3.1 märkmed." Toote nimed ja "vali, mitte klõpsa" tulevad kaasa ilma, et peaksid neid eraldi küsima.
Kui muudatus on lai, vaata enne plaani
Stiilireeglid on kõige olulisemad siis, kui agent muudab korraga palju lehti, ja just siis on viga kõige kallim. Ümbernimetamine neljakümnel lehel või iga hoiatuse tõstmine oma sammu ette ei ole asi, mida tahad lasta kõigepealt ära teha ja alles siis üle vaadata.
Claude Code'i ja Codexiga saad lülitada agendi režiimi Plan only. Agent loeb failid ja sinu stiilifaili läbi, näitab siis, mida ja millistes failides ta muuta kavatseb, ja midagi ei muudeta enne, kui oled plaani heaks kiitnud. Plaani lugemine on kiirem kui neljakümne muudatuse lugemine ja just siis on õige hetk öelda: "API viidet ära puutu, need nimed tulevad koodist."
Mida fail ei tee
Stiilifail on juhis ja seda oleks lihtne üle müüa.
Agent järgib seda enamasti ja jätab ikkagi asju kahe silma vahele, eriti reegleid, mis nõuavad otsustamist, näiteks millal on hoiatus piisavalt tõsine, et olla hoiatus. See ei ole automaatne kontroll. Kui su meeskond kasutab terminoloogia jaoks automaatseid kontrolle, jäta need alles ja käivita need agendi kirjutatu peal nagu kõige muu peal. Fail ei asenda ka päris stiilijuhendit. Sisseelamine, reeglite põhjendused ja pikk erandite saba elavad endiselt seal. Fail on lühike versioon, mis peab iga mustandi juures olemas olema.
Muutub see, millist ülevaatust sa teed. Selle asemel, et parandada sel nädalal viiendat korda "klõpsa" sõnaks "vali", kulutad ülevaatuse sellele, kas selgitus on õige, ja seda osa saad teha ainult sina.
Kui tahad näha, kuhu see kogu dokumentatsioonitöös sobib, siis tehniliste kirjutajate leht käib läbi väljalaskemärkmed, API dokumentatsiooni ja teadmusbaasi töö ning New Window juhend näitab, kuidas iga kaust saab oma akna.