Ograniczone polecenia: powstrzymywanie asystentów AI przed tworzeniem równoległych struktur danych

Zapytaj asystenta do programowania o „stworzenie strony ustawień użytkownika” i zazwyczaj otrzymasz coś, co kompiluje się, renderuje i wygląda na gotowe. Przy bliższym przyjrzeniu się okazuje się, że często zawiera on własny magazyn stanu, własne narzędzia do pobierania danych oraz bibliotekę walidacji, której twój repozytorium nigdy nie używało. Nic się nie psuje, i to właśnie dlatego problem umyka podczas przeglądu. Ten artykuł wyjaśnia, dlaczego niejasne prośby kończą się w ten sposób, dlaczego dodawanie przymiotników nie pomaga oraz jak napisać precyzyjne polecenie, wraz z listą kontrolną do ponownego użycia, która zapewnia, że generowany kod pasuje do istniejącej architektury.

Dlaczego niejasne prośby kończą się bez większych problemów

Załóżmy zespół pracujący nad aplikacją administracyjną dla klienta stworzoną przy użyciu React i TypeScript. Baza kodu zawiera już elementy formularzy, wspólnego klienta API oraz hooka do wyświetlania powiadomień. Ktoś prosi asystenta o stronę ustawień w jednym krótkim zdaniu. Wynikiem są karty, formularze, komunikaty typu toast, elementy tymczasowe podczas ładowania oraz mały magazyn stanów. W tle ta zmiana po cichu koliduje z obecną bazą kodu:

• Stan formularzy jest zarządzany za pomocą biblioteki, której projekt nie używa.
• Nowe narzędzia do żądania danych znajdują się obok wspólnego klienta API.
• Komunikaty toast są tworzone bezpośrednio, zamiast przechodzić przez hook do wyświetlania powiadomień projektu.
• Schematy walidacji ignorują struktury już zdefiniowane w katalogu types/.
• „Magazyn ustawień” po stronie klienta przechowuje trzy pola, które w rzeczywistości powinny znajdować się na serwerze.
• Elementy tymczasowe podczas ładowania nie pasują do reszty interfejsu.

Żadna z tych sytuacji nie powoduje błędu i może przetrwać szybką weryfikację, chyba że ktoś otworzy plik package.json. W tym właśnie tkwi niebezpieczeństwo: niejasne instrukcje powodują łagodne problemy. Wprowadzają one drugi sposób wykonywania czegoś, co zespół już rozwiązał, a każdy przyszły administrator musi radzić sobie z oboma rozwiązaniami. Asystent radzi sobie dobrze z kodem, który może zobaczyć; to pliki, których nigdy nie otworzył, decydują o tym, czy dana funkcja rzeczywiście pasuje do twojej aplikacji.

Dlaczego dłuższa instrukcja nie jest rozwiązaniem

Zwykłą radą jest bycie bardziej konkretowym. Naturalną drugą próbą jest poproszenie o stronę ustawień „wykończoną i gotową do użycia w produkcji” z „czystym interfejsem użytkownika, dobrym TypeScriptem oraz solidnym obsługą błędów”.

To daje tę samą architekturę równoległą, tylko przedstawioną z większą pewnością siebie. Słowa opisują gust, a gust pozostawia modelowi całkowitą swobodę w tworzeniu struktury. Tym, czego brakowało, nie była elokwencja – chodziło o granice: wyraźne zasady dotyczące tego, co model może użyć, czego nie powinien dodawać oraz co stanowi ukończenie zadania.

Pisanie wersji ograniczonej

Poniższy, ograniczony prompt prosi o te same funkcje, ale jest sformułowany jak opis stanowiska pracy. Wymienia dokładne komponenty, hooki, klienta API oraz pliki schematu do ponownego użycia, opisuje zachowanie w zakresie kart i wysyłania danych, definiuje testy i kończy się wyraźnymi zakazami.

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`

To raczej nota architektoniczna, której model musi się trzymać, niż lepszy prompt. W porównaniu z wersją jednowierszową komunikuje siedem rzeczy, które wcześniej były pozostawione przypadkowi:

1. Które istniejące komponenty należy ponownie wykorzystać.

Miejsce, w którym znajduje się źródło prawdy służące do walidacji.

Zasady interakcji, takie jak przechowywanie niezapisanych zmian pomiędzy kartkami.

Miejsce, gdzie powinny pojawiać się błędy.

Zachowanie konkurencyjne: stan w trakcie przetwarzania i podawanie danych wielokrotnie.

Testy, które określają, co oznacza „zakończenie”.

Bezzwrotne zatrzymanie dodawania nowych zależności.

Dzięki tym ograniczeniom uzyskany rozbieżność staje się przyjemnie nudny. Wykorzystuje ten sam FormField, tę samą funkcję useNotify, ten sam api/client. Kartki zachowują swój nieuporządkowany stan bez konieczności tworzenia nowego magazynu danych, a podawanie danych wielokrotnie jest radzone poprzez wyłączony przycisk i test, a nie komentarz typu „zajmę się tym później”. Istniejące bazy kodowe już zawierają odpowiednie wzorce; zadaniem instrukcji jest wskazanie ich tak wyraźnie, aby model nie mógł ich przeoczyć.

To również wyjaśnia, dlaczego doświadczeni programiści zazwyczaj osiągają lepsze rezultaty dzięki asystentom. Ich przewagą nie jest sformułowanie zdań, lecz umiejętność wcześniejszego rozpoznania, które szczegóły mają znaczenie. Ważne jest komunikowanie architektury, a nie dekorowanie instrukcji.

Szybki test ograniczeń

Jeśli twoja instrukcja miała sens po wklejeniu do dowolnego repozytorium na świecie, oznacza to, że jeszcze nie ma ograniczeń. Dobra instrukcja powinna być nieco bezużyteczna poza twoim własnym drzewem źródłowym, ponieważ odnosi się do twoich ścieżek, typów i konwencji.

Przydatna lista kontrolna przed użyciem

Zachowanie szablonu nad każdym żądaniem funkcjonalnym sprawia, że taki styl staje się nawykiem. Ten poniżej grupuje pytania według kontekstu, niezmienników, zachowania, ograniczeń oraz definicji ukończenia pracy. Sekcja niezmienników jest najczęściej pomijana: decyzja o tym, czy dane znajdują się na serwerze, w URL czy w lokalnym stanie interfejsu, zapobiega pojawieniu się problemu „przechowywanie trzech pól” jeszcze przed jego wystąpieniem.

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: ...

Wykorzystaj szablon jako bramkę gotowości. Jeśli nie możesz wypełnić informacji o ograniczeniach i odpowiednich ścieżkach, nie jesteś gotowy do generowania kodu – nadal projektujesz. Generowanie kodu, gdy projekt jest jeszcze w fazie koncepcyjnej, to właśnie sposób, w jaki pojawia się druga architektura. Stabilne elementy tej listy kontrolnej mogą znajdować się w pliku z instrukcjami projektu; zapoznaj się z naszym przewodnikiem dotyczącym pisania skutecznego pliku CLAUDE.md.

Co nadal wymaga ludzkiej oceny

Wskazówki z ograniczeniami eliminują większość zbędnych elementów, ale nie zastępują osądu. Przy sprawdzaniu różnic należy nadal sprawdzić:

• Nowy pakiet, który nikt nie zatwierdził.
• Inny sposób wywoływania API.
• Typy, które odbiegają od umowy serwera.
• Stan po stronie klienta dla danych, które powinien posiadać serwer.
• Testy, które nie sprawdzają nic poza scenariuszem sukcesu założonym przez model.

Pisanie wskazówek to tańsza część; zrozumienie, które ograniczenia są istotne w tym kodzie, to droższa część, a ta wiedza pozostaje z zespołem.

Najmniejsza zmiana do wprowadzenia dzisiaj

Jeśli pełna lista kontrolna wydaje się zbyt obciążająca, dodaj do swojej następnej prośby o funkcję zaledwie trzy linijki: jakie ścieżki używać, które biblioteki nie dodawać oraz jak powinien wyglądać wynik „gotowe”, włączając przynajmniej jeden scenariusz niepowodzenia.

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

• Niejasne instrukcje rzadko powodują błędy; tworzą one dublowaną infrastrukturę, która wygląda na gotową, ale później przysparza kosztów.
• Instrukcja o określonych ramach określa nazwy plików do ponownego użycia, źródło prawdy dotyczące danych i typów, zachowanie w skrajnych przypadkach, testy oraz zależności, które są niedozwolone.
• Gdy model wymyśla coś poza ustalonymi ramami, traktuj to jako brakującą granicę: popraw instrukcję i wygeneruj wynik na nowo, zamiast dopracowywać sformułowania.

• Utrzymywanie hooki bez głowy: oddzielanie zachowania alerty od jej renderowania — Dowiedz się, dlaczego hook w React, który zwraca JSX, ukrywa część drzewa komponentów i łączy zachowanie z prezentacją, oraz jak przeprojektować go tak, by zamiast tego eksponował stan.
• Kierowanie agentami programistycznymi-AI za pomocą czterech nazwanych wzorców architektury React — Poznaj cztery wzorce w React (składanie sekcji, niestandardowe hooki, komponenty polimorficzne, reduktory) oraz to, jak nadawanie im nazw w instrukcjach pozwala uzyskać czystszy kod generowany przez AI.