Agent üçün texniki tapşırıq: ideyanı konkret tapşırığa necə çevirmək

Agentə ardıcıl iki sorğu. Birincisi: "SPEC_LANDING.md faylındakı texniki tapşırığa görə səhifəni qur". Bir neçə dəqiqə sonra qovluqda index.html yaranır və o, tam düşünüldüyü kimi görünür. İkincisi, elə həmin axşam: "2048 oyununu qur". Bu dəfə isə agent ya ardıcıl beş sual verir, ya da heç nə demədən 5×5 sahə qurur, üstəlik heç kimin istəmədiyi gedişi geri qaytarma düyməsini də əlavə edir.

Fərq agentdə deyil. Fərq onun girişdə nə aldığındadır. Bu məqalədə kiçik bir iş üçün texniki tapşırığın nədən ibarət olduğunu, ona yazılacaq mənanı haradan götürməyi, yalnız istiqamət məlum olanda nə etməyi və "hazırdır"dan sonra nəticəni niyə işə başlamazdan əvvəl yazdığınız həmin sətirlərlə yoxladığınızı araşdıracağıq.

1. İdeya hələ tapşırıq deyil

"2048 istəyirəm". "Gözəl bir səhifə düzəlt". "Yeni oyun düzəlt, bir az maraqlısını". Bunların hamısı ideyadır və hamısının ortaq bir dərdi var: başınızda bütöv bir şəkil var, mətndə isə iki söz. Agent isə yalnız mətni görür.

İstəkdə boş yer qalanda agentin qarşısında iki yol olur. Birincisi - soruşmaq. İkincisi - onu özü doldurmaq: sahəni seçmək, qayda uydurmaq, düymə əlavə etmək. İkinci yol daha səssizdir və elə buna görə daha təhlükəlidir. siz nəticəni görənə qədər qərarın sizin əvəzinizə verildiyini hiss etməyəcəksiniz. İstəkdəki hər doldurulmamış yer kiminsə verəcəyi bir qərardır və susmaya görə bu kəs siz olmayacaqsınız.

"2048-i necə oynamağı hamı bilir" - bu, sizin başınızdadır. Agent bu "hamı bilir"i oxumur. Sahə neçəyə neçədir? Yeni lövhəciklər haradan və nə vaxt gəlir? Hansıları birləşir və nəyə çevrilir? Qələbə nə vaxtdır, oyun nə vaxt bitir? Sizin üçün bir sözdür, onun üçün isə qaydalara bölünənə qədər boş yerdir. Çatda bu belə görünür:

Siz:   2048 oyununu qur
Agent: Başlamazdan əvvəl dəqiqləşdirim:
       1. Sahə necə olsun, 4×4?
       2. Nəyi qələbə sayaq?
       3. Gedişi geri qaytarmaq lazımdırmı?

Bu, yaxşı nəticədir. Eyni sorğuya başqa nəticə də olur:

Siz:   2048 oyununu qur
Agent: Hazırdır. Oyun index.html faylındadır:
       - 5×5 sahə
       - son gedişi geri qaytarma düyməsi
       - localStorage-da rekordlar cədvəli

Bu, agentin xətası deyil. Bunlar sizin üç boş yerinizdir, sizsiz doldurulub.

İdeyadan etibar edilə bilən nəticəyə gedən yol belə görünür. Məqalə bu yolla soldan sağa gedir. Son addım isə üçüncüyə qaytarır: yoxladınız, boşluq tapdınız, texniki tapşırığa sətir əlavə etdiniz və yenidən agentə verdiniz.

2. Məna haradan gəlir

Səhifənin və ya oyunun karkasını agent bir neçə dəqiqəyə qurur və bu, həqiqətən ən çətin hissə deyil. Çətini bilməkdir: səhifədə nə olmalıdır və ümumiyyətlə nə oynayırıq. Bu, kodda yoxdur. Bu, insanların başındadır, bəzən də sizin öz başınızda, bəzi şeyləri isə agent də bilir. Bu məna suallarla əldə edilir və mənbə üçdür: insanlar, siz özünüz, agent.

İnsanlar - sifariş verən və istifadə edəcək şəxslərdir. Onlara sualları toplu şəkildə vermək daha yaxşıdır. Bir dəfəyə beş-altı bəndlik siyahı, gündə bir sual yox. Toplu suallar zəhlətökən görünür, bilirəm. Əslində isə hamını bir həftəlik yazışmadan xilas edir.

Sifarişçi siz özünüz olanda (öz oyununuz, öz səhifəniz) sualları özünüzə verirsiniz və burada ən böyük vəsvəsə "bu ki aydındır" deyə cavab verməkdir. Aydın olan da aydın olmayan kimi yazılır. "Sahə 4×4" iki saniyəlik işdir, agent üçün isə bütöv bir yol ayrıcını bağlayır.

Üçüncü mənbə agentdir və burada əvvəlcədən bilməyə dəyən bir tələ var: bilmədiyiniz şey haqqında soruşa bilməzsiniz. Heç nəyi yerindən tərpətməyən gediş gediş sayılırmı? Telefonda svayp lazımdırmı? Xal göstərilsinmi? Oyun gözünüzün qarşısında olmayana qədər bu suallar ağlınıza gəlmir. Agent isə belə oyunlardan minini görüb və adətən harada büdrədiklərini bilir. Ona görə bəzən "qur" əvəzinə "gəl müzakirə edək" ilə başlamaq daha faydalıdır:

Brauzerdə 2048 oyunu qurmaq istəyirəm. Hələlik heç nə yazma.
Mənə onlarsız başlaya bilməyəcəyin sualları ver. Hamısını birdən, siyahı ilə.
Cavab verəcəyəm, sonra texniki tapşırığı SPEC_2048.md faylına yığacağıq.

Belə söhbət üçün iki qayda, yoxsa o bitmir. Birincisi: müzakirə növbəti bölmədəki dörd dayaq doldurulanda bitir və onun nəticəsi çat deyil, fayldır. İkincisi: agentin sualları tələb deyil, variantdır. O, həvəslə "rekordlar cədvəli də edək?" deyə soruşacaq və "yox" normal cavabdır. Belə "yox" da texniki tapşırığın sətridir, sadəcə "etmirik" bölməsində.

Hər halda - siz soruşmusunuz, ya agent - cavab çatda replika kimi qalmır, texniki tapşırıq faylına yazılır. Əks halda növbəti sorğu həmin boşluqla başlayacaq.

Solda üç mənbə, sağda bir təyinat yeri. Aşağıya gedən qırıq-qırıq ox cavabların ən çox getdiyi yoldur: çatda qalıblar və on mesajdan sonra artıq tapılmırlar. Sxemdə ox var, amma onun sonunda fayl yoxdur.

Agentdən daha çoxunu da istəmək olar: təkcə soruşmaq yox, həm də cavablarınıza əsasən texniki tapşırığın qaralamasını özü cızmaq, demədiklərinizi doldurmaq. Onun özündən əlavə etdikləri ilə sonra nə etməli - 4-cü bölmədə. Əvvəlcə texniki tapşırığın nədən ibarət olduğu haqqında.

3. Texniki tapşırığın dörd dayağı

Kiçik iş üçün texniki tapşırıq altı-səkkiz sətirdir. Onlar dörd dayaq üzərində durur: məqsəd, nə baş verməlidir, ilk versiyada nə olmayacaq, necə yoxlayacağıq. Budur, bütöv halda, oyun üçün:

# Texniki tapşırıq: 2048

MƏQSƏD:    brauzerdə 2048 oyunu, fayldan açılır, quraşdırma tələb etmir.
           HTML, CSS və JavaScript, yığım (build) olmadan

QAYDALAR:  sahə 4×4
           başlanğıcda və hər gedişdən sonra yeni lövhəcik yaranır: 2 və ya 4
           oxlar bütün lövhəcikləri bir tərəfə, sona qədər hərəkət etdirir
           iki eyni lövhəcik toqquşanda cəmlərinə bərabər bir lövhəciyə birləşir
           qələbə: sahədə 2048 lövhəciyi yarandı
           məğlubiyyət: gediş yoxdur, sahə doludur, birləşdiriləcək heç nə yoxdur

ETMİRİK:   rekordlar cədvəli, animasiyalar, gedişi geri qaytarma

YOXLAMA:   index.html-i brauzerdə açmaq, sahəni və başlanğıc lövhəcikləri görmək
           oxlarla üç gediş etmək, hər birindən sonra yeni lövhəcik yaranır
           iki ikiliyi birləşdirib dördlük almaq
           oyunu sona qədər oynamaq, məğlubiyyət ekranını görmək

Sonra dayaqları bir-bir keçək, hər birini iki tapşırıq üzərində göstərək: oyun və stolüstü oyunlar klubunun görüşünə dəvət səhifəsi.

Məqsəd

Birinci sətir. Onu oxuyan insan kodu yox, nəticəni təsəvvür etməlidir. "Brauzerdə 2048 oyunu, fayldan açılır, quraşdırma tələb etmir". "Klubun görüşünə dəvət səhifəsi: insan bunun necə görüş olduğunu başa düşür və düymə ilə qeydiyyatdan keçir".

Məqsədin yoxlanması: onu oxuyarkən insanın görəcəyi şeyi yox, kodu görürsünüzsə, bu artıq məqsəd deyil. "Lövhəciklərin birləşmə funksiyasını yazmaq" məqsəd deyil, işin bir parçasıdır.

Bura bir sətirlə "nə ilə qururuq" da əlavə olunur: HTML, CSS və JavaScript, yığım olmadan. Bu sətir olmasa, agent özü seçəcək və sizin işə sala bildiyiniz şeyi seçəcəyi heç də məlum deyil.

"Gözəl et" isə məqsəd ola bilməz. Kimə gözəl və bunu harada görmək lazımdır - aydın deyil.

Nə baş verməlidir

Ən uzun dayaq və oyun üçün o, artıq yuxarıda yazılıb. Qayda birdir: işə saldıqdan sonra sətrə baxıb "hə" və ya "yox" demək mümkündürsə, sətir yaxşıdır. "Sahə 4×4" - hə və ya yox. "İki eyni lövhəcik cəmlərinə bərabər bir lövhəciyə birləşir" - hə və ya yox. "Bir az maraqlısı" - nə hə, nə yox, və belə sətrin texniki tapşırıqda yeri yoxdur.

Bir sətirdə bir fikir. "Lövhəciklər yaranır və birləşir" iki yoxlamadır, deməli, iki sətir.

Səhifə üçün də eynidir, sadəcə qaydalar əvəzinə onda nə olduğu yazılır: "adı və tarixi olan başlıq", "üç blok: nə olacaq, kimin üçün, harada", "Qeydiyyat düyməsi formanın ünvanına aparır". Hər birini açıb görmək olar.

Belə siyahı ideyanın yanında darıxdırıcı görünür. Darıxdırıcı olması elə yaxşıdır. darıxdırıcı olan yoxlanılır.

İlk versiyada nə olmayacaq

Adətən unudulan yeganə dayaq və buna görə də ən dəyərlisi. Boş yeri agent özü bağlayır, həm də ən həvəslə - əlavə etməklə. Rekordlar cədvəli, lövhəciklərin animasiyası, gedişi geri qaytarma düyməsi, qaranlıq tema. Bunların hamısı faydalıdır və heç birini siz istəməmisiniz.

Adbaad yazılır. "Artıq heç nə olmasın" yox - bu, sərhəd deyil, arzudur - "etmirik: rekordlar cədvəli, animasiyalar, gedişi geri qaytarma". Səhifə üçün: "etmirik: qeydiyyat formasının özü, ödəniş, foto qalereyası". Adətən üç ad kifayətdir, on adı onsuz da heç kim yazmayacaq.

Bu, agentə yox, sizə nə üçün lazımdır. Nə qədər az qurulubsa, bir o qədər az yoxlamaq lazımdır. Həm də xarab olan şeyin haradan gəldiyi bir o qədər aydın olur: altı sətirdə axtarmaq altı ekranda axtarmaqdan asandır. Sərhədin olmadığının əlaməti: istəyinizdə və ya agentin cavabında "yeri gəlmişkən" sözü tez-tez görünməyə başlayıb.

Necə yoxlayacağıq

"Nə baş verməlidir" bölməsindəki hər sətir agent "hazırdır" dedikdən sonra bir yoxlamadır. Oyunu açdınız - sahə 4×4, hə. Oxu basdınız - lövhəciklər sürüşdü, yenisi yarandı, hə. İki ikiliyi birləşdirdiniz - dördlük, hə. Yoxlamalar siyahısını ayrıca yazmırsınız, o artıq yazılıb.

Üstəlik texniki tapşırığın özündə iki-üç "yoxlama" sətri: əl ilə dəqiq nə etməli. "Faylı brauzerdə açmaq, üç gediş etmək, sona qədər oynayıb uduzmaq". Bu sətirlər sorğudan sonra yox, əvvəl yazılır. Nəticədən sonra onları hiss olunmadan alınan şeyə uyğunlaşdırırlar - bu, öz-özünə baş verir və sizinlə də olacaq.

Agentin "hazırdır" deməsi yoxlama deyil, replikadır. Yoxlama sizindir, sizin sətirlərinizlə.

İndi təcrübə. "Stolüstü oyunlar klubunun görüşü üçün gözəl səhifə düzəlt" istəyini götürün və onu dörd dayağa bölün, hər birinə bir-iki sətir. Cavab elə aşağıdadır, tutuşdurun:

# Texniki tapşırıq: dəvət səhifəsi

MƏQSƏD:     stolüstü oyunlar klubunun görüşünə dəvət səhifəsi:
            insan bunun necə görüş olduğunu, nə vaxt və harada olduğunu başa düşür və düymə ilə qeydiyyatdan keçir.
            bir HTML faylı, stillər daxilində

SƏHİFƏDƏ:   klubun adı və görüşün tarixi olan başlıq
            üç blok: nə olacaq, kimin üçün, harada
            "Qeydiyyat" düyməsi formanın ünvanına aparır

ETMİRİK:    qeydiyyat formasının özü, ödəniş, foto qalereyası

YOXLAMA:    brauzerdə açmaq, başlığı və üç bloku görmək
            düyməni basmaq, formanın ünvanına düşmək

Diqqət edin, "gözəl" sözü texniki tapşırığa ümumiyyətlə düşməyib. O, yoxlanılmır. Gözəllik həqiqətən vacibdirsə, o da qalan hər şey kimi sətirlərə bölünür: "başlıqda bir şəkil", "ikidən çox rəng yox", "hər şey telefon ekranına sığır". Bunu artıq açıb baxmaq olar.

İki nümunədə blokların adları fərqlidir: oyun üçün "qaydalar", səhifə üçün "səhifədə". Bu, vacib deyil, necə rahatdırsa, elə adlandırın. Vacib olan odur ki, hər birində dörd dayaq var:

4. Bu, kimin qərarıdır

Texniki tapşırıqda heç kimin razılaşdırmadığı qərarlar peyda olur və bu, iki yolla baş verir. Birincisi: qaralamanı çərşənbə axşamına qədər cavab gözləmədən indi almaq üçün agentə boşluqları "ağlabatan bir şeylə" bağlamağa icazə vermisiniz. İkincisi: soruşmağa adam və ya vaxt olmadığı üçün sifarişçinin yerinə özünüz qərar vermisiniz.

Hər iki hal normaldır. Normal olmayan bunun fərziyyə olduğunu unutmaqdır. Bir həftə sonra düymənin formaya yox, poçta apardığını kimin fikirləşdiyini heç kim xatırlamayacaq və mübahisə məhz bunun üstündə olacaq.

Birinci hal üçün agentə sorğu belə görünür:

Bu cavablara əsasən dəvət səhifəsi üçün texniki tapşırığın qaralamasını hazırla.
Cavab olmayan yerlərdə ağlabatan bir şey fikirləş və ayrıca siyahıda
özündən nə əlavə etdiyini sadala. SPEC_INVITE.md faylına yaz.

Özündən əlavə edilənlərin siyahısını birinci, texniki tapşırığın özündən əvvəl oxuyursunuz. Bunlar sizin əvəzinizə verilmiş qərarlardır: hər biri ya razılaşdırmaq üçün mövzudan xəbəri olan adama göndərilir, ya da qeydlə texniki tapşırıqda qalır.

İkinci hal üçün - faylın özündə qeyd. Qərardan əvvəl "fərziyyə:" sözü və ya sadəcə sətrin sonunda sual işarəsi: "düymə klubun poçtuna aparır (?)". Cavab gələndə nəyi dəyişmək lazım olduğu dərhal görünür. və bunun haradan çıxdığını xatırlamağa ehtiyac qalmır.

Qeyd hər iki istiqamətdə işləyir. Sual işarələri olan texniki tapşırıq verilmiş agent adətən ilk növbədə onlar haqqında soruşur: onun üçün bu, sizin üçün olduğu kimi bir siqnaldır.

5. Suallar əvəzinə sandbox

Olur ki, nə qədər otursanız da, dörd dayaq yazılmır. "2048-ə bənzər nəsə istəyirəm, amma bilmirəm, xal lazımdırmı, svayplar lazımdırmı və ümumiyyətlə 4×4 olacaqmı". Bu, texniki tapşırıq deyil, hətta adi mənada ideya da deyil. Bu, istiqamətdir: yön aydındır, nəticə yox. Burada suallar kömək etmir: cavablar hələ nə sizdə var, nə sifarişçidə, agentin variantlarını isə müqayisə edəcək bir şeyiniz yoxdur.

Belə halda ən ucuzu baxmaqdır. Sandbox qurmaq: baxıb toxuna biləcəyiniz və əslində nə istədiyinizi anlaya biləcəyiniz ən sadə versiya. Agentlə bu, on dəqiqəyə başa gəlir və on dəqiqəlik işin nəticəsini atmağa heyfiniz gəlməz.

Sandbox da dörd dayaqlı texniki tapşırıqdır, sadəcə məqsədi fərqlidir:

# Texniki tapşırıq: sandbox 2048

MƏQSƏD:    2048-in brauzerdə necə oynandığına baxmaq və nə istədiyimi anlamaq.
           HTML, CSS və JavaScript, yığım (build) olmadan

QAYDALAR:  sahə 4×4
           oxlar lövhəcikləri hərəkət etdirir, eyniləri birləşir
           gedişdən sonra yeni lövhəcik yaranır

ETMİRİK:   qalan hər şey: qələbə, məğlubiyyət, xal, svayplar, dizayn

YOXLAMA:   beş dəqiqə oynamaq və nəyin çatmadığını, nəyin artıq olduğunu yazmaq

Baxın, nə dəyişdi. Məqsəd oyun deyil, anlayışdır. "Etmirik" ən uzun sətirdir, orada əmin olmadığınız hər şey var. Yoxlama isə "işləyirmi" deyil, "indi nə bilirəm"dir. Beş dəqiqə oynadınız - və əvvəldə vermək mümkün olmayan suallar öz-özünə yaranır: svayplar lazım deyil, kompüter arxasında oxlarla oynayırlar; xal lazımdır, onsuz darıxdırıcıdır; 4×4 azdır, 5×5-i sınamaq istərdim; məğlubiyyəti göstərmək lazımdır, yoxsa oyunun bitdiyi aydın olmur.

Sandbox-un nəticəsi elə budur. Kod yox, cavablar. Onlardan əsl texniki tapşırıq yazılır və o, sıfırdan, təmiz qovluqda, bir cümlə ilə qurulur: "fayldakı texniki tapşırığa görə oyunu qur". Sandbox öz işini görüb.

Bu, birinci bölmədəki həmin zəncirdir, sadəcə burada "Suallar" addımını bir dövr əvəz edib: soruşmağa bir şey olmayanda əvvəlcə baxırıq, sonra yazırıq. Aşağıya, texniki tapşırığa bir şey gedir - cavablar. Sandbox-dan agentə ox yoxdur və bu, unutqanlıq deyil: əsl versiyanı agent təmiz qovluqda, sıfırdan qurur. sonra hər şey zəncir üzrə gedir.

6. Texniki tapşırıq faylda yaşayır

Niyə yazışma yox, fayl. Yazışma itir: on mesajdan sonra lövhəciklərin birləşməsi haqqındakı qaydanı artıq tapmaq olmur. Fayl layihə qovluğunda kodun yanında durur, siz onu göstərəndə agent onu özü oxuyur, düzəliş edib yenidən vermək isə elə həmin cümlə ilə olur. Ad istənilən ola bilər: SPEC_2048.md, SPEC_LANDING.md, hətta tapsiriq.txt. Bu, adi mətn faylıdır, heç bir xüsusi formatı yoxdur.

O, bir cümlə ilə verilir. Müqayisə edin:

Əvvəl: "2048 oyununu qur, özün başa düşürsən necəsini, bir az maraqlısını".

İndi: "SPEC_2048.md faylındakı texniki tapşırığa görə oyunu qur".

İkinci sorğu birincidən qısadır, amma onda on qat çox məlumat var - o, fayldadır. Texniki tapşırığın mətnini çata köçürmək lazım deyil, agent faylı özü açacaq.

Faylda nəyi dəyişməli, nəyi isə sözlə demək olar. Meyar belədir: qayda və ya sərhəd dəyişibsə - faylı düzəldirik və yenidən veririk ("qələbə 1024-də yox, 2048-də" - bu, fayla gedir). Qaydalara təsir etməyən kiçik görünüş detalı dəyişibsə - sözlə demək olar ("düyməni göy et"). Şübhə edirsinizsə - fayla: artıq sətir unudulmuş qaydadan ucuzdur.

Ölçü haqqında. Kiçik iş üçün bu, yuxarıdakı 2048 bloku kimi altı-səkkiz sətirdir. Bir axşamlıq oyun üçün texniki tapşırıq iki səhifəyə uzanıbsa, çox güman ki, ona "etmirik" bölməsinə düşməli olan şeylər düşüb.

Və faylı agentə verməzdən əvvəl sonuncu şey: onu bir dəfə başqasının yazdığı mətn kimi oxuyun. Yoxlanıla bilməyən sətir demək olar ki, həmişə tapılır. mənim mətnlərimdə də tapılır.

7. Agent texniki tapşırıqla nə edir, sizə isə nə qalır

Hər şeyi bir yerə yığaq: bu sxemdə Claude Code nə edir, sizin tərəfinizdə isə nə qalır. Cüt-cüt.

Texniki tapşırığın mənası agentin başa düşməsində deyil. O, iki sözə görə də nəsə quracaq. Məna ondadır ki, siz özünüz nə sifariş etdiyinizi biləsiniz və bunu yoxlaya biləsiniz.