AGENTS.md спакет Vercel научыць дапаможнікоў AI 70 лепшых практыках использовання React
Практычны ўзгляд на аб’ект навыка react-best-practices ад Vercel, які паказвае, як ён вбудоввае 70 правіл React, перапрацаваных у рэальных умовах, безпасэчна ў код, створаны AI.
Колега з команды платформы размістіў у внутршньам канале Slack посілання без жадных адказаў — толькі сам URL і эмодзі у вигляді паднятых рук. Посіланне вела да репазітарыю vercel-labs/agent-skills, а самэй да елемента react-best-practices. Спачатку спадзяваліся, што це ўсё той жа перероблены список „Параўанні ўрабочасу React“ пад прыкметкай сучасных тэхналогій AI. Але це выявілася не так. Усё-такі, це кніга правілаў, якая налічвае 70 правілаў у 8 катэгорыях; Vercel адзначае, што яна створаная на базе мнагах гадоў спостэрэнняя за тым, як працоўныя прыкладнення на React і Next.js зламляюцца па адных і тых жа прычынах. Галоўная мета — кантульгаванне яе спачатку асистэнтам для кодавання на AI, а толькі пасля — людскім разработчыкам.
Гэты падход на самай сутнасці ў тым, што робіць гэта праект выдатным, і варта зупініцца на яму перш чым працаваць з самым тэкстам правілаў.
Што насправды ёсць у репазітарыі
Для інсталяцыі данай спэцыялізацыі патрэбна толькі адна команда:
npx skills add vercel-labs/agent-skills
У тылу кадроў гэта компілюецца у файл AGENTS.md — стандарт, які стае популярным як спосаб прынясення структураванага контексту проекта кодавальчым агентам (такія інструменты як Claude Code, Cursor, Codex і OpenCode всі шукаюць гэты файл). Калі ён будзе створаны, ваш агент будзе маць кнігу правілаў, на яю можа апісвацца пад час напісання чы рэвізіі коду, замест таго каб паследаваць выключна тым урокам React, якія знайшліся ў його данных для навчання.
70 правіл выдзелены на васьмі катэгорыяў, кожная з якіх мае пазначку прыоритэта, якая варьюецца ад CRITICAL да LOW. Две катэгорыі, пазначаныя як CRITICAL, як і можна было спадзявацца, ўважаюцца камандай Vercel галоўнымымы істочнікамі проблем у рэальных умовах: последоўныя асінхронныя операцыі, якіе ствараюць эфект «водоспаду», і неконтрольванае збільшэнне розмеру пакета. Тыповая правіла з катэгорыі «водоспаду» выражае гэту ідею так:
// Flagged: sequential awaits create a waterfall
async function getThreadPage(threadId) {
const thread = await getThread(threadId)
const author = await getAuthor(thread.authorId)
const replies = await getReplies(threadId)
return { thread, author, replies }
}
// Preferred: parallelize independent fetches
async function getThreadPage(threadId) {
const [thread, replies] = await Promise.all([
getThread(threadId),
getReplies(threadId),
])
const author = await getAuthor(thread.authorId)
return { thread, author, replies }
}
Усё гэта не ўскладненае, якщо вы вядома працавалі з React. Насправды цікавае — не сама сутнасць правілы, а тое, што ёна тепер існуе у форме, яку машына можа аналізаваць і застосоўваць аднакова ў всім кодбэсе, нават о 2 гадзіны ночы, па прыеме змян, якія ніхто не пераглядаў дакладна, без вяласці чы скарыганняў, якія з’являюцца, калі назначаны тэрмін.
Чаму гэта не так, як у лінтара
Перша рэакцыя — спадзявацца, чы не ўсё гэта проста ESLint у іншай апошніцы. У дзеярых аспектах так, але самэўпрацоўка ёсьць тым, што яго адрознівае. Лінтар выяўляе проблему пасля таго, як код вэсць ужо існуе. Цей падход прызначаны для таго, каб уплываць на код падчас яго стварэння, выяўляючы проблему ўсё раней, чым яна будзе запісана. Якщо штучны інтэлектавы асистент адпавядае за 30–60 процэнтоў разліку ў певным прыёме змян (а оцінкі гэтага паказніка сильна разлічаюцца залежна ад таго, каго запытаць у командзе), то вбудовыванне правіл працы ў сам процес стварэння — это абсалютна іншы спосаб выкарыстоўвання вліяння, у працоўнасці з выяўленням памылак пасля таго, як яны вэсць створеныя.
Існуе таксон спадчыны, якую лінтар проста не можа адекватна выразыць: архітектурныя суджэння. Правіло на кшталт «вадзіце стварэнне моделі у вигляде «водоспаду»» пры належным кастамізаванні і тольеранцы да хутароў позытываў можа быць часткова апрыксавана лінтаром. Але ўмовы на кшталт «гэты компонент, верагодна, павінен стаць серверным компонентам, адколі ён не мае інтэрактывнай прымусовасці, а межа кліента, накрэсленая навакол яго, выглядае даслідным» выклікаюць практычныя размышленні пра намеры і структуру — самэ гэтае рашэнне, якое хацелася б, каб прымеў агент, а не ўсё, што можа быць заставлена праз падпаданне пад шаблон.
Дзе прасачыцца скептыцизм
Цікава ўмова — назваць безпакойную частку прымо. Набор правіл, створаных той самыя компаніяй, якая розрабатвае фрэймворк, а чыё хостынгава платформа ў звычайных случаях адзначае певныя параметры працы, за замовчаннем не ўжо є нейтральным дакументам. Частка рэкамендацый на роўні CRITICAL, якія стосуюцца размеру пакета, занадта чыста супадае з тымі параметрамі, якія таксама дапамагаюць аналітычным панелям Vercel і ўстановкам кэшавання выглядаць чыста. Але такое супаданне не значыць, што рэкамендацыі паслабленыя. Ізбеганне асінхронных процесаў — граматычна інжынерная практыка, незалежна ад таго, хто служыць вашам прыкладку. Тым не менш, справядліва будзе памятаць, што „наяўнейшыя методы“ , створаныя постачальнікам, ніколі не ўжо є чыста тэхнічнымі рэшэннямі — завжды є лёгкі маркетынгавы налёт, які супакоўваеся разам з інжынернымі парадамі.
Другая проблема мае болей структурны характер: што будзе, калі 70 правіл ператворыцца ў 200, або калі функцыі з розных постаўчыкаў пачну заходзіць у адны і той жа файл AGENTS.md і суперсечыцца межу сабой? Зараз, калі ёсць адна база дадзеных і абэлектная концэпцыя, все выглядае апрантна і проста для разумэння. Але чыроз месцы пасля адзіннаццаці восемнацца месцаў лёгка ўявіць, што кожны фрэймворк, кожны постаўчык хостынгу і кожная система дизайна захочаць, каб яе сопныя функцыі былі інсталаваны. У такі момент ваш агент можа мусіць кераваць множынай кніг правіл з суперсучаснымі інструкцыямі, і можа не быць явнага спосабу з’ясавіць, калі тое правіло павінна мець прывілей.
Аплыненне на рэальную базу кода
З большайшаю цікавасцю, а не з прагненням даць рэштункі, гэтыя алгорытмы был прыкладзены да среднага за велічынай внутранняга панэла керування, ўпорхнуўшы пазнаць, што на самай працэ выйдзе. Результаты аналізу з категорый CRITICAL і HIGH виявіліся досыта будзь-якімі: калька последовных вызоў await, якія моглі б выконвацца паралельна, калька кліентскіх компанентаў, якія не мелі рэальнай прычыны быць кліентскімі, і адзін досыта няпрыемны прыклад, калі для форматавання аднаго толькі значэння была выкарыстоўвана цэлая бібліятэкя для обробкі дат. Нічага з гэтага не могло бы здзівіць тых, хто вже працаваў над пасібнай оптымізацыяй выконвання коду на React. Адно ж застаўся выдатным — гэта была шырока: агенту патрабавалася працоўнае чатыры хвіліны, каб знайсці і пазначыць усё гэта, на вядома як дзяўга людзкаму аналізавальніку патрабавалася бы, каб знайсці тыя ж проблемы, распаўзаныя па вялікай заявцы на перэйманне коду.
Гэта разліка ў шыроце працы ёсць справжнім ключовым прыемлівым аспектам у гэтым случае. Самыя правілы не ўнесают нічога новага — большасць апытных інжынероў вже інстынктыўна володзяць гэтай інформацыяй. Змінюецца тое, што правілы тепер застосоўваюцца з такой стабільнасцю і шыроцею, якую людзкий адгукнік, бясконечна займаны трэцім адгукам за дзень, проста не можа падтрымваць.
Недастаткова адзначаная перавага: навчанне, а не толькі прыменэнне
Тое, што насправды змяніла ситуацыю, — гэта не самыя перагляды працы, а тое, як новы член команды викорыстоўваў інструмент. Яго працаванне ў камандзе трывала лишэнь калькі месцаў, і ён яшчэ пазнаваў кодавую базу. Перад тым, як створыць запрошэнне да з’еднання коду, ён папросіў свога агента спачатку яго пераглянуць. Агент з’явіў аб’ект у формате «водоспад» і, замест таго, каб проста пазначыць гэта, поясніў простым языком — безпосередна на адной з конкрэтных правіл — чаму виконанне гэтых запытаў паралельна ёсць важлівым у даным контексте. Гэта значна адрознена ад дзейства лінтара, які выдае толькі ID правіла і стислыя паведамлення, якія потым трэба шукаты окрема. Гэта было болей схожа на коментар вышэйшага інжынера, які дае практычна корисныя працоўнія, толькі адзывы надходзілі ўсё раней, чым запрошэнне да з’еднання коду нават стаўало проектам.
Гэта можа быць болей прыемным варыянтом практычнае застосоўвання, чым фраза «Штучны інтэлект піша чыстыя кодаў». Гэта ближэй да формулы «Штучны інтэлект выучае кращыя прыкметы», які робіць гэта непаўнаважна і без патрэбы, каб хтось выдзейваў час на наставніцтво або пісаў дакументацыю для адучэння, якая за шасць месцаў становіцца застарэлай. Чы будзе гэты прынтак застаўся актуальным, калі у команды будзе пяцьдзiesць файлаў з надпісамі навыкаў — кожны з своімі мненнямі, дзеякія з яых неабходна будуць суперсечыцца — застаецца невялікай запытаннем. Але для маленькай команды, якая складаецца з аднаго апытнагі інжынера і калькі людзей, якія ўсё яшчэ шукаюць сабе месца, гэта вядома вярнуецца справжнім фактарам паўтарэння эфектаў.
Якія є наследкі
Эта спэцыялізацыя была установлена ў спакульнай настройцы команды, галоўная прычына — мінімальныя недагоды, а практычная выгода: агент, які перастае пісаць код у формате «водоспад», — гэта разумны компроміс. Чы стане гэты падход стандартным спосабам, якім фреймворкі передаюць своія інструкцыі агентам AI, чы проста стане ўсьмо толькі ўжо адной з настройчыных файлаў, якія тыхо «згніваюць», калі новасць зникне і ніхто не стане яго апдэйтаваць, паказае час. Гэта пытанне вароць рассмотрзець за шасць месцаў, а не відпавядаць на яго зараз.
Супаўзеяныя матэрыялы
- Inside TypeScript 7's Go Rewrite: Speed Gains Without Code Changes — Дазвольце дазнацца, як кампайляр TypeScript 7 на базе Go даў можлівасць ствараць проекты на 8-12 разоў быстрэй без змян у кодзе, чаму такая архітектурная змена ўспраўнела і як безпечна апдэйтаваць існуючыя проекты.