Аб’явленыя запрасы: спакаванне дапаможнікаў AI ад стварэння паралельнага стаку

Якщо папрашчыце асистента для кодавання «стварыць сторонку налаштоўкаў пользователя», як правілу вы отрымаеце ўсё, што можа скомпілявацца, адрасавацца і выглядае готовым. Але якщо прыглядзіцца атрымальней, часта выявіце, што ў такім кодзе є саўны склад для зберагання стану, саўныі функцыі для запрашэння дадзеных і бібліятэка для верыфікацыі, якой ваш репазітарый ніколі не выкарыстоўваў. Нічога не ламаецца, і самэ гэта ўсёліквае тое, што проблема застаецца непазначанай пад час перагляду. У этым артыкуле пояснюецца, чаму нечысткія запиты вырашаюцца так, чаму дадаванне аднародків не дапамагае, і як напісаць чысткі запит, а таксама даўаецца перадпісны список, які дапамагае заставіць створаны код у межах існуючай архітэктуры.

Як нечысткі запит вырашаецца «мягка»

Уявіце команду, яка працюе над додаткам адміністрування для клієнтав, створэным на React і TypeScript. У базе коду вже є прымітывы форм, спяльны кліент API і хук для паведамленняў. Хтось за адну короткую фразу прасіць асистента стварыць сторанку налаштаванняў. Рэзультат включае вкладкі, формы, паведамленняя у вигляде „toast“, элементы для показу стану завантажэння і маленькі хранальнік стану. Але на самай справе этыя змены не пасходзяць за правіламі базы коду:

• Стан форм керуецца бібліятэкай, якую проект не викорыстоўвае.
• Новыя кэшэры функцый fetch знаходзяцца праза спяльным кліентам API.
• Паведамленняя у вигляде „toast“ ствараюцца безпосередна, а не чераз хук для паведамленняў проекту.
• Шэмы верыфікацыі ігнаруюць структуры, якія вже з’явіліся ў каталозе types/.
• „Хранальнік налаштаванняў“ з боку кліента храніць тры поля, якія насправды патрабуюцца на сервере.
• Элементы для показу стану завантажэння не пасходзяць за дизайном решыткі.

Нічна з гэтага не вызвалі каштоўных памылак, і ўсё гэта можа перазстаць пасля швырага адзірвання, якщо толькі хтось не ачыне файл package.json. У гэтым і ўсё небяспека: нечысткія запиты прыводзяць да слабых наследкаў. Яны ствараюць другі спосаб дзеяння, які каманда вже рашыла, і кожны будучы адпаведальны за працэю спадчынае і той, і другі варыянт. Асистэнт добра справляецца з кодам, які можа бачыць; самэўсё тыя файлы, якія ён ніколі не ачынаў, вяршаюць тое, чы рэальна даная функцыя патрабуецца ў вашай працоўнай програме.

Чаму дыявальнейшы запит — гэта не рашэнне

Звычная парада — быць болей конкрэтным. Наступная, логічная спроба — прагледзець „выпрацоўаную, гатовую да выкарыстоўвання“ сторонку налашчэнняя з „чыстым інтерфейсам, хорашым TypeScript і надзеяным кераваннем памылкамі“.

Это стварае тую ж самую паралельную архітэктуру, толькі яна прыносіцца з большай уверенасцю. Словы описваюць смак, а смак дае модэлю пэўную свабоду для стварання структуры. Таго, чаго не хацелася, ніколі не было — элагантнасці. Хацелася быў межы: чысткія заставнікі пра тое, што модэль можа выкарыстоўваць, што яй не трэба дадаваць, і шта лягчыце як завершанне задачы.

Запісваўце версіі з межамі

Указаны выкладак з межамі прасіць пра тую ж функцыю, але выглядае як опис работы. У ём указаны точныя компоненты, хукі, кліент API і файлы схемы, якія можна перадаць знову, пераказаны правілы роботы з вкладкамі і надсылкай даных, заданы тэсты, а ў канцы — чысткія забораныя правілы.

Build a user settings page in React and TypeScript.
Use ONLY these existing pieces:
- `src/components/FormField.tsx`
- `src/components/Button.tsx`
- `src/hooks/useNotify.ts`
- `src/api/client.ts` (no new fetch wrappers)
- validation schemas from `src/types/userSettings.ts`
Behavior:
- Tabs: Profile, Notifications, Security
- Preserve unsaved edits when switching tabs
- Show server field errors beside the matching inputs
- Disable submit while in flight
- Ignore duplicate submits
Tests:
- loading, success, server error, duplicate click
- empty required fields
Do NOT:
- add a state-management library
- add a toast library
- create a new API client
- invent types that duplicate `src/types/userSettings.ts`

Это меньш простае запрасце, чым заставнік архітэктуры, якога мусi следаваць модэль. Параўняючы з короткім запрасцам, ён перадае семь пунктав, якія раней залишаліся на волю случая:

1. Калькі існуючыя компоненты можна перадаць знову.

Месца, дзе знаходзіцца адказгальны источнік для параболікацыі.

Правілы взаімадзеяння, такія як зберагчыце незахаваныя правкі между вкладкамі.

Месца, дзе павінны апыляцься кантакты.

Працэўнае сталянне: стан пад адработкай і дублікаў запускоў.

Тэсты, якія визначаюць, што значыць „заканчана“.

Строгія абмежэння для новых залежнасцей.

З такімі абмежэннямі результатны разлік стае досыць нудным. У ўсём викорыстоўваецца той самы FormField, той самы useNotify, той самы api/client. Вкладкі застаюцца ў своем нечыстам стане без новага хранілніка, а дублікаў запускоў карміцца за дапамогою выключанага кранку і тэсту, а не коментара „займіцца гэтым пазней“. Ужо існуючыя кодавесці маюць патэрны; задача інструкцыі — чытка адзначыць іх так, каб модэль не могла іх працягнуць.

Это таксама пояснюе, чаму апытныя разработчыкі частаюць атрымляць кращыя рэзультаты з дапаможнікамі. Їхня перадчынна — не спосаб парадкавання; гэта здатнасць заздалегідь ведаць, якія деталі маюць значэнне. Главна — граматычна структура паведамлення, а не проста адзінакаванне запиту.

Короткі тэст на частковасць

Якщо ваш запит будзе зрозумелы, калі яго скопіюваць у будзь-ям рэпазітарые ў свете, значыць я он чырвонаваўся. Хорашы запит павінен быць часткова безпарадны за межамі вашага сэрвяра, таму што ён апісвае вашы пацекі, типы і стандарты.

Перадполётны чэк-ліст для павторнага выкарыстання

Зберагчы шаблон вышэй кожнай просьбы па функцыях прывучвае нас да адпаведнага стылю. Шаблон, які знаходзится нижэй, агрупавае запытанні па кантэкст, інваріянты, поведзенне, абмежэнняі і вакуумацыю задання. Раздзел з інваріянтамі частае ўскладненне: выбор таго, чыя меркавядзіны знаходзяцца на сервере, у URL чы ў локальным стане інтерфейса, дапамага запобегчы проблеме «зберагчы тры палаткі» яшчэ до ўзнікнення.

CONTEXT
- Stack: React + TypeScript
- Relevant paths: ...
- Patterns to copy: ...

INVARIANTS
- Where does data live (server / URL / local UI state)?
- What must survive refresh?
- What is the source of truth for types/validation?

BEHAVIOR
- Happy path
- Empty / invalid input
- Server errors (field-level + form-level)
- Slow network / double submit
- Permission failure

CONSTRAINTS
- Do not add: ...
- Do not invent parallel: API client / store / toast / form lib
- Prefer editing: [files]

DONE
- Tests for: ...
- Manual checks: ...

Іспользуйце шаблон як крок параджэння гатовнасці. Якщо вы не можете запаўніць роздзелы з абмежэннямі і стосунаванымі шляхамі, вы не гатовы да стварэння коду; вы яшчэ праектаваеце. Стварэнне коду, калі проект ў стадыі праектавання, самэўсёлквае да з’явлення другой архітектуры. Стабільныя часткі гэтага списку можна разместіць у файле інструкцый для проекту; паглядзіце нашае кераванне па стварэнні эфектыўнага файла CLAUDE.md.

Што яшчэ патрэбуе чалавечага адзінакоўвання

Обмежыцьі запросаў пазбавляюць большасці шуму, але яны не заменяюць сабою суджэння. Працуячы з разлікамі, яшчэ трэба пераканацца ў наступным:

• Новы пакет, які ніхто не затвердзіў.
• Другі спосаб прыкладзення API.
• Тыпы, якія адхоююцься ад угоды з серверам.
• Стан на боку кліента для дадзэнняў, якія павінны належаць серверу.
• Тэсты, якія не пераканаюць нічога за межамі стандартнага шляху, які прыпускае модэль.

Напісанне запроса — это дыявольскай проста частка; розумеў, якія обмежыцьі важны ў гэтым кодбазе, — это складная частка, і гэтая ведомасць застаецца з камандай.

Найменскія змены, якія трэба здзейсніць сёння

Якщо цэлы список пераканаў здаецца вельмі многі, проста дадзіце тры рэчы да вашага наступнага запиту пра фічу: якія шляхі выкарыстоўваць, якія бібліятэкі не дадаваць, і як выглядае „завершэнне“, уключаючы прынаёмнае і адхоюючаеся становішча.

Use only: [paths]
Do not add: [libs]
Done when: [2–3 behaviors + one failure path]

Заключанне

• Нечыярыя запиты рэдкасцю вызываюць збоі; яны ствараюць дублікаты інфраструктуры, якія выглядаюць готовымі, але пазней коштаюць вам дорага.
• Большая колькасць адэкватыў зменяе тон выходных даных, але не ўсё іх структура. Абмежэнняя зменяюць структуру.
• Чыяры запіт прызначае назвы файлоў для падзвірнага вжывання, а таксама вказвае джерэлы правды для дадзеных і типаў, поведанне у крайніх сцэнарыях, тэсты і залежнасці, якія є недаступнымі.
• Калі модель стварае ўсё, што не падпадае під чыярыя абмежэння, спрацаваўце гэта як відсутнае абмежэнне: паспрабуйце парадкаваць запіт і стварыць даныя занову, а не толькі паспрабуйце парадкаваць формулюванні.