Саған өтірік айтпайтын Claude Code агенттерін қалай жазу керек

Сен Claude Code-қа осы дизайнды жүзеге асыруды және оның Figma макетіне сәйкес келетінін тексеруді тапсырдың. Ол былай деп жауап берді: Дайын. Барлық бөлімдер сәйкес келеді, аралықтар дұрыс, түстер орнында. Бетті аштың. Аралықтардың жартысы қате болды. Hover күйі мүлде жоқ еді. Түймелер бір реңкке ауытқыған. Модель қасақана өтірік айтқан жоқ — ол сенің тексерілді дегенді естігің келетінін болжады да, дәл сол токендер тізбегін генерациялады. Тексеру қадамы болған жоқ. Ол болуы да мүмкін емес еді — тексеру ground truth-пен салыстыруды талап етеді, ал бір контексттегі жалғыз агент өз жауабынан шығып, өзін тексере алмайды.

Екі ереже менің галлюцинацияға толы жұмыс ағындарымды сенімді пайплайндарға айналдырды: бір агент — бір мамандану және shell командасы ретінде орындалатын кез келген нәрсе shell командасы ретінде орындалуы тиіс. Бұл теория емес. Бұл — менің Claude Code-пен күнде істейтін ісім, әрі шын мәнінде нәтиже беретін паттерндер осылар.

Неге жалпы бейінді агенттер өтірік айтады

LLM — келесі токенді болжайтын жүйе. Промпт екі рөлді сұрағанда — X-ті құрастыр және X-ті тексер — модель бірінші рөлді аяқтайды да, екіншісінің шығысы қалай көрінетінін оны шын орындамай болжайды. Өзін-өзі тексеру құрылымдық тұрғыдан әлсіз: сол контекст, сол модель, сол соқыр аймақтар. Тексерудегі өтті құрастырудағы өтті дегенмен корреляцияланады — олар бірге сәтсіздікке ұшырайды.

Модель өзінің өтірік айтып жатқанын білмейді. Оның көзқарасы бойынша мен бәрін мұқият тексердім дегені мен кодты жаздым дегеннің дәйекті жалғасы. Сенімдісің бе? деген промпттердің галлюцинацияларды ұстай алмайтын себебі де осы: модель екінші жүрісте де дәл сондай сенімді. Сенімділік дұрыстықпен емес — келесі сөйлемнің қаншалықты сенімді естілетінімен корреляцияланады.

Шешім — жақсырақ промпт емес. Абай бол, қайта тексер, галлюцинация жасама — бұл нұсқаулар ештеңе бермейді. Шешім құрылымдық: агентті физикалық тұрғыдан жалған сыңай таныта алмайтындай етіп мамандандыр және сандық жұмысты shell арқылы жүргіз, сонда жауап токен ықтималдығынан емес, нақты күйден келеді.

1-ереже: бір агент — бір мамандану

Жұмысты бөлек контексттері бар бөлек агенттерге бөл. Әр агентте жалғыз жауапкершілік пен тар құралдар жиыны бар. Бүкіл ағын шеңбер бойымен жүгіретін бір агенттің орнына эстафетаға айналады:

• Builder агенті: spec-ті алады, кодты жазады. Оның бар жұмысы осы. Оның Read, Edit, Write, Bash құралдары бар.
• Reviewer агенті: spec-ті және diff-ті алады, қабылдау критерийлерін тексереді. Таза контекст. Кодтың қалай жазылғанын білмейді — тек не шыққанын ғана. Оның Bash, Read, Grep, Glob құралдары бар — жазу құралдары мүлде жоқ.
• Analytics агенті: сұрауларды құрастырып әрі орындау арқылы деректер туралы сұрақтарға жауап береді. Тек Bash. Нақты команданы орындамай жауапқа жете алмайды.
• Оркестратор: әр агентті кезекпен жіберетін және бір агенттен ешқашан екіншісінің жұмысын істеуді сұрамайтын негізгі сессия.

Нақты мысал: UI жүзеге асыру плюс Figma макетіне қарсы визуалды тексеру. Builder компоненттерді жазады да, diff-ті commit жасайды. Одан кейін оркестратор reviewer-ді дизайн URL-імен, diff-пен және нақты қабылдау критерийлерімен шақырады. Reviewer Playwright-ты іске қосады, скриншоттар түсіреді, оларды эталонмен салыстырады және нақты скриншот жолдары мен пиксель айырмашылықтарымен PASS немесе FAIL қайтарады. Builder тексеру қадамына мүлде жақындамайды — тексерудің шынайы болатын себебі де нақ осы.

Анти-паттерн — бұл мега-агент: осы UI-ды құрастыр да, оның макетке сәйкес келетініне көз жеткіз дейтін жалғыз промпт. Кепілдік беремін — ол бәрі сәйкес келеді деп хабарлайды. Сәйкес келмейді. Мен тексердім деген баяндау — бұл жай ғана мен құрастырдым дегеннен кейінгі ең ықтимал токендер тізбегі.

2-ереже: әрдайым промпттың орнына shell

Сандық барлық нәрсені, нақты күйге қатысты барлық нәрсені, жауабы дұрыс көрінгенімен қате болуы мүмкін барлық нәрсені — sh арқылы жүргіз. Агенттің жұмысы — команданы құрастырып орындау, содан соң оның шығысын оқу. Ақиқат көзі агент емес. Shell шығысы.

• Санау: wc -l logs.txt — шындық. Модельден шыққан шамамен 47 лог жолы бар дегені — галлюцинация.
• Analytics: psql -c "SELECT count(*) FROM events WHERE created_at > now() - interval '30 days'". Көлемін бағала емес.
• Тесттер: pnpm test --reporter=json | jq '.numFailedTests'. Не сәтсіз болғанын қорытында емес.
• Git күйі: git rev-list --count main..HEAD, git diff --stat. Коммиттерді сана немесе өзгерістерді сипатта емес.

Мұны бойыңа сіңіргеннен кейін агент санды ойдан шығаруға дайындалған әрбір орынды байқай бастайсың. Мұнда шамамен 200 жазба бар сияқты... — жоқ. SELECT count(*) орында. Тесттердің көбі өтеді... — жоқ. Тест жиынтығын іске қос, JSON-ды талда. Модель команданы құрастыруда керемет. Ал команданың өзі болуда сенімсіз.

Өзім тап болған сәтсіздік режимдері

Бұлар — болжамды мысалдар емес. Паттернді өзгертпей тұрып, олардың әрқайсысы маған нақты уақытыма шығын әкелді:

• Елес тексеру. Агент мен 14 бөлімнің бәрін макетпен салыстырып тексердім деді. Ол макетті ашпады. Скриншот түсірмеді. Тексеру — баяндаудағы галлюцинацияланған қадам болды.
• Сенімді айтылған қате сандар. Analytics деректерінен monthly active users сұрадым. Шамамен 3× қателескен сан алдым. Модель нақты сұрауды орындаудың орнына үлгі жолдардан интерполяция жасады.
• Ойдан шығарылған файл өзгерістері. Агент мен config/feature-flags.json файлын жаңарттым деді. Жаңартқан жоқ. Ол тек ниеттенген еді. git diff бос болды.
• Жалған тест жүгірулері. Барлық тесттер өтеді. Бірде-бір тест орындалмады. Агент test runner-ді ешқашан шақырмады — ол runner шығысының қалай көрінетінін болжады.

Төртеуі де сол екі ережемен шешіледі: агентті бөл, shell-ге ысыр. Reviewer-де Write жоқ, сондықтан ол файлдарды жалған өңдей алмайды. Analytics агентінде тек Bash бар, сондықтан ол сұраудан келмеген санды қайтара алмайды. Құрылымдық мүмкін еместік ізгі ниеттерді әрдайым жеңеді.

Мұны Claude Code-та қалай құрылымдау керек

Claude Code .claude/agents/*.md ішінде анықталатын sub-agent-тарды қолдайды. Әр агент файлы атауды, сипаттаманы, рұқсат етілген құралдар жиынын және жүйелік промптты жариялайды. Оркестратор (сенің негізгі сессияң) оларды Agent құралы арқылы жібереді. Мен reviewer үшін қолданатын анықтаманың түрі мынадай — қысқа, тар және код жазуға физикалық тұрғыдан қабілетсіз:

---
name: reviewer
description: Reviews a diff against acceptance criteria. Cannot edit code.
tools: Bash, Read, Grep, Glob
---

You are a strict code reviewer. You receive:
- A diff (already produced by the builder)
- Acceptance criteria

Your job:
1. Run the build, the tests, the linter — through Bash.
2. Read the changed files directly.
3. Compare the actual behavior to the criteria.
4. Report PASS or FAIL with concrete evidence (command output, file excerpts).

You must NOT:
- Trust the builder's summary
- Assume anything was verified just because it was claimed
- Mark something PASS without running the actual check

Құралдар жиынына назар аудар: Bash, Read, Grep, Glob. Write жоқ, Edit жоқ, Agent жоқ. Reviewer командаларды орындай алады, файлдарды оқи алады, паттерндерді іздей алады — басқа ештеңе жоқ. Егер ол галлюцинацияланған diff-ті тексерілген деп өткізуге әрекеттенсе, оның құрал шақыруларының пішіні мұны айқын көрсетеді: нақты тексерулер болмаған. Құрал шақыруларын аудиттеп, нақ не тексерілгенін көре аласың.

Оркестрация паттерні: негізгі сессия Builder-ді шақырады → күтеді → нақты өзгерісті қармау үшін git diff-ті өзі орындайды → Reviewer-ді spec-пен және diff-пен шақырады → үкімін оқиды. Негізгі сессия бір агенттен ешқашан екеуін де істеуді сұрамайды. Құрал шектеулері промпт нұсқауларынан күштірек: тексеруді жалғандама — бұл тілек. Write-тың болмауы — бұл факт.

Тастау керек анти-паттерндер

Промпттерде көретін, ешқандай әсері жоқ — немесе одан да жаманы, жалған қауіпсіздік сезімін беретін нәрселер:

• Абай бол және жұмысыңды қайта тексер. Ешқандай қосымша мінез-құлық тудырмайды. Модель мұқият жұмысқа ұқсайтын нәрсені бұрыннан-ақ шығарады.
• Шынымен тексергеніңе көз жеткіз. Шынымен деген сөз модель әрекет ете алатын семантика қоспайды. Ол шынымен тексердім деп мәлімдейді.
• Галлюцинация жасама. Prompt engineering мемі. Галлюцинация — модель өшіре алатын ауыстырғыш емес.
• Агентке кіші сандарда сену. Дәл кіші сандарда ол ең сенімді түрде өтірік айтады. Адалдықтың табалдырығы жоқ.
• Адалдықты мәжбүрлеу үшін промптқа қосымша ережелер қосу. Құрылымдық түзетулер (бөлу + shell) промпт өзгертулерін әрдайым жеңеді. Егер ережені орындату қажет болса, оны қазақ тілінде емес, құралдарға қолжетімділікте кодта.

Егер галлюцинацияларды ұстау стратегияң неғұрлым екпінді тұжырымдама болса, сенде стратегия жоқ. Сенде тек үміт бар.

Ойлау моделі

Агент — әріптес емес. Ол функция: prompt → tokens. Функция кодты жазуда керемет, ал дұрыс нәрсе істеген-істемегенін іштей саралауда нашар. Оның өз жұмысы туралы мәлімдемелерін гипотеза ретінде қабылда. Diff, exit коды, скриншот, жолдар саны — міне, дәлелдер осылар. Жүрістің соңындағы қорытынды — бүкіл жүйедегі ең өтірікшіл бет.

Мамандану — баяндаудың ауытқуынан сақтандыруың. Shell — сенің жалғыз ақиқат көзің. Builder жазады. Reviewer тексереді. Bash шешеді.

Қорытынды

Бір нәрсені есте сақтасаң: бір агентке өз шығысын әрі өндіруге, әрі бағалауға жол берме; әрі бірде-бір агентке команданы орындамай сандық сұраққа жауап беруге жол берме. Қалғанының бәрі осы екі ереженің салдары. Құралдарға қолжетімділікті агрессивті түрде баптап, қорытындылардың орнына құрал шақыруларын аудитте — сонда галлюцинация беті барлық жерден өзің қарауды бұрыннан білетін бірнеше нақты орынға дейін тарылады.