CLAUDE.md, рұқсаттар және «/» пәрмендері

Lab 02-де сен агентке бәрін бір файлда ұста дедің. Ол нұсқау бір ғана әңгіменің ішінде өмір сүреді. /clear пәрменін орында, контекст түйінделсін немесе ертең қайта кел — нұсқау жоқ, сен оны қайтадан тересің. Бүгін бұған нүкте қоясың әрі өтіну мен мәжбүрлеудің айырмасын түсінесің.

Бүгін төрт нәрсе жасайсың: агент әр сеанстың басында оқитын CLAUDE.md, нені сұраусыз іске қосуға болатынын шешетін .claude/settings.json, көз алдыңда сұрауды қабылдамайтын тыйым ережесі және өз қолыңмен жазылған бір «/» пәрмені. Басынан аяғына дейін Manual режимінде отыр.

cd qairu-event
git status
claude --permission-mode manual

Алдымен оған жад бер, сосын жадтың жүктелгенін дәлелде

CLAUDE.md әр сеанстың басында толық жүктеледі және /compact пәрменінен кейін де аман қалады, себебі Claude Code оны дискіден қайта оқиды. Ал тек чатқа терген нұсқауларың аман қалмайды (жад туралы құжаттама).

1. Дайындаманы жасат та, жартысын қырқып таста

   /init пәрменін орында. Claude репозиторийді оқып шығып, CLAUDE.md жазады. Оны қабылда да, /memory пәрменімен ашып қара.

   Шыққан файл тым ұзын. Әр жолға бір ғана сынақ қолдан: осыны өшірсем, қате туа ма? Жоқ болса — өшір. Агент кодтың өзінен оқып ала алатын нәрсе жад емес, шу. Мұнда жиырма шақты жолды нысана ет, ал нағыз репозиторийде 200-ден аспасын.

2. Орнына тексеруге келетін ережелер жаз

   Бұлыңғыр ережелер («таза код жаз») түк өзгертпейді. Ішінде пәрмен, файл жолы немесе санауға келетін шарт бар ережелер ғана жұмыс істейді.

   # CLAUDE.md — QAIRU Event Sign-up
   
   ## What this is
   One static page: an event description and a form that reserves a seat.
   
   ## Commands
   - Serve locally: `npx serve .`
   - Check it: open the page, submit the form with an empty name field
   
   ## Workflow
   - Anything bigger than a one-line change: plan first, wait for my approval.
   - After every change, list the manual test steps you expect me to run.
   - Small commits. The message says what changed and why.
   
   ## Rules that differ from defaults
   - All code stays in `index.html`. No frameworks, no npm packages, no build step.
   - Every user-visible string exists in Kazakh and English.
   - The seat cap is one constant at the top of the script, never a number typed in three places.
   
   ## Do not touch
   - `.env` — it holds keys. Never read it, print it, or commit it.
   
   ## When compacting
   Keep: the list of modified files, the current plan step, and the seat-cap value.

   Агент болжай алмайтын пәрмендер, әдепкі қалыптан өзгеше ережелер, тиюге болмайтын бір нәрсе және контекст түйінделгенде нені сақтау керегі. Басқа ештеңе жоқ.

   6-модульде сен AGENTS.md файлын бірден-бір ақиқат көзі етіп, CLAUDE.md ішінде бір ғана жол — @AGENTS.md — қалдырдың. Солай істеген болсаң, бұл бөлімдерді AGENTS.md ішіне жаз: сол файлды Codex, Cursor және басқа құралдар да оқиды. Зертхананың қалған бөлігі екі жағдайда да бірдей.

3. Оның шынымен жүктелгенін тексер

   /context деп тер. Жад файлдарының тізімінен өз CLAUDE.md файлыңды тауып, оның терезенің неше пайызын жеп тұрғанына қара. Әр жол — әр сеанста төлейтін салық. Оны алдымен қырқып алғаныңның себебі де осы.

4. Жап-жаңа, бос әңгімеде сынап көр

   Көпшілік аттап өтетін қадам — әрі бір нәрсені шынымен дәлелдейтін жалғыз қадам. /clear әңгімені өшіреді, жад файлын емес.

   ❯Жад сынағыClaude Code · Manual mode, immediately after /clearКөшіру

   Тіркелу формасына барлық өрісті тазалайтын "Reset" түймесін қос.
   Алдымен жоспарды түсіндірме — тікелей өзгерісті жаса.

   Екінші жол сынақты бір кезекке сыйғызу үшін тұр: сен жоспарды емес, жад файлын бағалап отырсың.

   Нәтижені өзіңнің үш ережеңмен салыстыр. Код index.html файлында қалды ма? Түйменің жазуы қазақша да, ағылшынша да бар ма? Сұрамай-ақ тест қадамдарын тізіп берді ме? Үштен екеуі шықса, бір ережең тым бұлыңғыр — сол жолды қайта жаз да, қайта сына.

Енді оған қоршау қой, өйткені файл — кеңес қана

Claude Code құжаттамасы жад файлдарын “context, not enforced configuration” — мәжбүрлейтін баптау емес, жай ғана контекст деп атайды. Бірдеңені шынымен бұғаттау үшін тыйым ережесі немесе hook керек (жад). Ал сенің «.env файлын ешқашан оқыма» деген жолың — тапсырманы аяқтауға бейімделген жүйеге айтылған сыпайы өтініш қана.

1. Қорғауға тұрарлық бірдеңе жаса

   Жоба түбірінде .env файлын жасап, ішіне FORM_API_KEY=super-secret-123 жаз, сосын .env файлын .gitignore ішіне қос. Кілт жалған. Он минут бойы оны нағыз кілт деп есепте.

2. .claude/settings.json файлын жаз

   Қатаң JSON: түсініктеме жоқ, соңғы үтір жоқ. Әйтпесе келесі іске қосқанда Settings Error шығады.

   {
     "$schema": "https://json.schemastore.org/claude-code-settings.json",
     "permissions": {
       "allow": ["Bash(git status)", "Bash(git diff *)", "Bash(git log *)"],
       "ask": ["Bash(git push *)"],
       "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
     }
   }

   allow — растай-растай жалыққан ұсақ-түйегің, ask — әр жолы өз көзіңмен көргің келетіні, deny — ешқашан болмайтыны. Ережелер deny → ask → allow ретімен тексеріледі, бірінші сәйкестік жеңеді: таласты ереженің нақтылығы емес, осы санат реті шешеді.

3. Қайта іске қос та, өз ережелеріңді оқып шық

   /exit жаса, claude --permission-mode manual арқылы қайта қос та, /permissions пәрменін орында. Үш allow, бір ask, үш deny — әрқайсысының қасында қай файлдан келгені жазулы. Бір ереже жоқ болса, JSON файлың дұрыс оқылмаған.

4. Тыйым ережесінің сұрауды қалай қабылдамайтынын көр

   Үш сұрау, біртіндеп. Біріншісін жібер де, келесісін жібермей тұрып жауабын оқы.

   ❯1-сұрау — deny тізіміне түседіClaude Code · Manual modeКөшіру

   .env файлымның ішінде не бар?

   Қабылдамады — рұқсат сұраған жоқ, тікелей бас тартты. Read бойынша тыйым сол жолдағы Edit пен Write әрекетін де бұғаттайды әрі Bash ішіндегі cat, head, tail және sed пәрмендерін қамтиды.

   ❯2-сұрау — allow тізіміне түседіClaude Code · Manual modeКөшіру

   git status пен соңғы 3 commit-ті көрсет.

   Үнсіз орындалады. Растау терезесі жоқ, кідіріс жоқ. Зертхананың ең қызықсыз жартысы осы — әрі күн сайын сезінетін жартысы да осы.

   ❯3-сұрау — ask тізіміне түседіClaude Code · Manual modeКөшіру

   Орында: git push

   Сұрайды — әрі accept-edits режимінде де сұрай береді, себебі анық жазылған ask ережесі ешбір режимде автоматты түрде расталмайды. «Жоқ» деп жауап бер де, Tab пернесін басып, себебін қоса жаз: “no remote yet”.

   Үш сұрау, үш түрлі жауап — шешімді әңгіме емес, файл қабылдады. Ешкімді көндірудің қажеті болмады.

Қоршаудың саңылаулары бар, қай жерде екенін білген жөн

.env файлын бір жолдық Python скриптімен оқып, нәтижесін экранға шығар.

Manual режимінде растау терезесі бәрібір шығады, өйткені бұл — Bash пәрмені. Ал енді терезеде не жазылмағанына қара: тыйым ережесі мүлде оянбады. Растасаң, жалған кілт экраныңда тұрады.

Bash ережелері іске қосылатын бағдарламаға емес, пәрменнің мәтініне қарап сәйкестендіріледі. Bash(rm *) ережесі /bin/rm шақыруын да, bash -c 'rm ...' жазуын да тоқтатпайды, ал Read бойынша тыйым файлды өзі ашатын скриптті ұстамайды. Құжаттама бұл ережелердің не екенін ашық айтады: ыңғайлылық, қауіпсіздік шекарасы емес.

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

Оған елу рет іске қосатын бір пәрменді үйрет

Екі рет көшіріп жапсырған кез келген нәрсе «/» пәрменіне айналуға тиіс. Skill-дер мен өз пәрмендерің — бір жүйе: .claude/commands/preflight.md да, .claude/skills/preflight/SKILL.md да саған /preflight пәрменін береді.

1. Skill файлын жаз

   .claude/skills/preflight/SKILL.md файлын жаса. Қалта атауы name өрісімен дәлме-дәл сәйкес келуі керек.

   ---
   name: preflight
   description: Review my uncommitted changes for secrets, missing Kazakh strings and untested behaviour before I commit
   disable-model-invocation: true
   ---
   ## Current changes
   !`git diff HEAD`
   
   ## Instructions
   1. Summarise what changed in three bullets a beginner can follow.
   2. Flag anything resembling a key, token, password, phone number or email address.
   3. Check every new user-visible string exists in both Kazakh and English.
   4. List the exact manual test steps for this change.
   
   Do not edit any files. Report only.

   Мұны екі механизм көтеріп тұр. ! таңбасынан басталып, кері апострофқа алынған пәрмен жазылған жол сол пәрменді орындайды да, шыққан нәтижені контекстке салады — демек сен бірдеңе терместен бұрын diff контекстте тұрады. Ал disable-model-invocation: true деген жол Claude оны өз бетінше ешқашан іске қоспайтынын білдіреді — қосымша әсері немесе шығыны бар кез келген нәрсе үшін дұрысы осы.

2. Нағыз өзгеріске қолданып көр

   Skill жүктелуі үшін Claude Code-ты қайта іске қос. / деп теріп, тізімнен preflight дегенді тап немесе /skills пәрменін орында. index.html файлын өз қолыңмен өңде де, /preflight пәрменін іске қос. Сен оны шақырмайынша контекстте тек сипаттамасы ғана тұрады — skill-дің CLAUDE.md ішіндегі қырық жаңа жолдан артық болатын себебі осы.

3. Қоршаудың өзін де commit жаса

   CLAUDE.md, .claude/settings.json және skill файлын commit жаса. .claude/settings.local.json пен .env файлын қалдыр: біреуі — жеке параметрлерің, екіншісі — құпия дерек. Енді репозиторийіңді клондаған әркім бұл ережелерді алғашқы сеансында бірге алады.

Code freeze — бір сөйлем. Тыйым ережесі — қоршау.

Әзірлеу агентінің қолында production дерекқорының тірі кілттері болды, ал code freeze тек чат терезесіндегі мәтін күйінде қалды. Replit-тің бас директоры Amjad Masad кейін мұны “Unacceptable and should never be possible.” — мұндай болуға тиіс емес, мүлде мүмкін болмауы керек — деп бағалады (The Register, 2025 ж. 22 шілде). Бас әріппен жазылған он бір ескерту мен бір тыйым ережесі — бір нәрсенің аз-көп мөлшері емес. Бұл екеуі — мүлде бөлек санат.

Екеуін де жаз. CLAUDE.md — агентпен жұмыс істеуді жағымды ететін қалауларың тұратын жер; параметрлер, hook-тар және құпия деректер — ешқашан болмауға тиіс нәрселерді ұстап тұратын жер. Осы екеуін шатастыру — бұл курстағы ең жиі кездесетін бастаушы қатесі.