Распрацоўка па спецыфікацыях з AI-агентамі кадавання: практычны гід
Распрацоўка па спецыфікацыях з AI-агентамі: чатырохфазны працэс, файлы AGENTS.md і SPEC.md, ролі ў шматагентнай схеме, узроўні сталасці і як заўважыць дрэйф.
Крыніцы: Spec-Driven Development with AI Coding Agents: The Definitive Guide
Такі інструменты, як Claude Code, GitHub Copilot, Cursor і Windsurf, зараз ствараюць, перастраююць і тэстуюць код набліжна шырэй, чым можа любая адзіна адна особа. Аднак швальна скорасць без тачнасці часта стае прычынай проблем. Багатыя команды, якія выкарыстоўваюць гэтыя інструменты, працуюць у цыкле: задаюць запіты, атрымоўваюць рэзультаты, вылечваюць бягі і зноў задаюць запіты, і гэты цыкл стае ўсё гіршы ў меру зростання базы коду. Прычына зазвычай не ў самай модэлі. Гэта таму, што ніхто не мае дысцыплінованага спосабу, як сказаць агенту, чаго трэба.
Развіцце на адной основе спецыфікацый (SDD) — адна з апавядзін. Ён расследзвае структураваную спецыфікацыю як галоўны продукт працэсу выдачы: дакумент, з якога атрымліваецца, перакантролюецца і керуецца код.
Канцэптуальная база
Як не выйшаў кодаванне на адной атмасферы
«Кодаванне на атмасферу» значыць опіс прыямоўленага рэзультата моваючы, а таксама кераванне выходным рэзультатам за дапамою неформальных запытанняў. Гэты падход добра працуе для адзінаковых задач, шыракіх пратотыпаў і експерыментаў, якія адбываюцца за адну сесію. Аднак ён паслаба працуе у масштабных праектах, і прычына гэтага заслуговае на розумеў.
Заніканне кантэксту
Кожная сесія адбываецца ў рамках вікна кантэксту — абмежанага колькісна кола інформацыі, яку агент можа выкарыстоваць для прымецоў у адны момент. Пад час кодавання на атмасферу стан праекту існуе толькі ў історыі чату. Калі розмова практычна падае, раннія архітэктурныя рашэнні, абмежэнні ў аблэгацыі безпекі і выбор бібліятэкаў выходзяць за межы вікна кантэксту. Агент тады заменяе іх правдападобнымі альтэрнатывамі, часта не адзначаючы гэтага. Гэта і ёсць заніканне кантэксту.
Яго тыповым сімптамам ёсць адхіленае рэалізаванне: пахутнае аддаленне межы таго, што агент смяркаецца, што ён стварае, і таго, каля чаго спачатку прасіла компанія. Код пераходзіць тэсты, працуе самастаі і выглядае правільна, пры тым як нарушае структурныя або бізнес-правіла, заданы раней. У корпоратыўных сістэмах гэта тып дыфекта, які найважча да дыягназавання і найдорожэй да вылечэння.
Асновная ідэя
SDD стоіць на адной архітэктурнай прынцыпе: спецыфікацыя ёсць галоўным продуктом, а рэалізаванне выводзіцца з яе. Гэта не проста парадксальна змяна у працэсе працы. Гэта перакладвае традыцыйную мадэль на гэтычас, калі спачатку прыходзіць код, а дакументацыя следзі за ўсім.
У такым падходзе спецыфікацыя ўможліва да чытання камп’ютэрам, контролюецца па версіях, ў стані постаўлення і можа быць выканана. Яна выступае як даговор межа намерамі чалавека і выкананням агента, пры чым агент працуе ў межах умов даговору, а не прыпускае. Точны даговор дае прыкметны выхід, тады як неясны — разніцю. Корача, вы не можэце кантролюваць тое, што стварыць агент, пакуль не з’ясавіце точна, што хочаце стварыць.
Шэсць элементаў спецыфікацыі, уможлівай пры чытанні камп’ютэрам
Спецыфікацыя, прызначаная для агента, павінна пазбавіцца неяснасцяў, прынесеных нейтральным языкам. Шэсць элементаў, якія зазвычай вважаюцца неабходнымі, каб запобiec нехтарактарным прыпускам агента, ёсць:
- Рэзультаты — рэзультаты, якія павінны быць досягнутыя праз работу.
- Межы — уключаючы тое, што явна не ўключаецца.
Працэс SDD
Чатыры фазы з удзелам людзей
Процэс складаецца з чатырох последовальных фаз, і кожная з іх містыць момент, калі неабяжна участка чалавека. Шырокія пераконтроўкі з удзелам людзей не ўскладнююць працу. Яны запобегаюць таму, каб пакрыткі ствараліся ў далейшым перабегу, а прыхіленне да „шырэйшага працэвування“ часта дае працоўны эфект.
Фаза 1: адакрасаванне. Распрацоўшчык на высокам рэвэне выказвае намерэнне, а потым або агент, або сам распрацоўшчык прыводзіць яго ў форму структураванай функцыональнай спецыфікацыі: маршруты дзеяння корыстніка, бізнес-рэзультаты, крэтынія прыняцця і чысткія межы сферы дзеяння. Задача чалавека тут — архітэктурны анаіз, перачытанне рэзультата на наявнасць халюцінацый, пракрыцэнняў і неправільных тлумачэнняяў прычымо да пачатку будзь-якага планавання. Адкладзіце фазу 2 пакуль у фазе 1 не будзе неяснасцяў: нечысткая спецыфікацыя рэдка калі ведае да нечысткай рэалізацыі, а да такой, якая ўпэўнена ў сабе, але неправая.
2-я фаза, план. Пасля затверджэння спецыфікацыі агент складае тэхнічны план, які включае рашэнні па архітэктурэ, модэлі дадзэйна, контракты API і выбор тэхналогій. У плане прыменяюцься організацыйныя абмежэнні, такія як «зберагаць дадзеныя ў PostgreSQL» або «кожны канеццапункт API выклікае неабходнасць аутэнтыфікаціі JWT». Перагляд з боку людзя ў гэты момент дапамагае выявіць архітэктурныя памылкі прычымо да таго, як яны будуць запісаныя ў тыячы створаных рэядкаў.
Фаза 3, разбіўка задач. Узгоджаны план дзеляцца на маленькія задачы, кожна з якіх можа быць працавана незалежна. Разбіўка на мелкія елементы, верагатна, ёсць найменш ацэнаваным факторам у методыцы SDD. Задача павінна быць рэалізаванай і пераканальванай за адну працу агента; калі ёй трэба, каб агент адночасна кераваў болейш чым трыма рознымі аспектамі, значыць яя занадта веліка. Хораша разбіўка задач таксама служыць основай для розвіцця на основе тэстаў, адколі кожная задача мае чыстае крэатарыя на успех пры пачатку працы, а праект мае частыя пункты пераканальвання.
Фаза 4, рэалізацыя і пераканальвання. Агент пішае код задачу за задачай, ствараючы чыткі выхід, які можна аўдытаваць і прыясніць у зв’язку з конкрэтнымі вакуфамі. Што стосуецца гэтай фазы, яна выконвалася ў пары з патэрнам пераканальвання: адны агент генеруе код, а другі агент або автаматызаваны набор тэстаў пераканальвае яго за крэатарыямі прыйнятнасці.
Адаптаванне спецыфікацыі ў обох напрамках
Аднай з найважлівейшых практык, якая часта зламваная, ёсць двунаправленая адаптацыя. Падазроўцем, што ў фазе 4 агент прыме рашэнне, якое не пакрываецца спецыфікацыяй, напрыклад, выберэ бібліятэку з мотываў карыстнасці чы будзе рашаць спецыяльны кейс нестандартным спосабам. Такое рашэнне трэба негайна запісаць знову ў спецыфікацыю.
Калі гэта не так, ствараецца „заборгаванасць па спецыфікацыях“: задум, задокументаваны ў спецыфікацыі, і рэальная праця сістэмы адступаюць адзін ад другога. Гэта адступленне ператварае жывую спецыфікацыю на застарэлы файл, якому ніхто не давае доверы, і востаткі ніхто не чытае; ён стае бесполезным самэй тады, калі ён найбольш патрэбны — пад час пазнейшых змян за дапамою ШЫ. Правілле простае: калі рэалізацыя адхіляецца ад спецыфікацыі, трэба яе апдэйтаваць зараз, а не на наступным цыкле працы. Заборгаванасць па спецыфікацыях расце быстрэй, чым тэхнічная заборгаванасць, адколькі яна парадузівае тое, з чаго запускаецца кожна наступная версія сістэмы.
Артыфакты пастаноўчасці і констытуцыя праекту
Чаму агентам патрэбна констытуцыя
Агент для кодавання не мае памяці між сесіямі. Кожная новая сесія пачынаецца толькі з таго, што вы задаеце ў яе кантэкст. Без механізма зберагчэння кожная сесія ёсць чыстым аркушам, без жадных ведамае пра вашы стандарты безпекі, правілы называння, забраныя бібліятэкі чыста архітэктурныя рашэнні.
„Канстытуцыя праекту“ — гэта набор стойкіх дасягненняў, якія рашаюць гэтыя проблемы. Цэе структураваныя файлы, якія зберагаюцца ў рэпазітарыі разам з кодам, і якія даюць агенту інстытуцыйныя ведамы, каб ён могаў працаваць як член команды, які ведае усе, а не як сторонній учаснік.
Ключовыя дасягненні
AGENTS.md або CLAUDE.md – інструкцыя з эксплуатацыі. Гэта самая важная частка: README для агента, які чытаюць на пачатку кожнай сесіі, ўбачыць, як працюе конкрэтны праект. Яго трэба пісаць так, каб машыны моглі яго аналізаваць, а не толькі людзі моглі чытаць. Эфектыўны файл містыць тры відэры інфармацыі:
- Дэталі эксплуатацыі, якія агент не можа вывяліць: точныя команды пабудовы з флагамі, спосаб працы тэстаў, настройкі лінтара і назвы зменных сераўыска.
- Практыкі называння і структуры: для чаго прагаты кожны каталог, як называць файлы і як арганізаваць модулі.
.env і не змянюваць логіку аутантыкацыі без прадзеўжнага адгукі.SPEC.md — жывая спецыфікацыя. Гэта ўповажненыя апісанне таго, што сістэма павінна робіць. Гэта не історычны запіс. Яна відбівае чынную запланаваную працэздатнасць, укладаючы кожнае рашэнне, якое было прыменена пад час рэалізацыі. Калі код адхіляецца ад SPEC.md, файл апдэйтаваецца, а калі змянююцца трэбаванні, спачатку рэдагуецца SPEC.md, а потым — рэалізацыя.
PLAN.md — гісторыя архітэктуры. У яму зберагаюцца рашэнні ў архітэктурных пытаннях, выборы тэхналогій і абмежэнні для всій сістэмы. Ён адпавядае на запытанне «Чаму ўсё пабудавана так?», прыносячы паспакуйванні, якія не дазволяюць пазнейшым агентам і інжынерам скасаваць рашэнні, якія былі роблены адзяйнальна.
Файлы налашчэння, спецыяльныя для кожнага інструмента. Кожны інструмент мае свае правілы стварэння файлаў з правіламі. Фармат .mdc ад інструмента Cursor заслуговае на увагу, адколі ён спалюе Markdown з YAML-фронт-матэрыялам, ўнаследкі чаго правілы можна прыкрэпіць да шаблонаў імен файлаў. Правілы бэкенду, такія як тэрэтарыі аутэнтыфікаціі і шаблоны доступу да базы дадзеных, можна застаўляць толькі тады, калі агент працуе з файламі бэкенду, чым усунуць нерэлевантны кантэкст з яго рабочай памяці пад час работы з фронтэндам.
Оркестрацыя калькольных агентаў
Чаму аднаго агента недастатнек
Адзін агент, які выконваець задачы з усім кодавым базам прэдпрыемства, сталквецца з серьзым лімітам — вікнам кантэксту. Большая сістэма з 100 000 і болей файлоў, калькама служб, складнымі потокамі дадзэнняў і полным наборам тэстаў не можа поместыцца ў кантэкст аднаго агента. Агенту трэба выбіраць, што включыць, і гэтыя выборы ствараюць «слепыя пункты».
Ідэя мульты-агентнай оркестрацыі — гэта наследаванне прыемаў эфектывнай людскай команды, дзе ёсць чыста візначаныя ролі, адчытны перадачы задач і ўсіма прыймаемая за істыну адна спецыфікацыя.
Тры ролі
Коардынатор. Штырэнь гэты выполняе ролі менеджэра праекту і архітэктара. Ён мае цэлыя даныя пра праект: паўную спецыфікацыю, спіс задач і архітэктурныя абмежэнні. Ён дзеліць спецыфікацыю на падспецыфікацыі, перадае іх тым, хто іх адклёнуе, сочыць за суперсечаннямі між паралельнымі напрамкамі работы і стараецца, каб завершэнне адной задачы не пашкадзіла архітэктуру в цэлым.
Адклёнучы. Адклёнучыя — спецыялісты. Кожны з іх атрымлеў падспецыфікацыю, якая абходзіць адну задачу або невялікі кластэр супаўзялых задач, і працуе ў ізольаванай дрэва работы Git, тады як не можа стварыць суперсечання на рэвэлі файлоў з іншымі адклёнучымі, якія працуюць паралельна. Ён нічога не ведае пра работу паza сваім завадзеннем і не несе за ёе адпаведнасць адпаведнасці. Гэта ізоляцыя не ўскладненне — гэта тое, што робіць рэзультат дэтэрміністычным, можна тэставаць і можна пераглядаць.
Парабяральнік. Парабяральнік мае працоўны падход, працоўны ад ператворніка. Як ператворнік стараецца завершыць задачу, парабяральнік стараецца знайсці там, дзе рэзультат не паспелаў спэцыфікацыі. Такая супрацоўка запознана з формальнай парабяркі і даследжэнняў безпекі, і яна ўваходзіць у лік сэрцаўскаях механізмаў якосці, якія прысутны ў SDD. Парабяральнік тэстуе выходны рэзультат па крытэрыях прыйнятнасці і шукае функцыональныя недастаткі, наявнасць паляганняў у правілах безпекі, перакрыцця паказанняў пра выдатнасць і адхыленні ад спэцыфікацыі. Калі ён знаходзіць несувярэннасць, ён не правіляе код. Ён адправляе адпаведны атласны апісанне коордынатору, у яком усё прыкладзена да конкрэтнай вялічыны.
Для прымэнных сістэм такі адварсарыяны верыфікатор не павінен быць неабяжным. Агент, які пішае і пераканальвае свой сопрацоўны код, практычна завжды будзе ацэніваць свою работу як прыемлівую, а значэнне верыфікатора крыўцяцца ў яго незалежнасці ад таго, хто яе рэалізуе, і ў протыстоянні з ім.
Паралельная експансія з работавымі дрэвамі
Адна з найценнейшых спроможнасцэў мульты-агентных SDD — гэта паралелізм: калькі рэалізатора працуюць адночасова над разнымі функцыямі або службамі, кожны з іх у сваёй сабе работавай дрэве. Для большых праектаў з малым колькам залежнасцяў між задачамі час выпалення можа значна зменшыцца.
Git-работавыя дрэвы дазволяюць гэта. Кожны агент мае аддзельную рабочую дырэктарыю, прыўязаную да таго ж рэпазітарыя, таму ускладнення з файламі утрымваюцца, а коордынатор сочыць за прыбыллю ў всіх работавых потоках з аднаго месца. Пасля таго, як верыфікатор даў санкцыю, коордынатор злучае завершаныя работавыя дрэвы і падтрымвае чыстасцю галоўнай гілкі.
Дыяграмы як код
Чаму дыяграмы патрабуецца ў спецыфікацыі
Архітэктурныя дыяграмы традыцыйна ствараліся пасля таго, як код ужо існаваў, як дакументацыя да яго. У падходзе SDD яны ствараюцца на ранніх этапах, як частка спецыфікацыі і плану, ўсё раней, чым прыходзіць да рэалізацыі.
Прычына ціх змян — дыягнастыка. Калі ад агента запрашваецца правільная дыяграма Mermaid на адной з спецыфікацый, ён вынушаны чытра размышляць пра потокі дадзеных, залежнасцях сервісаў і пераходах стана пры напісанні коду. Неясная або некахацкая дыяграма на гэтым этапе ёсць надзеяным знакам таго, што спецыфікацыя ёсць неодназначной або структурна некорэктной, і выправленне такіх проблем у дыяграме коштае значна менш, чым ў выпусканым кодзе.
Фарматы
Фарматы на основе тэксту, усаблівае Mermaid і D2, прыграюць бінарным з’явам для гэтай мэты. Іх можна версіяваць і пораўнюваць, а агенты можаць чытаць іх безпосерэдна. Іх таксама можна апдэйтаваць па меры развіцця спецыфікацыі, што дапамагае падтрымваць структурную дакументацыю і рэалізацыю ў адпаведнасці.
Тры рэвэлюцыі готовасці
Эксперты выбралі тры рэвэлюціі SDD. Гэтыя рэвэлюціі не ўтвараюць лесвіцы, якую кожная каманда павінна працягваць па парадку. Гэта разныя варыянты компромісаў для разных супаконтактаў, і важліва знайсці той варыянт, які падходзіць вашай сітуацыі, прычымо да якога-лібо запуску.
Рэгламент 1: спачатку спецыфікацыя. Для адзінаго заведама праблемы пішаецца дакладная спецыфікацыя. Калі рэалізацыя завершана і пераканана, спецыфікацыя спрацоўвае як тымчасовы документ: яго можна заставіць для аднаго кансультавання, але яго не падтрымваюць. Ён падходзіць для адзінаковых функцый, експерыментаў і разовых міграцый, калі падтрымка рэгламента 2 няўяўна. Яго падтрымальнікі ствараюць, што гэты рэгламент даўа прыблізна 60% цяніноў SDD за значна меньшыя затраты, што робіць яго разумным пачатковым пунктом для новачакоў. Ожывайце яго для новай функцыі з чысткімі крытэрамі адзымкі, без залежнасцей між службамі, пры чым час выдання лічыцца за дні.
Рэгламент 2, адаснованы на спецыфікацыі (рэкамендаваны стандарт). Спецыфікацыя ўсё час застаецца роўным партнерам коду працаваючы ўсю трываласць праекта, і якія-то з іх стаяцься падтрымкай. Калі змянююцца трэбаванні, спяцыфікацыя змінюецца першая, а калі рэалізацыя адхіляецца, спецыфікацыя негараздо апдэйтуецца, каб зафіксаваць рэальную працэю і праблемы, якія яе вызвалі. Гэта выглядае як двойная падтрымка, але на практыцы гэта зніжвае загальныя вітраты: гэта запобегае занепаду кантэксту між сесіямі, дазволяе новым члэнам команды (людзям і ШЫ) эфектываўна інтэгрувацца, а таксама робіць пазнейшыя змяны з адказам ШЫ надзейнейшымі. Гэта ёсць базовы прынцып для прымэнных сістэм, камандных праектаў і всьго, што мае продовжваць развівацца.
Рэгламент 3, спецыфікацыя як адказ (экспэрыментальны). Спецыфікацыя ўсё жа ёдын галоўны даслед. Код спрацоўваецца як скомпіляваны выхід, генеруецца за патрэбай і ніколі не рэдагуецца вручную. Гэта тэарэтычны канец SDD: інжынеры адпавядаюць за спецыфікацыі, а ШЫ — за ўтылізацыю. У гэтым падходзе існуе нерашаная проблема — дэтэрмінізм. Аднаковыя спецыфікацыі могу даўаць сінтаксычна разны, хоць і функцыянальна эквівалентны код у розныя запускі, што значна ускладнюе стварэнне разніц, адлагоджэнне і перагляд. Спрацоўваць з гэтым падходам трэба як з экспэрыментам. Ён можа падходзіць для праектаў з абмоўленаямі спецыфікацыямі, сільным кераваннем за дапамогою ШЫ і толерантнасцю да незрэлых інструментаў, але як на 2026 год не рэкамендуецца для крытычных прыёмных сістэм.
Інструкцыі па ролі
Інжынеры і архітэктары
Галоўныя навыкі інжынера пераключаюцца на інжынерыю кантэксту. Складанне правільнай сінтаксісу — гэта тое, што агенты выконваюць з машынной швальнай, таму ценнасць інжынера крыўцяцца ў візначэнні точнага архітэктурнага кантэксту, підборэ таго, што можа бачыць агент, і перакананні, што яго выход падходзіць да структурных цялей сістэмы. Гэта включае стварэнне якісных файлаў AGENTS.md і SPEC.md, встановленне правіл керавання бібліятэкамі (явнага спісу дазволеных і забраных залежнасцей), апісанне вакуфаў безпекі і супакоўкі ў фармаце, чытаемым машынай, а таксама структуруванне задач так, каб прыбліжанні заставаліся аддзельнымі.
Прыемны рутын для інжынераў:
- Перад стварэннем будзь-якай функцыі за дапамогай ШЫ, створыце або апдэйтаваце SPEC.md, каб у яму былі шэсць раней опісаных элементаў.
- Перагляньце AGENTS.md і пераканацеся, што команды будовы, шаблоны тэставання, правілы называння і іерархія сур’ёзнасці ўсё ўсё адпавядаюць рэальнасці.
Блок з абмежэннямі — годны шаблон, які можна дадаць у будзь-які гайдлайн. У ём указваецца тэхнічны стак (кожная неабходная тэхналогія), забраныя бібліятэкі (з перапісам), трэбованні да безпекі (як корыстувальнікі аўтэнтыфікуюцца, які шыфраванні ўжоўваецца, як можна обрабляць даны), ліміты працызледжання (цэльвыя часы адпаведзі і працызледжання), трэбованні да тэставання (праграма пакрыцця і тыпы тэстаў, якія неабходны) і архітэктурныя шаблоны (тые, якія неабходны, і тые, якіх трэба ухіліцца).
Тэхнічныя менеджэры продуктам
З PRD-аў да інструкцыйяў па поведзінцы. Класычны документ з вакуумаў продукту прыпускае, што яго буду чытаць, обгаварываць і рэалізаваць інжынеры, якія карыстаюцца сабой разумам. У падходзе SDD выходны дакумент TPM павінен стаць інструкцыяй па поведзінцы – машынным чытальным опісам таго, як продукт павінен рэагаваць на конкрэтныя патрэбныя корыстувальніка, з точнаю інформацыяй пра тыя вімаганні, якія ставяе ўпрыемнік.
Разлік не толькі у стылі. PRD можа сказаць "падбадзіць апыт пракупкі". Інструкцыя па поведзінцы павінна чытальна апісаць, што робіць нынешні працэс пракупкі, якія проблэмы корыстувальнікаў ён стварае, якія змяны паведзінкі лягаюць у базу падбадроўкі, як вяршыну меркуюць, якія крайнія случаі павінны быць адрабоўваны і чаго сістэма ніколі не павінна робіць.
Цыкл протатыпаў. SDD дазволяе TPM скорачыць звычны пераход ад праектавання да інжынернай працы. У замест на чаканне макетаў ад дызайнера і ўсунення іх інжынерам, TPM можа ствараць інтэрактывныя протатыпы непасрэдна на адной з апісаў поведзення і ацэніваць ўжоцьвярнутае поведзенне, а не статычныя экраны. Калі протатып не падпадае пад задум, спецыфікацыя адкорэгуецца, а агент зноў стварыць рэалізацыю, такім чынам цыкл зворачнай свярзанасці працюе на адной з спецыфікацый, а не на кодзе. Гэта усуне калькі ліній перакладу (PRD, потым пераход пра праектаванне, потым пераход пра інжынерную працу), дзе намеры часта трапляюцца змішаныя.
CTO і керавальнікі інжынернай часткі
Управленьне. Адміністратыўны прыорытэт тэхнічнага дырэктара ў арганізацыі, якая ставіць агенты на першае месца, — гэта рамкі управленьня, якія дазволяюць штучнаму інтэлекту прышвыдзіць працэс рэалізацыі без падрыву якосці, безпекі чыста супакоўкі з правіламі. SDD забезпечвае шар кантролю, але толькі за наявнасці організацыйнай дысцыпліны. У масштабных праектах важлівыя тры механізмы:
- Кантроль версій спецыфікацый. Файлы SPEC.md, PLAN.md і AGENTS.md знаходзяцца ў тым жа рэпазітарыі, чым код, і праходзяць тыя ж процедуры перагляду і затверджэння.
- Хронікі аўдыту. Кожная змяна, створаная штучным інтэлектам, должна быць прыязначаная да конкрэтнай вімогі спецыфікацыі, што ў рэгулююцыхся галузях не ёсць неабяжным.
- Людзкі контроль на кожным етапе пераходу. Нічога не можа автонамна перэйсці з етапу спецыфікацыі на етап планування і далей на етап рэалізацыі без затверджэння на кожным кроцы.
Кінцавыя адпаведальнікі за тэхналогіямі таксама должны ацэніць інструменты для програмавання на асоцыяцыі інтэлекту пры выкарыстоўванні гэтай рамкі, спытваючы, насколькі добра кожны з іх падтрымлівае постацейныя файлы правілаў, працэсы перагляду, возможнасць трасування і рабочыя працэсы з удзелам калькольніка агентаў.
Ацэнка рэзультатаў. Арганізацыі, якія адмашчваюць SDD, часта адзвярцаюцься, што праца над разработкай здаецца медленнейшай прыблізна прыблізна першыя два-чатыры тыдні, таму што інжынеры выдзеляюць час на стварэнне спецыфікацый замест таго, каб адразу працаваць над кодам. Гэтае спазіраванне праведна, але яго інтэрпрэтацыя вводзіць у глухы кут. Работа над спецыфікацыямі — гэта не новы додатковы трыбут. Гэта праца, якая раней выконвалася неформальна, нэпаспэчна і пасля рэалізаціі, калі ўсё гэта коштаў кроў. Паказнікі, якія паказваюць рэальны рэзультат, знаходзяцца пасля гэтага этапу:
- выцік часу ад стварэння тэрэўіні да готовага да выкарыстоўвання коду, тыям самым пераверанага, пераглянутага і размішчанага, а не проста напісанага,
- Процэнт пераробкі — частка завершаных функцыйяў, якія павінны быць пераробленыя з-за няправільнага разумення трэбаванняў,
- Час вярнення да працы — час, якія распрацоўшчыку або агенту трэба, каб стаць продуктывым з коду, які не правільнікаваўся працоўнік 30 дзён, і
- Рэшткавае частка дыфектаў — частка дыфектаў, якія былі выявленыя пад час перагляду спецыфікацыі, у працоўнасупораненні з тымі, якія з’яўляюцца пасля развяртання.
Як паведамляецца, каманды, якія апышваюць зрошаныя практыкі SDD, бачаць зніжэнне пераробкі на 40-60% і рошчыцу часу вярнення да працы, адколі спецыфікацыя забезпечвае неабходны кантэкст, які інакш заставіў бы гадзіны на аналіз коду. Гэтыя цыфры выйшлі з аповешчэнняў практыкантав, а не з контрольваных даследжэнняў, таму вырахавайце сабе базовыя показнікі.
Зміна намеру
Што гэта такое
Змішанне выконанне — гэта павольны прыем між первачнымі трэбаваннямі бізнесу і працэю коду ў працэйнай асяроддзі. Гэта не ўпершыню для працы з дапамогою ШЫ і ўзялося адна з старэйшых проблем інжынерыі програмнага забезпечэння, але агенты для кодавання ствараюць небяспечны прышвартківацы фактар. Яны оптымізуюць код для правдопадобнасці і пасавання тэстаў, а не для адпаведнасці бізнес-трэбаванням. Калі папросіце агента стварыць сістэму для апрацоўкі платэжаў, ён напісае код, які пасавае ўсе тэсты і пакрывае ўсі заданыя кейсы. Калі спецыфікацыя непূраная або застарэлая, агент заполняе прыемы статыстычна верагоднымі стандартамі з своіх дадзеных для навчання. Гэта падходзіць для генерычных сістэм, але можа стаць катастрофічным для вашых конкрэтных бізнес-правіл. Найгоршыя формы змішанага выканання — гэта тые, якія з’яўляюцца толькі тады, калі гэта коштуе кліента, аўдыту выпаведкі аб інцыдэту ў працэйнай асяроддзі, таму што агенты дужа добра ствараюць код, які выглядае правільным, але ў той жытак ёсць незначна некорэктным.
Захопы
- Жывая спецыфікацыя. Першы захоп — гэта спецыфікацыя, якая апдэюўаецца ў рэальны час па меры прымэння рашэнняў. Кожны адхылэнне ад файла SPEC.md, незалежна ад таго, насколькі ён маленькі чы абгрунтаваны, негайна фіксуецца, таму файл завжды опісвае потычнае паведанне, а не первачную мету.
- Перакананне протыўнікам. Мадэль пераканання выконвае таксама функцыю выявлення адхылэнняў. Перакананне выходных даных адносна спецыфікацыі па кожнай задачы дазволяе выявіць адхылэння ў найменшым можлівым масштабе, перш чым яны накаплююцца за калькі цыклів рэалізацыі.
- Адстаўленне ад крытычных пунктав спецыфікацыі. Болей прыглушаныя расклады сочыць за часткай трэбаванняў, якія маюць аўтаматызаваныя, перакананыя тэсты. Трэбаванне без тэста можа адхыляцца непазначана, а прагненне да повнага адстаўлення — гэта развіцце на адварце тэстаў, прыменяванае на рэвэлікацыі трэбаванняў.
Мінімальны AGENTS.md
Файл AGENTS.md, готавы ў выпуску, можа быць короткім. Як мінімум, ён павінен уключаць апісанне праекта ў аднам абзаце, точныя команды для стварэння, тэставання і перагляду коду, правілы называння і структуры дырэктарыяў, спісы «заўжды», «спачатку запытайце» і «ніколі», паўязі на файлы SPEC.md і PLAN.md, а таксама правілы керавання бібліятэкамі. Адаптавайце кожную частку да вашага стэку і трэбаванняў вашай організацыі.
Што застаецца пасля гэтага
Развіцце на адной основе спецыфікацый — гэта не тымчасовая мода чы незначныя прадуктыўныя паліпшэнні існуючых прычындалаў. Гэта зміняе сэрвіс складання програмнага забавы. За дапамогою агентаў-програмістаў вузькія месцы ў працэсе выдачы продукту больш не становіць швальнасць стварэння сінтаксісу; гэта швальнасць точнага адзначэння намеру. Спецыфікацыя ёсць самым продуктом, код — тым, што яго рэалізуе, а ў працэсе стварэння програмнага забавы на адной основе спецыфікацый спецыфікацыя ёсць найважлівейшым рэзультатам работы інжынера.
Супаўязаныя матэрыялы
- Практычныя прытамулы: Я запускаю агента для кодавання на AI локальна і ўсяго ў два разы — Паследовыя інструкцыі па прытамулах: Я запускаю агента для кодавання на AI локальна і ўсяго ў два разы: контракты, перакрыццяі і месцы для коду для команд, якія вікорыстоўваюць гэты патэрн.
- Інжынерыя агентав: пяць слоёў — ад спецыфікацый і паралельных агентав да правіл і нагляду — Карпаты распісаў пераход ад старога стылю кодавання. Пазнайоміцеся з пяцьма слоямі інжынерыі агентав: спецыфікацыі, оркестрацыя, кодаваныя правілы, людская пераглядка і можлівасць назірання, а таксама план на тыдзень.