--- title: "Claude Code – Best Practices" url: "https://romankryvolapov.com/bg/claude-code-best-practices/" description: "Как да организирате работата с Claude Code: инструкции на проекта, правила и скилове, тракер на задачи и бъгове в хранилището, план преди кода, субагенти, контекст, разрешения и разход на бюджета." language: bg published: 2026-08-06 updated: 2026-11-09 --- **Здравейте!** Тук преди имаше статия за практиките при работа с Cursor. Пренаписах я. Не е там работата, че Cursor е станал по-лош. Променил се е самият начин на работа: агентът вече не е „умно автодопълване“, а изпълнител, за когото вие подготвяте работното място, и резултатът зависи много повече от това колко добре е подготвено то, отколкото от това колко красиво сте формулирали заявката. Само че да подготвяш не значи да описваш всичко подред: кода съвременният модел ще го прочете сам, и то по-бързо, отколкото бихте го преразказали вие. Записва се това, което го няма в кода. По-нататък е за Claude Code. Какво да сложите в хранилището, как да планирате работата, как да не изгорите контекста и парите. Примерите са взети от работен проект, където всичко това е настроено и изпитано в продължение на няколко месеца реална разработка; числата също са оттам, а не от въздуха. Снимката на проекта е направена през август 2026 г., а какво се е променило в него през следващите три месеца и защо – е в раздела „Три месеца по-късно“. ## Контекст: не стена, а цена Моделът има контекстен прозорец и в него се побира цялата сесия: вашите съобщения, всеки прочетен файл, изходът на всяка команда, включително онзи лог от триста реда, който агентът е изкарал веднъж и повече не се е връщал към него. Едно дебъгване лесно изяжда десетки хиляди токени. Доскоро това беше основното ограничение. Сега при повечето модели прозорецът е милион токена, а преди да се напълни, Claude Code сам свива историята, така че рядко се стига до стената. В официалните препоръки на Anthropic съветът „контекстният прозорец е основното ограничение, пестете го агресивно“ вече е сред остарелите. Но като цена контекстът никъде не е изчезнал. Всяка заявка изпраща на модела целия разговор отново: докато кешът е топъл – с отстъпка, след пауза – на пълна цена (при абонамент кешът живее около час, при API ключ – пет минути). Сесия, в която има три несвързани задачи, на всеки ход на четвъртата препрочита и трите. И като шум също: две неуспешни опита, останали в историята, моделът ги препрочита заедно с успешния, а договореност, дадена само в чата, може да не оцелее след свиването. От тук идва изводът, от който расте всичко останало. Контекстът все така трябва да се управлява съзнателно: да решавате какво попада там и какво не. Само че сега заради цената и фокуса, а не от страх, че прозорецът ще свърши. ## Дайте на агента начин да се провери Това е първото, което си струва да настроите, и най-често го пропускат. Агентът спира, когато работата изглежда свършена. Ако няма с какво да се провери, „изглежда“ е единственият наличен сигнал и проверяващият ставате вие. Всяка грешка чака, докато я забележите. Дайте нещо с еднозначно „мина / не мина“ и цикълът се затваря сам. Агентът поправя, пуска проверката, чете резултата, повтаря. Проверката може да е набор от тестове, изходният код на билда, линтер, скрипт за сравнение с еталон, скрийншот за сверяване с макета. Разликата си личи още във формулировката на задачата: ```text ✗ направи функция за валидиране на email ✓ направи функция за валидиране на email. Примери: user@example.com – вярно, invalid – грешно, user@.com – грешно. След реализацията пусни тестовете и покажи изхода ✗ билдът пада ✓ билдът пада със следното: [текст на грешката]. Поправи причината, а не симптома, и се увери, че билдът минава ``` В моя проект проверката е вградена в правилото за комит: преди комит задължително се изпълняват проверка на типовете, билд и два валидатора на съдържанието. Не „желателно“, а задължително, с указание, че резултатът от гейтовете влиза в отчета такъв, какъвто е, а не „май всичко е зелено“. Колко строго да държите проверката, решавате вие, и нивата вече са четири. В заявката: „пусни тестовете на auth и продължавай, докато минат“ – кога е достатъчно, агентът решава сам. С цел: `/goal` задава условие, което след всеки ход отделен модел сверява с разговора, и агентът работи, докато то не е изпълнено; това е нужно най-вече при дълги фонови изпълнения, където понякога приключва хода с отчет за напредъка, макар точките още да са отворени. С хук `Stop`: вашият скрипт се стартира всеки път, когато агентът се опита да приключи хода, и изходен код 2 го връща на работа. Това го държи вече самият Claude Code, а не моделът. И с чужди очи: `/code-review` проверява diff в нов субагент, който не е видял вашия разговор и не е заразен от разсъжденията, от които е израснал кодът. За това, което тестовете и проверката на типовете не хващат, има `/verify`: агентът билдва и стартира самото приложение и гледа резултата. И искайте да показва доказателство: изхода на тестовете, самата команда, скрийншот. Доказателството се чете по-бързо, отколкото се проверява на ръка. А за сесия, която не сте следили, това е изобщо единственият начин да разберете какво е станало. ## Първо разузнаване, после план, после код Ако веднага поискате код, ще получите грижливо решение на грешната задача. В Claude Code има отделен режим за планиране – Shift+Tab или `/plan` преди една заявка: агентът чете файлове, пуска команди за разузнаване и пише план, но не пипа сорс кода. Работният цикъл е такъв: да се разбере нужната част от кода → да се състави план → да се одобри, и режимът се изключва сам → да се реализира → комит. Планът го четете лично и внимателно. Това е най-евтината точка за намеса: да поправите абзац от плана е минута, да преправяте реализацията – половин час. При голяма задача добре работи похватът „нека агентът ви интервюира“. Описвате идеята в един абзац и го молите да задава въпроси: за реализацията, за граничните случаи, за онова, което може да не сте взели предвид. В края – да запише спецификацията във файл. След това нова сесия с чист контекст и молба да се реализира по тази спецификация. ```text Искам да направя [едно изречение за фийчъра]. Интервюирай ме подробно, чрез инструмента за въпроси. Питай за реализацията, интерфейса, граничните случаи, рисковете и компромисите. Очевидното не питай, рови в трудните места, които може да не съм взел предвид. Когато приключим, запиши пълната спецификация в SPEC.md. ``` Само не го превръщайте в ритуал. Ако промяната може да се опише с едно изречение, план не е нужен: излишният кръг струва повече, отколкото ползата от него. За ясна задача обикновено стига първата проста заявка: нужния код агентът ще го прочете сам. ## Три нива на настройка Знанието се предава на агента по три начина и те не са взаимозаменяеми. **Инструкциите на проекта** се четат в началото на всяка сесия. Тук отиват фактите, нужни винаги: как се билдва, как се пускат тестовете, с какво този проект се отличава от типовия. Препоръката на Anthropic е да се държите в рамките на двеста реда и това не е формалност. Колкото по-дълъг е файлът, толкова по-зле се спазват собствените му указания. Добър тест за всеки ред: ако го махна, агентът ще започне ли да греши? Не – махайте го. При Anthropic тестът е още по-строг: може ли агентът да намери това, като прочете кода, и ще отиде ли да погледне? Ако и двата отговора са „да“, редът е излишен. Затова да описвате в инструкциите архитектурата и разположението на папките вече няма смисъл: хранилището агентът ще го прочете сам, и по-бързо, отколкото вие го обясните. Нужно е това, което го няма в кода: решение, взето на видеоразговор, процес на деплой, който живее в главата на един човек, променлива на средата за интеграционните тестове, място, където кодът заблуждава. Началната версия на файла ще я събере `/init`, нататък работата е предимно в зачертаване. А `/doctor prompt-audit` минава през инструкциите, правилата и скиловете и търси указания, писани за стари модели, връзки към несъществуващи файлове и противоречия между файловете; предлага поправки, но без да го попитате, нищо не променя. **Правилата** са отделни файлове в каталога за правила, по един файл на тема, и се зареждат по същия начин. Могат да се ограничат с маски на пътища и тогава правилото се зарежда само когато агентът пипа подходящи файлове: ```markdown title=".claude/rules/api-endpoints.md" --- paths: - "src/api/**/*.ts" - "apps/backend/**/*.ts" --- # Правила за API - Всеки ендпойнт валидира входа, без изключения. - Грешките се връщат в общия формат от `ErrorResponse`. - Новият ендпойнт първо се описва в api.md, после се пише кодът. ``` Правило с маски се зарежда, когато агентът чете или променя подходящ файл. Нюанс, който лесно може да се пропусне: при свиване на контекста такова правило си отива заедно с историята и ще се върне само когато агентът отново пипне подходящ файл. Правилата без маски и коренният файл с инструкции след свиването се препрочитат от диска. **Скиловете** са знание при поискване. Каталог с файл вътре; тялото влиза в контекста само когато задачата му съответства или когато вие сами сте извикали скила. Затова големите справочници трябва да са скилове: в спящо състояние от тях в контекста има само име и описание. А процедура със странични ефекти, като издаване на релийз, си струва да се маркира с `disable-model-invocation: true`: тогава агентът сам няма да я стартира, а само вие с командата `/име`, и в списъка тя не заема място. Разпределението, което ползвам аз: - факт, нужен винаги → инструкции на проекта; - задължително поведение → правило; - процедура или справочник, нужни понякога → скил; - това, което е длъжно да се случва (или да не се случва) винаги, без участие на модела → хук или забрана в настройките за разрешения. Последната точка стои настрана. Всичко по-горе е текст, който моделът чете и обикновено изпълнява. Хукът е код, който ще се изпълни независимо от неговото решение. Критичното поведение трябва да е хук, а не абзац в инструкциите. Обратното също е вярно: хук за нещо, което на практика е предпочитание, е вреден. Предпочитанията имат изключения и моделът, виждайки кода пред себе си, обикновено преценява по-добре дали правилото пасва на случая, отколкото вие, написали го предварително. Anthropic съветва да се държи наборът от твърди забрани малък: ако са станали към четиридесет, повечето са въпрос на вкус. Разбор на хуковете с всички събития и работни примери имам в [отделна статия](/bg/claude-code-hooks/). ### И всичко това са промптове Мисъл, до която стигнах не веднага, а трябваше да е от самото начало. Инструкциите на проекта, правилата, скиловете, описанията на субагентите не са конфигурация. Това са системни промптове, които някой (вие) пише веднъж, а моделът чете във всяка сесия. Разликата между „агентът постоянно прави не това“ и „агентът работи предвидимо“ много често се оказва разликата между небрежно и грижливо написан промпт. Кои от техниките на промпт инженеринга наистина се отплащат в тези файлове: - **Структура и разделители.** Заглавия, списъци, явни блокове: моделът разбира структуриран текст по-надеждно от плътна проза, а вие получавате възможност да сочите към конкретно парче от друго правило. Повече за [разделителите и структурата на промпта](/bg/prompt-engineering/#Разделители-и-структура-на-промпта). - **Йерархия на правилата.** Когато правилата са повече от пет, те започват да си противоречат и трябва направо да се напише кое от тях е по-важно. При мен например правилото „не комитвай без молба“ стои над правилото за проверка преди комит и в текста това е казано с думи, а не се подразбира. За това как се задава [йерархия на правилата](/bg/prompt-engineering/#Йерархия-на-правилата) има отделен раздел. - **Положителни формулировки вместо забрани.** „Остави промените в работното дърво и разкажи какво си направил“ работи по-добре от „не комитвай“. Само забраните оставят модела без образец на поведение. - **Спокоен тон вместо крясък.** IMPORTANT и главните букви бяха нужни на старите модели. Сегашните следват спокойно формулиран ред, а от натиск започват да прилагат правилото твърде широко, и там, където не пасва. - **Примери вместо описания.** Двойка „така е зле / така е добре“ в правилото струва колкото три абзаца обяснение. Това е обикновеният [few-shot](/bg/prompt-engineering/#Few-shot-примери), просто приложен към конфигурацията на проекта. - **Явен формат на отговора.** Ако искате определена форма на отчета, трябва да я опишете, а още по-добре – да я покажете. За [контрола на формата на отговора](/bg/prompt-engineering/#Контрол-на-формата-на-отговора) – там също. - **Икономия на контекст.** Всеки ред от инструкциите и правилата се плаща във всяка сесия, затова излишната дума тук е по-скъпа, отколкото в обикновен промпт. Това е точно онова, което в статията за промптовете се нарича [контекст инженеринг](/bg/prompt-engineering/#Контекст-инженеринг-прозорецът-като-ресурс). Още едно наблюдение от практиката: описва се не само какво да се прави, но и **каква грешка предотвратява правилото**. Моделът, който разбира от какво го застраховат, прилага правилото много по-добре към ситуация, която не е описана дословно. Половината от моите правила затова започват с абзац „известният сценарий на провал изглежда така“. Пълният разбор на техниките е в статията [за промпт инженеринга](/bg/prompt-engineering/); по-нататък в текста ще се позовавам на конкретни раздели оттам. ## Как изглежда това на жив проект По-нататък показвам на работно хранилище във вида, в който беше през август 2026 г.: девет правила, справочник по API, сто и два скила и тракер на задачите направо в проекта. Всичко това не е израсло изведнъж, а от ситуации, в които едно и също се е налагало да се обяснява за трети път. ### Правила Правилото е това, което агентът е длъжен да спазва винаги. Всяко е в отделен файл и завършва с чеклист: по него се вижда дали е спазено, или не. Ето как изглежда едно правило изцяло, най-краткото от моите: ```markdown title=".claude/rules/never-commit-unless-asked.md" # Никакви комити, докато не са поискани **Не стартирай `git commit` (както и push, PR, merge), докато потребителят не го е поискал директно, със свои думи.** Завършена работа, зелен билд и усещането „май е готово“ не са разрешение. Направил си промените – остави ги в работното дърво, разкажи накратко какво се е променило и спри. Не си сигурен дали е поискан комит – не комитвай, питай. ## Чеклист - [ ] Нито един комит, push или PR без изрична молба със свои думи. - [ ] Работата е оставена в работното дърво, промените са описани. - [ ] При съмнение е зададен въпрос, а не е направен комит. ``` Изглежда като излишество. До първия път, когато агентът реши, че щом тестовете са зелени, може и да комитне, и отнесе в историята вашите недовършени експерименти. По-нататък ще мина през останалите осем. Оригиналите при мен са написани на английски (така се е получило исторически, правилата са се местили между проекти), затова цитатите ги давам в превод. #### Проверка преди комит Най-дългото правило, влиза в сила, когато комит все пак е поискан. Четири стадия: да се прочете целият diff на парчета; да се разгледа всичко, което промените засягат извън diff, тоест извикващият код, контрактите и документацията, която тези промени току-що са направили остаряла; да се потърсят дефекти; да се произнесе вердикт. Вердиктите са точно три и са написани така, че на агента да няма накъде да се измъкне: ```text PASS – не е намерено нищо, или всичко намерено вече е поправено и проверено наново. FIX, СЛЕД ТОВА PASS – има истински, но поправими находки. Поправи ги сам, незабавно, пусни проверката отново върху поправеното състояние и честно кажи на разработчика какво си намерил и какво си поправил. Поправянето е поведение по подразбиране: проблемите никога не се „оставят за после“ и никога не се свеждат до споменаване в отчета. STOP – сериозен проблем (загуба на данни, дупка в сигурността, счупен контракт, промяната противоречи на собственото си изискване) или истинско разклонение, където и двете конструкции са защитими и изборът принадлежи на разработчика. Комит няма. Обясни просто и конкретно в какво е проблемът. ``` След това идва фразата, която смятам за най-полезната в цялото правило: поправката, направена по време на проверката, сама е промяна и минава през същите четири стадия отново. Повтаря се, докато поредният пълен проход не намери нищо ново. Само това състояние се смята за чисто. Още е уговорено, че `--no-verify` е забранен: паднал хук се поправя, а не се заглушава. Отделно ще кажа за един похват, който тук работи. Стадиите са номерирани, всеки има свой списък с това какво да се проверява, а в края има задължителен вердикт с една дума. Това е същият [контрол на формата на отговора](/bg/prompt-engineering/#Контрол-на-формата-на-отговора), както в обикновените промптове: на модела му е много по-трудно да „проверява приблизително“ и да казва „май е нормално“, когато от него се изисква да избере един от трите означени изхода. #### Стил на отговорите Правило за това как да се разговаря с мен. Започва така: ```text Потребителят е човек, който чете чата, а не Claude Code. При него НЕ е отворен сорсът паралелно и той НЕ иска да разшифрова идентификатори на кода, имена на полета и пътища до файлове в отговора. Говори с него като колега, а не като инструмент за код ревю. Смятай, че читателят е компетентен разработчик, който НЕ е потопен в този проект. Той умее да пише код, но най-вероятно води няколко проекта едновременно и не държи спецификата на този в главата си. ``` След това – списък с това, което е забранено по подразбиране: фрагменти код, връзки от вида „файл:ред“, имена на полета и класове, големи таблици, ASCII диаграми. Всичко това е разрешено само ако директно съм поискал. Отделна част описва формата на финалния отчет: направено / остава / какво е нужно от човека. И там има пример, взет от живота: ```text ✗ „Остава: собствено дърво на миграциите с проверка за разминаване, образ и манифест, свързване в скрипта за стартиране.“ ✓ „Остава: - Да се опишат промените в базата като отделни стъпки за обновяване: сега таблицата се създава в движение и на истински сървър просто няма да я има. - Да се събере образ и да се добави в описанието на клъстера, иначе няма къде да се внедрява. - Да се впише услугата в скрипта за стартиране, за да се вдига заедно с останалите.“ ``` Три различни дела, слепени в един ред с думи, разбираеми само за този, който току-що ги е писал. Читателят ще кимне и няма да прочете, а после се оказва, че се е съгласил с нещо, което не е разбрал. Двойката „зле / добре“ тук работи по-добре от всяко описание и това е точно [few-shot](/bg/prompt-engineering/#Few-shot-примери): един показан пример замества абзац обяснения за самодостатъчността на формулировките. #### Бюджет на сесията ```text Харчи токени пропорционално на реалната сложност на задачата – по най-евтиния път, който я решава надеждно, а не по най-щателния, който би позволил бюджетът. Лимитите са ограда: те показват къде ще се блъснеш в стената или в ограничение на честотата, за да спреш предварително, а не бюджет, който трябва да бъде усвоен. ЗЕЛЕНАТА зона НЕ означава „харчи свободно“. ``` След това в правилото има таблица с класове задачи: тривиална – правим веднага, без размисъл и разузнаване; малка – прицелни четения, всичко в една нишка; средна – един проход на планиране и високи усилия само при трудното разклонение; голяма – на фази, с контролна точка между тях. И отделен раздел за субагентите с директна сметка: паралелно пускане на N агента струва колкото N сесии, затова има смисъл да се правят само заради явна икономия. Това правило работи в двойка с хука, който носи живите цифри на лимитите, – подробности за него има в статията за хуковете. #### Съмняваш ли се – търси в интернет Кратко правило, седемнадесет реда, и почти всичко в него е описание на един сценарий: ```text Известният сценарий на провал, който трябва да се избегне: нещо не работи → прилагаш поправка, основана на това, което „знаеш“ → пак не работи → всяка следваща поправка заравя решение, построено върху грешно предположение. Затова във ВСИЧКИ съмнителни случаи – когато нещо е неясно, неочевидно, държи се не така, както си очаквал, или се разминава със знанията ти – ВИНАГИ търси в интернет, преди да поправяш по-нататък, и гледай на първо място свежата официална документация. Ако и търсенето не даде решение – СПРИ и попитай потребителя. ``` Обърнете внимание на структурата: първо е описан провалът, после изискването. Така правилото се прилага и към ситуации, които в него не са описани дословно, защото моделът разбира от какво го застраховат. А главните букви днес бих ги махнал и в сегашната версия на правилото вече ги няма: защо – е казано по-горе, в раздела за промптовете. #### Обнови клона преди работа ```text Цената на пропускането не е конфликт при сливането накрая. Това е работа, построена върху основа, която вече я няма: бъг, вече поправен от някой друг; ревю на код, който междувременно се е променил; номер на запис в тракера или времеви печат на миграция, вече заети; решение, взето по файл отпреди две седмици. Нищо от това няма да изплува, докато работата не бъде завършена. ``` След това три стъпки: да се вземат промените и да се види доколко клонът е изостанал; да се превърти напред; да се прочете пристигналото, ако засяга вашата област. И отделен раздел за случая на мръсно работно дърво. #### Спирай на архитектурните разклонения Може би най-ценното правило от всички. Започва с формулировка, която ми харесва: ```text Част от решенията са поправка. Част са преписване. Това правило е за втория тип. Когато забележиш, че работата може разумно да се построи по повече от един начин и изборът е скъп за отмяна, – спри, преди да пишеш код, разбери картината изцяло и положи разклонението пред разработчика с предистория и подредени варианти. Да избереш тихо и да вървиш нататък – това е провалът, който правилото предотвратява: цената му не се вижда в diff, тя изплува месеци по-късно под формата на работа, която ще се наложи да се изхвърли. ``` След това – признаците, по които решението се смята за разклонение: трудно се отменя; разпростира се върху повече от един компонент или екип; определя кой какво притежава и къде минава границата на доверие; променя това, което се вижда отвън (внедрен компонент, схема на данните, API контракт); засяга пари, сигурност или поверителност. Два признака и повече – стоп. А ето втората половина на правилото, без която първата е вредна: ```text Да повдигнеш разклонение струва на разработчика истинско внимание. Преди да го повдигнеш: – Обратимо ли е в рамките на деня? → решавай сам. – Проектът вече е вземал равнозначно решение? → следвай го; прецедентът е по-важен от предпочитанието. – Би те устроил всеки от вариантите? → това не е разклонение, а вкус. Избирай. – Неясно е само защото не си погледнал? → първо погледни. Повечето „разклонения“ се разтварят при четене. Очаквай в проекта няколко истински разклонения, а не по едно на задача. Ако ги повдигаш всяка седмица – филтърът е настроен неправилно. ``` Без този филтър правилото се превръща в своята противоположност: агентът започва да пита по всеки повод, човекът спира да чете въпросите и пропуска онзи единствен, който е бил важен. #### Символна навигация В проекта е свързан сървър, който дава преход към дефиниция, търсене на използвания и промяна по символ. Правилото изисква да се ползва той вместо четене на файловете изцяло, и централната му част е таблица на съответствията: ```text | Задача | Инструмент | Вместо какво | | Да се разбере API на файл | преглед на символите | четене на целия файл | | Да се намери клас или функция | търсене на символ | grep по име | | Да се прочете тялото на символ | символ с тяло | четене с отместване | | Да се разбере кой го извиква | търсене на референции | grep по име | | Преименуване в целия проект | преименуване на символ | десетки промени | ``` След това – раздел „кога обикновените инструменти са правилният избор“. Това е важната половина: езиковият сървър има езици, които не разбира, и честното им изброяване е по-полезно, отколкото да се иска невъзможното. #### Водене на работата Деветото правило е за тракера: какво попада в задачите и бъговете, какво не попада никога, как са свързани записите и изискванията. То е голямо и го разглеждам по-долу в отделен раздел, защото там е интересна не толкова формулировката, колкото самата схема на водене. ### Скиловете са документация Главната мисъл на раздела: скиловете при мен не са „плъгини за агента“, а документация на проекта. Същата, която преди се е писала в уикита и никой не я е отварял. Документацията в уикито живее отделно от кода и бавно се разминава с него. Документацията в хранилището се поправя в същия pull request като кода и я чете изпълнителят. При това избирателно: тялото на скила влиза в контекста само когато задачата му съответства. Двадесет и шест хиляди реда документация струват по един ред в списъка за всеки скил, докато не са потрябвали. **Префиксът в името е адресатът.** Скиловете са разпределени не по теми, а по това чий екип е адресат: ```text .claude/skills/ ├── req-uc-auth/SKILL.md изисквания: сценарии за автентикация ├── req-personas/SKILL.md изисквания: персонажи ├── req-business-rules-core/SKILL.md изисквания: бизнес правила ├── ba-acceptance-criteria/SKILL.md бизнес анализ: как се пишат критерии ├── qa-bug-report/SKILL.md тестване: как се оформят находките ├── dev-backend-new-endpoint/SKILL.md разработка: процедура за нов ендпойнт ├── dev-tests-backend-unit/SKILL.md разработка: юнит тестове └── dev-workflow-git/SKILL.md разработка: конфликти при сливане ``` Дойде ли нова роля в екипа, се появява нов префикс, а не ново уики. **Как изглежда един скил.** Заглавна част с име и описание, после обикновен markdown: ```markdown title=".claude/skills/dev-backend-new-endpoint/SKILL.md" --- name: dev-backend-new-endpoint description: Процедура за добавяне на HTTP ендпойнт: контракт, валидация, слоеве, тестове, регенериране на клиента. Прилагай при създаване на нов ендпойнт или модул на бекенда. --- # Нов ендпойнт 1. Опиши контракта в `api.md` – преди кода, иначе файлът и кодът ще се разминат. 2. Контролерът само приема и връща; логиката е в услугата, достъпът до данните е в хранилището. 3. Валидацията на входа е задължителна, грешките – в общия формат. 4. Тестове: успешен път, отказ на валидацията, липса на права. 5. Прегенерирай клиента на фронтенда и провери, че се билдва. ## Чеклист - [ ] api.md е обновен преди кода - [ ] логиката е извън контролера - [ ] трите теста са налице - [ ] клиентът е прегенериран, билдът е зелен ``` Описанието е най-важното поле: по него агентът решава дали скилът пасва на задачата. „Справочник по FastAPI“ работи зле. „Архитектура и продукционни практики на FastAPI; прилагай при създаване и ревю на услуги на FastAPI“ – добре. В списъка описанието заедно с полето `when_to_use` се отрязва на 1536 символа, така че главния сценарий го поставяйте първи. По същество това е малък промпт за маршрутизация: той трябва да съдържа и предмета, и условието за задействане. Тялото на скила при това се държи кратко, защото след зареждането остава в разговора до края на сесията и пътува във всяка следваща заявка. А след свиването на контекста от всеки извикан скил се връща само началото – първите пет хиляди токена, и за всички скилове заедно не повече от двадесет и пет хиляди, – затова най-важното се слага в началото на файла. Тук важат същите съображения, както в [контекст инженеринга](/bg/prompt-engineering/#Контекст-инженеринг-прозорецът-като-ресурс): дългият справочник е по-добре да се раздели, като детайлите се изнесат в съседни файлове, към които скилът препраща. **Изисквания като скилове.** Скилът с изисквания изглежда като нормален документ на аналитик. Сценарии със свои номера, персонажи, граници, критерии за приемане. Нищо „за агента“ в него няма: ```markdown title=".claude/skills/req-uc-auth/SKILL.md (фрагмент)" ## UC-AUTH-002 Вход с имейл и парола **Персони:** PER-001 Агент, PER-002 Мениджър **Приоритет:** P0 ### Критерии за приемане - AC-UC-AUTH-002-001 – при верни данни сесията е отворена и важи и в двете приложения без повторен вход. - AC-UC-AUTH-002-002 – при грешна парола отговорът е един и същ независимо дали акаунтът съществува (не подсказваме при изброяване на акаунти). - AC-UC-AUTH-002-003 – след пет неуспешни опита подред входът с този имейл се блокира за 15 минути. ``` А после идва главното: към тези номера се позовават задачите и бъговете. В записа на тракера стои не преразказ, а връзка. Текстът на изискването не се копира никъде и живее на едно място. Ако записът и изискването се разминат – прав е документът с изискването. Лекува позната болест: критерий, преписан в задачата, в уикито и в тест кейса, и три негови версии след половин година. ### Но това е само един от вариантите Да държите документацията в скилове е мой избор, а не единственият правилен път. Хората решават тази задача по много различни начини и си струва да знаете от какво изобщо се избира. **Обикновена папка с документация в хранилището.** Най-простият вариант: markdown в `docs/`, а в инструкциите на проекта ред „документацията е еди-къде си“. Нищо не трябва да се настройва, хората го четат в GitHub както е. Минусът е точно един, но съществен: агентът няма да си спомни за нея, докато не посочите файла. Той не знае какво има вътре и в най-добрия случай ще намери нужното с търсене по думи. **AGENTS.md.** Междуинструментален файл с контекст, който четат Codex, Cursor и още десетина агента. Claude Code също го чете сам, но само ако в проекта няма нито CLAUDE.md, нито CLAUDE.local.md, така че го изключва дори личният CLAUDE.local.md с вашите бележки. Ако CLAUDE.md го има, по подразбиране се чете той, а AGENTS.md се включва с ред `@AGENTS.md` вътре в него или с настройка, която нарежда да се четат и двата файла. Добър избор за екип, в който различни хора работят с различни агенти. Ограничението е същото като при инструкциите на проекта: това е един файл и не може да се раздува до справочник. **Външно уики през MCP.** Confluence, Notion, Linear и каквото друго се сетите: документацията остава там, където хората и без това я водят, а агентът ходи там през MCP сървър. Аналитикът поправя страницата в познатия интерфейс, с коментари и история, а агентът чете същото. Цената са мрежата, акаунтите и това, че версията на документацията живее отделно от версията на кода: страницата се е променила вчера, а клонът, който поправяте, отговаря на състоянието отпреди месец. **Obsidian и сродните му.** Локално хранилище от markdown файлове, към което агентът се свързва или с MCP сървър, или просто като му се отвори каталогът. Форматът е същият – обикновен текст, затова хранилището може да се държи в гита, а върху него работят и човекът със своя граф от връзки и търсене, и агентът. Хората го ползват като обща памет между инструменти и сесии: бележки, решения, наработки на едно място, достъпно и за Claude Code, и за друг агент. За лична база знания вариантът е отличен. За проектна документация на екип е по-слаб: връзката с кода пак се губи, а хранилището живее собствен живот. **Платформи за документация с MCP и llms.txt.** Съвременни услуги като GitBook или Mintlify предлагат документацията веднага в два вида: сайт за хора и машинночетим слой, чак до автоматично вдигнат MCP сървър. Разумно е, когато документацията е публична и така или иначе трябва да се публикува някъде. **Търсене в голям корпус.** Ако документацията е хиляди страници, нито един от горните варианти няма да се побере в контекста и въпросът преминава в областта на търсенето: векторна база данни, хибридно търсене, отделен сървър, който дава на агента нужните парчета. Това вече е отделно инженерство, а не „сложих файловете в папка“. #### С какво печелят скиловете С едно свойство, заради което съм преминал към тях: **агентът винаги знае, че съществуват.** Списъкът със скиловете и описанията им влиза в контекста в началото на всяка сесия (освен онези, които се извикват само ръчно), затова нужния документ агентът го зарежда сам, без напомняния. С папка с документация така не става: докато не посочите файла, все едно го няма. След това дребни неща, но приятни. Документацията се версионира заедно с кода и в стария клон е документацията, която съответства на стария код. Промените минават през обикновеното ревю в pull request. Нищо не трябва да се настройва, всичко работи офлайн, без токени и външни услуги. А форматът е отворен: скиловете на Claude Code следват стандарта Agent Skills, който разбират и други инструменти. #### С какво се плаща По-честно е минусите да се изброят веднага. **Списъкът със скилове сам заема контекст.** Не телата, а именно списъкът с имена и описания, но във всяка сесия. Бюджетът на този списък е един процент от контекстния прозорец. Когато скиловете са толкова много, че списъкът не се побира, Claude Code изхвърля описанията на най-рядко ползваните и от тях остават само имената. Тоест плащате вече не толкова с токени, колкото с невидимост: без описание агентът няма да разбере, че скилът пасва на задачата. Колко струва вашият списък, ще оцени `/doctor`, а кои скилове почти не се ползват, ще покаже `/skill-doctor`. **На хората е неудобно да четат.** Вътре в хранилището няма нито търсене в документацията, нито съдържание, нито коментари на полето, нито удобна работа с картинки. Аналитик, свикнал с Confluence, в GitHub за изисквания няма да отиде. При мен това е решено, защото изискванията ги поправя същият човек, който работи с агента, но в голям екип това ще стане проблем. **Няма съвместно редактиране и обсъждане.** Коментар към абзац, обсъждане направо в документа, известие „споменаха ви“ – всичко това го няма. Има pull request, което е в пъти по-формално. **Няколко хранилища – няколко копия.** Общите за компанията практики ще трябва или да се дублират, или да се свързват със символни връзки, или да се опаковат в плъгин. В монорепо проблем няма, а при пет хранилища е забележим. **Изкушението да се струпа всичко там.** Скиловете са евтини, затова лесно се натъпкват сто файла и се получава същото мъртво уики, само че в гита. Единственото спасение е описанието, по което агентът избира скила. Ако е написано небрежно, документът никога няма да бъде зареден и дори няма да разберете. **Няма филтриране по роли.** Скиловете на аналитика ги вижда разработчикът и обратно, а с контекст плащат всички. За това по-подробно е по-долу, в раздела за ролите. Ако се сведе до едно правило: това, което е нужно на агента в момента на работа върху кода, е по-добре да се държи до кода; това, което е нужно на хората за обсъждане и планиране, е по-добре да се държи там, където хората са свикнали да работят. При мен границата минава приблизително така: изискванията и практиките – в скилове, а плановете, сроковете и кореспонденцията остават във външна система. ### Колко струва това Инструкциите на проекта и правилата се зареждат във всяка сесия изцяло. През август при мен това бяха 571 реда инструкции плюс 1245 реда правила. Почти две хиляди реда, преди да сте напечатали първата дума. Забележимо повече от препоръчаното и аз плащам за това с контекст. Направил съм съзнателен компромис: предвидимостта в проект с няколко приложения и обща инфраструктура струва повече от спестените токени. Но компромисът има предел. Ако файлът растеше нататък, щях да разнеса правилата по маски на пътища. Между другото, ако агентът упорито нарушава някое правило – работата почти винаги не е във формулировката, а в обема. Правилото се е загубило. Лекува се със съкращаване, а не с добавяне на главни букви. А ако правилото не бива да знае изключения изобщо, мястото му не е в текста, а в хук или забрана. ### Три месеца по-късно Компромисът „предвидимостта струва повече от токените“ се наложи да бъде преразгледан. Файлът с инструкции до края на август порасна до 653 реда, съкратиха го до 216, а в началото на октомври проектът мина през пълно почистване. След него в инструкциите са около сто и петдесет реда, а скиловете вместо сто и два са тридесет и шест: седемдесет и два махнаха, а шест нови междувременно се добавиха. Какво се промени: - **Седемдесет и два общи скила.** Справочници като най-добрите практики на FastAPI или производителността на Python. Всичко това моделът го знае и без нас, а ние плащахме за тях с място в списъка на всяка сесия. Останаха изискванията, двадесет и четири скила, и процедурите, които съществуват само в този проект, като ревю на pull request по правилата на екипа. - **Бележките по части на проекта** са събрани в отделни CLAUDE.md в папките на бекенда, фронтенда, инфраструктурата и други. Такъв файл се зарежда само когато агентът започне да работи в своята папка. - **Файловете `.claudeignore`.** Claude Code не ги чете: файл да се затвори за агента може само със забрана за четене в настройките за разрешения. - **Трите правила** – не комитвай без молба, проверка преди комит и обновяване на клона – се превърнаха в две: „преди започване на работа“ и „приключване на работа“, където са ревизията на промените, комитът само при молба и pull request до зелените проверки. Готовата задача я проверява веднъж отделен субагент-ревюър. Добавиха се правила за качеството на кода, за конфликтите при сливане и за самостоятелната работа: преди да питаш, потърси сам, и довеждай задачата докрай, а не я връщай по средата на пътя. Правилата вече са общо единадесет плюс справочникът по API, около хиляда и сто реда, и всички, освен стила на отговорите, са преписани наново. Цитатите по-горе са от августовските версии: като образци на формулировки те все още стават. Изводът съвпадна с този, до който е стигнала и самата Anthropic: на агента си струва да се пише само това, което той няма да намери сам в кода. Как изобщо се пише добър бекенд, моделът и без това го знае, а как е прието във вашия екип – не. ## Документация: как и къде Принципът е прост. Цялата документация, която чете агентът, живее в инструкциите, правилата и скиловете. Отделна папка „доки за агента“ изобщо няма – за да няма два източника на истина. Това е решение на конкретен проект, а не единственото възможно: вариантите и цената им разгледах по-горе. Какво следва от това: **Правилата и скиловете са източникът на истина.** На агента директно е забранено да измисля поведение, което им противоречи. Сметне ли документа за неправилен – казва на човека, а не действа по свой начин. **Не се поправя документацията без молба.** Отначало изглежда странно, после се оказва необходимо: агент, който се е спънал в неудобно правило, с готовност ще приведе правилото в съответствие със своето поведение. **Ново – нов документ, промяна на съществуващо – поправка на съществуващото.** Иначе след половин година в проекта има два скила за едно и също с различни версии на истината. **Единен шаблон.** Има отделен скил за това как се пишат правила и скилове: структура, формулировки, разделители, задължителен чеклист в края. Чеклистът превръща описанието в проверимо изискване, а заедно с това дава на агента начин сам да провери дали е изпълнил документа. Този скил по същество е свод от техники на промпт инженеринга, приложен към конфигурацията на проекта, и правилото изисква да се прилага при създаване или промяна на всяко правило и на всеки скил. Звучи бюрократично, но се отплаща: документите, писани по един шаблон, по-рядко си противоречат и по-добре се спазват. Разбор на самите техники има в статията [за промпт инженеринга](/bg/prompt-engineering/). **README за хората, инструкции за агента.** И двете са нужни, но читателите са различни. README обяснява на новия човек какво се случва тук; агентът се опира на инструкциите, правилата и скиловете. Променя ли се структурата на проекта – поправят се и двете, иначе разработчикът и агентът живеят с различни представи за хранилището. **Техническите справочници – отделно.** Внедряването, миграциите, резултатите от натоварващите тестове са в обикновена папка с документация в корена. На агента при работа върху кода не са нужни, а на човека са нужни от време на време. ## Тракер на задачи и бъгове направо в хранилището Най-своеобразната част от моята конфигурация. Задачите и бъговете са в хранилището като обикновени markdown файлове, по един файл на запис. Никаква база, никакъв уеб интерфейс, никакви проверки в CI. Скриптът умее две неща: да заведе запис и да прегенерира индекса. С това автоматизацията свършва. ```text management/ ├── tasks/ │ ├── auth/TASK-001-one-password-for-both-apps.md │ ├── billing/TASK-037-invoice-pdf-export.md │ ├── done/TASK-012-import-legacy-contacts.md │ ├── INDEX-AUGUST-2026.md │ └── TEMPLATE.md ├── bugs/ │ ├── auth/BUG-003-sign-in-loops-on-expired-token.md │ ├── done/BUG-001-avatar-upload-fails-over-2mb.md │ └── INDEX-AUGUST-2026.md ├── decisions/ADR-0001-where-user-sessions-are-stored.md ├── logs/roman/2026-08-06/a1b2c3d4.log └── new.py ``` Какво дава това. Агентът вижда задачата цялостно, без да излиза от проекта, заедно с изискването, към което тя препраща, и кода, който променя; записът живее в същата история като кода, затова винаги се вижда с кой комит е затворен и какво е променяно по него по пътя. Двама души (или двама агенти) над различни записи физически не редактират един файл, така че конфликти при сливане няма по самото устройство – това е може би главният аргумент срещу един голям файл със списък на задачите, към който всички са свикнали. Плюс всичко работи офлайн, без акаунти и токени. ### Как изглежда един запис Ето истински шаблон на бъг, само с измислено съдържание: ```markdown title="management/bugs/auth/BUG-003-sign-in-loops-on-expired-token.md" --- id: BUG-003 title: 'Sign-in loops on an expired token' severity: P1 status: CONFIRMED module: auth area: 'sign-in / refresh token' found: 2026-08-04 closed: assignee: '' req: 'AC-UC-AUTH-002-001' source: 'QA wave 12' --- # BUG-003 — Sign-in loops on an expired token - **Steps:** open the app with a token older than 24h → sign-in screen → enter valid credentials → back to the sign-in screen. - **Expected:** AC-UC-AUTH-002-001 — a valid sign-in opens a session. - **Actual:** the refresh call returns 401 and the client retries forever. - **Log:** - 2026-08-04 — filed from the QA wave. - 2026-08-05 — reproduced on staging, confirmed. Refresh interceptor does not clear the stale token before retrying. ## Screenshots - 2026-08-04 — `BUG-003_04-AUGUST-2026_11-20_loop.png` — the loop, three redirects in the network tab. ``` Създава се с команда, а не с копиране на файла на ръка: ```bash python management/new.py bug --module=auth --severity=P1 \ --title="Sign-in loops on an expired token" python management/new.py task --module=auth --priority=P1 \ --title="One password for both apps" python management/new.py attach BUG-003 shot.png --note="the loop after the fix" ``` Скриптът издава следващия свободен номер, слага файла в папката на модула и прегенерира индекса на месеца. Индексът изглежда така: ```markdown title="management/tasks/INDEX-AUGUST-2026.md" # Task index — AUGUST 2026 **Entries:** 31 · **Open:** 30 · **Closed:** 1 | ID | Prio | Status | Batch | Module | Title | | --- | --- | --- | --- | --- | --- | | TASK-029 | P1 | IN_PROGRESS | 2026-08-04-export | billing | Export invoices as PDF from the admin panel | | TASK-030 | P1 | TODO | PROJ-42 | platform | Choose a feature-flag library | | TASK-031 | P1 | TODO | PROJ-42 | platform | Set up CI/CD for the staging environment | ``` Детайли, които са важни на практика: **Номерата са вечни.** Не се преизползват и не се преномерират никога: към тях препращат комитите, кореспонденцията и другите записи. Сквозната номерация, вярно, по-късно се наложи да бъде сменена със случайни кодове от четири символа като `BUG-2W7F`: двама души на два клона вземаха един и същ „следващ свободен номер“ и git спокойно сливаше двата записа, защото имената на файловете им са различни. Старите записи запазиха своите номера. **Папките са наименувани по изискванията.** Областта на записа носи името на файла с изисквания, който я притежава: `req-uc-auth` → папка `auth`. Задачите и бъговете делят едни и същи папки. Дреболия, но премахва вечния спор „къде да се сложи това“ и свързва тракера с документацията. **Затваряне през `git mv`.** Сменя се статусът, поставя се датата, дописва се ред в журнала, файлът се премества в папката със затворените. Git не съхранява премествания: `git mv` дава същия резултат като обикновеното преместване, а `git log --follow` проследява файла по приликата на съдържанието. Затова историята на записа се къса само ако заедно с преместването файлът е силно преписан, и точно това в затварящия комит си струва да се избягва. **Скрийншотите – в хранилището.** Отделна команда слага картинката в папката с прикачени файлове, именува я по схема и дописва ред в записа. Само изображения, до четири мегабайта, изрязани: гитът пази всеки байт завинаги. Видеото – с връзка. Разделът със скрийншоти се дописва в края, защото бъг, живял три седмици, носи снимка за всяко състояние, а старите редове трябва да показват как е било тогава. **Езикът е английски, на латиница.** Името на файла се строи от заглавието, а тракерът го четат хора без общ роден език. Описанието може да се остави на езика на оплакването, ако са помолили, но заглавието и служебните полета винаги са на латиница. ### Какво не попада в тракера никога Най-важното правило на отчитането и то противоречи на навика: в тракера има само продукт. Тестът е точно един. Работи ли това при клиента? Приложенията, библиотеките, от които са събрани, данните, инфраструктурата – да, това е продукт. Всичко, което съществува само за да ни е по-удобно да строим продукта, не попада в тракера изобщо. Нито като задача, нито като бъг, независимо от обема работа и от това кой е поискал. Документацията на хранилището, правилата, скиловете, самият тракер и неговият скрипт, хуковете, служебните скриптове, настройките на CI, преместването на папки. Това просто се прави, а записът остава комитът и автоматичният журнал на сесията. Формулировката в правилото звучи твърдо и това е нарочно: ```text Никакъв запис изобщо – колкото и счупено да изглежда и колкото и работа да струва: остарял документ, мъртва връзка, грешен път в правило, дефект в самия този тракер или в служебен скрипт, хук, който погрешно чете входа си, крива настройка на CI, преименувана папка, правило, за което някой е помолил. До клиента нищо от това не стига, значи не е бъг. А да го превърнеш в задача е същата грешка под друга табела. Не създавай. Свърши работата, комитът ще говори вместо нея. ``` Изкушението е голямо: работата е много и се иска да се вижда. Но тракер, натъпкан със стопански дела, никой не чете, а е създаден точно за да се чете. Второто разделяне е задачи срещу бъгове. Всичко, което е намерило тестването, е бъг и само бъг. Поправката на бъг не ражда задача. Задача е нова функционалност или преработка на съществуваща, за която са помолили. ### Решения Заедно със задачите се пазят архитектурните решения, по един файл на решение. Форматът е обикновен, познат от ADR: ```markdown title="management/decisions/ADR-0001-session-storage.md (структура)" --- id: ADR-0001 title: Where user sessions are stored: database or cache status: Proposed date: 2026-07-31 deciders: Engineering lead / Architect related: - management/tasks/auth/TASK-001, TASK-002 - Requirements BR-SEC-004 (one session shared by both apps) supersedes: none --- ## Context какво е наложило решението и кой въпрос е блокиран ## Decision номерирани точки: какво точно е решено ## Verified facts (checked in code, not assumed) таблица „факт → къде в кода“ ## Consequences какво опростява това и с какво плащаме за него ## Alternatives какво е разглеждано и защо е отхвърлено ``` Разделът с проверените факти се роди, след като едно решение беше прието въз основа на чужд преразказ, а в кода се оказа различно. Сега всеки факт в ADR носи препратка към мястото в кода, откъдето е взет. Смисълът е прост: спор, който се решава веднъж, после не изплува наново на всеки два месеца. ### Журнал на сесиите, който се пише сам Третата част от отчитането на работата и никой не я води на ръка. Хукът записва всичко, което се е случвало в сесията: вашите заявки, въпросите на агента и какво сте избрали, статистика за всеки ход, променените файлове с брой редове, финалния отчет. Файл на сесия, папка на ден, папка на разработчик. Изглежда така: ```text title="management/logs/roman/2026-08-06/a1b2c3d4.log" session start: source=startup · model=claude-opus-5 ════════════════════════════════════════════════════════════ prompt: поправи безкрайното пренасочване при изтекъл токен, BUG-003 turn: model=claude-opus-5 · effort=high · 4m 12s · tools=23 (Read 9, Grep 5, Edit 3, Bash 6) · subagents=1 files: ~ apps/web/src/api/interceptors.ts +14/-6 +[41-48,52-57] -[41-46] ~ apps/web/tests/auth.spec.ts +31/-0 +[88-118] answer: Причината беше, че интерсепторът повтаряше заявката със стария токен... subagent done: general-purpose session end: reason=prompt_input_exit · duration=51m ``` Защо, като има самия агент? Защото да го питате какво е било в сесията е лоша идея. Към края на дългата работа контекстът му вече е свит: част от подробностите са загубени, част са преразказани оптимистично. Механичният запис, направен не от модела, е единственият честен отговор на въпроса „какво изобщо се е случило“. Четиридесет и седем такива файла се натрупаха до август, до ноември са над седемстотин. Отварях ги по-често, отколкото очаквах: обикновено за да разбера кога и защо се е появило странно място в кода. Освен това така се отговаря и на въпроса „а къде се отчита работата по самото хранилище, която е забранено да се води като задача“. Ето тук. Автоматично, без един ред ръчно водене. ### Какво схемата няма Честно за ограниченията. Тук няма табло, известия, отчети по спринт, отчитане на времето. Ако мениджмънтът живее в Jira, тази схема не я замества: при мен например етикетът за групиране съхранява точно ключ от Jira. Разделението е такова. Във външната система – планиране и отчетност за мениджъра. В хранилището – това, което е нужно на изпълнителя в момента на работа, заедно с кода и изискванията. ## Какво липсва: ролите Щом вече разпределих скиловете по префикси за различни екипи, ще кажа и за това, което на тази схема не ѝ достига в самия инструмент. Префиксът в името е конвенция, а не механизъм. Аналитикът, тестерът и разработчикът работят в едно хранилище и получават една и съща конфигурация: еднакви инструкции, целия набор от скилове, еднакви права за запис. Три неприятности и всичките три съм ги виждал на живо. Аналитикът моли да се сверят спецификацията и кодът, а агентът, натоварен с инструкции за разработчик, започва да поправя сорса. Тестерът моли да се възпроизведе дефект, а в общите инструкции пише „преди проверката приложи миграциите“ и агентът честно ги прилага на общия стенд. И по-тихо, но по-скъпо: всички плащат с контекст за всички скилове, включително за онези, които работата им не засяга никога. Обходният път е очевиден и лош: всеки си създава лична конфигурация в домашната си папка. Тя не е в хранилището, никой не я ревюира, новият човек просто я няма. Правилното решение е да се направи ролята пълноценен слой на конфигурацията в хранилището. Своя част от инструкциите, свой набор от скилове и агенти, свои разрешения и, най-вече, своя област за запис, отвъд която промените не излизат: ```text .claude/ ├── CLAUDE.md общата част за всички ├── settings.json ├── skills/ └── roles/ ├── dev/{CLAUDE.md, settings.json, skills/, agents/} ├── qa/{CLAUDE.md, settings.json} забрана за миграции и деплой └── ba/{CLAUDE.md, settings.json} запис само в docs/ и specs/ ``` При това тя трябва да е забрана на ниво инструмент, а не молба в текста. Разликата е точно същата като между правилото и хука. Част от схемата вече може да се сглоби от наличното. `--agent` дава на сесията инструментите и модела на нужния субагент, а файлът с настройки, подаден през `--settings`, добавя забрани и с параметъра `skillOverrides` крие от агента чуждите скилове или оставя от тях само имената. Но всичко това се избира на ръка при стартиране, а не е в хранилището като готова роля. Оформих това като [заявка за добавяне на роли](https://github.com/anthropics/claude-code/issues/97907) в Claude Code: с описание на проблема, с това, което вече покриват флаговете `--agent` и `--settings`, и с това, което не достига. Пълната версия със схема за сливане на настройките (ролята може само да стеснява проектните права, но не и да ги разширява) е в [първата заявка](https://github.com/anthropics/claude-code/issues/81615), която беше затворена от бота за неактивност. Ако болката ви е позната, отидете да подкрепите – колкото повече потвърждения, толкова по-голям е шансът да им стигнат ръцете за това. ## Субагенти Субагентът е отделна сесия със свой контекст, свои инструменти и свой системен промпт. Върши част от работата, връща резултат. Има и форк: той не започва от чист лист, а наследява целия текущ разговор. Ползата не е в това, че субагентът е по-умен: по подразбиране това е същият модел или по-лек, и същата задача той няма да реши по-добре от основната сесия. Ползата е в четири неща. Паралелност: независими парчета работа вървят едновременно. Шумният изход – пълно изпълнение на тестовете, широко търсене в кода – остава при субагента, а не пътува после във всяка заявка на основната сесия. Свеж поглед за проверка. И орязани права: ревюър, който може да чете, но не може да поправя, и тази забрана я държи самият инструмент. Да се иска това най-често не е нужно: широкото търсене в кода Claude Code сам го дава на вградения субагент Explore, страничните задачи – на форкове, и ги пуска във фонов режим, за да не чака основният разговор. Свой субагент се описва с един файл: ```markdown title=".claude/agents/security-reviewer.md" --- name: security-reviewer description: Ревю на промените за уязвимости. Стартирай преди релийз и при промени в автентикацията, качването на файлове, работата с БД. tools: Read, Grep, Glob, Bash model: opus --- Ти си старши инженер по сигурността. Гледай промените за: - инжекции (SQL, XSS, команди на обвивката); - дупки в автентикацията и оторизацията; - тайни в кода; - небезопасна работа с потребителски данни. Посочвай конкретни редове и предлагай поправка. Стилистиката не я пипай. ``` Тялото на такъв файл е системен промпт на отделен модел, а не бележка за себе си. Работи всичко същото: зададена роля, явни граници („стилистиката не я пипай“), формат на отговора и условие за извикване в описанието. За това как се пишат промптове за агенти и извикване на инструменти има [отделен раздел](/bg/prompt-engineering/#Промптове-за-агенти-и-извикване-на-инструменти) в статията за промптовете. Още едно приложение е независимата проверка. Който е писал кода, е лош проверяващ: той вижда не diff, а своите намерения. Субагент си струва да се моли конкретно: ```text Със субагент провери промените спрямо PLAN.md. Увери се, че всяко изискване е реализирано, че за изброените гранични случаи има тестове и че нищо извън задачата не е променено. Пиши за пропуските, а не за въпроси на вкус. ``` Оговорка, която е по-добре да знаете предварително: проверяващият, когото са помолили да намери недостатъци, ще ги намери. Дори когато работата е свършена добре, защото са го помолили за това. Да гоните всяка забележка е пряк път към излишни слоеве абстракция и тестове за невъзможни случаи. И за парите. Субагентите не са безплатни: всеки изпраща свои заявки и те отиват в същите лимити като основния разговор. На свежия субагент му се налага и наново да събира контекст, който основната сесия вече е имала, така че понякога той излиза дори по-бавен. Паралелното пускане на десет струва приблизително като десет сесии. Може да се спести от модела: проста работа като събиране на файловете, които импортират модул, се дава на субагент на Haiku, с ред `model: haiku` в описанието му. Промяна в един-два файла винаги е по-бърза в основната сесия. Отделна история са няколкото паралелни сесии. Най-лесно е да се разведат по работните дървета на гита: всяка има собствен каталог и собствен клон, промените не се сблъскват. `claude -w име` веднага стартира сесия в ново работно дърво, а файловете, които гитът игнорира, като `.env`, които в свежото дърво ги няма, Claude Code ще копира сам, ако ги изброите в `.worktreeinclude` в корена на хранилището. Схемата „един пише, друг проверява“ работи по същата причина като субагента-ревюър: свежият контекст не е заразен от разсъжденията на автора. ## Контекстът на практика Похвати, които ползвам постоянно: **Първата минута.** Гледайте накъде е тръгнал агентът и натискайте Esc, щом завие не натам: той ще спре, запазвайки всичко направено, и може да се поправи курсът. **Нова задача – чист контекст.** Изчистването между несвързани задачи е по-евтино от всяка оптимизация. Опашката на чужда задача са и излишни токени, и излишни поводи за разсейване. `/clear` не струва нищо, а с име, `/clear oauth`, дава име и на сесията, към която после може да се върнете. **Два неуспешни опита – стоп.** Поправихте два пъти и пак не е това? Вече не е във формулировката: контекстът е запълнен с неуспешни подходи. Чиста сесия с по-точна постановка почти винаги изпреварва дългата с натрупани поправки. **Свиването се настройва.** Преди да се напълни прозорецът, историята се свива автоматично. Може да се свие и на ръка, с акцент върху нужното (`/compact запази промените на API и командите за тестове`), а в инструкциите на проекта да се укаже какво задължително се пази: ```markdown title="CLAUDE.md" При свиване на контекста задължително запазвай: списъка на променените файлове, командите за пускане на тестовете и взетите архитектурни решения с причините им. ``` Само помнете, че свиването на дълга сесия само по себе си е голяма заявка: моделът препрочита целия разговор, за да го преразкаже. Ако историята не е нужна, `/clear` е по-евтино. **Връщане назад вместо предпазливост.** Всяка ваша заявка е точка за връщане: `/rewind` или Esc два пъти на празен ред, и може да се върне разговорът, файловете или и двете. Това променя стила на работа: вместо дълго обмисляне на рисковата стъпка е по-просто да опитате и да се върнете. Само помнете, че връщането не замества гита: то помни само файловете, които агентът е променял със своите инструменти в основния разговор, а промените през командния ред не ги следи. **Кратък въпрос настрани.** За дреболия от рода на „какво прави този флаг“ има `/btw`: отговорът не попада в историята. **Статусен ред и `/usage`.** Размерът на контекста и разходът е по-добре да ги държите пред очите си: в статусния ред – постоянно. А `/usage` при абонамент разпределя разхода по скилове, субагенти, плъгини и MCP сървъри и сам подсказва какво да се промени. ## Разрешения Режимите на разрешения са няколко и по подразбиране сега работи не най-строгият. Интерактивните сесии в терминала и във VS Code стартират в автоматичен режим: отделен модел-класификатор гледа действието преди изпълнение и спира това, което бихте спрели и вие – `curl | bash`, деплой и миграции в продукция, force push върху чужда работа, изпращане на чувствителни данни навън, действия, които приличат на команди от прочетен от агента текст, а не на ваши. След три блокирания подред или двадесет общо режимът се предава и отново пита човека. Ако неинтерактивно пускане с `claude -p` върви в автоматичен режим, няма кого да попита: блокираното действие просто не се изпълнява и Claude продължава работата без него. В другия край е ръчният режим, където потвърждавате всяка промяна и всяка команда, освен четенето. Безопасно и непоносимо: след десетото потвърждение вече не четете, а кликате. А режимът съвсем без проверки, `bypassPermissions`, има смисъл само в еднократен контейнер. Режимите, включително планирането, се превключват с Shift+Tab. Автоматичният режим е преценка на модела, а не правило, и може да сгреши. Затова всичко, което е „никога“, се записва така, че да го държи самият инструмент: със забрани в настройките и с хукове. Забраните и хуковете `PreToolUse` действат във всеки режим, включително автоматичния и `bypassPermissions`, и се задействат още преди класификаторът изобщо да види действието: ```json title=".claude/settings.json" { "permissions": { "allow": [ "Bash(npm run test *)", "Bash(npm run lint)", "Bash(npm run build)" ], "ask": ["Bash(git push *)"], "deny": [ "Read(.env)", "Read(.secrets/**)" ] } } ``` Записани без `./`, тези правила хващат такъв файл на всякаква дълбочина под папката, където е стартиран Claude Code; `Read(./.env)` би затворило само този, който е в нея самата. Забраната за четене на `.env` затваря и инструмента за четене, и `cat .env` в командния ред: разпространените команди за четене на файлове Claude Code ги разпознава. Скрипт, който отвори файла сам, той вече няма да хване. Да се разрешава четене вътре в проекта и команди като `git status` или `git diff` не е нужно, потвърждение те така или иначе не изискват. Звездичката след интервал е сегашният запис; старата форма `test:*` все още работи, но диалогът за разрешения записва новата. Целият синтаксис на правилата е в [справочника за команди и настройки](/bg/claude-code-commands-and-settings/#Права-за-достъп-на-инструментите). Ако класификаторът отново и отново спира това, което при вас е рутина, не потвърждавайте на ръка, а опишете средата с думи в личните настройки: кои домейни са ваши, кой стенд може да се пипа. В ръчния режим помага обратното: `/fewer-permission-prompts` разглежда минали сесии и добавя често срещани безопасни команди в списъка на разрешените. Най-строгият вариант е пясъчникът (`/sandbox`, на macOS, Linux и WSL2): ограничаване на файловата система и мрежата на ниво ОС за командите, които стартира агентът. Той подхваща и вашите забрани за четене, така че за всичко, което засяга сигурността, са нужни и двата слоя. Каквото и да изберете, едно правило остава. Преди комит да се гледа пълният diff. То беше важно и преди агентите, а сега е по-важно: моделът с готовност променя това, за което не са го молили, и заедно с това оправя съседния файл. ## Когато никой не гледа Всичко казано по-горе е двойно по-важно, когато агентът работи без вас. Докато гледате, пропуснато парче от контекста не е беда: ще забележите след съобщение-две. Пуснете ли задачата за през нощта – и сутринта разбирате, че цяла нощ тя се е градила върху грешно предположение. Преди такова пускане си струва да минете през пет въпроса, точно за тази задача: 1. Знае ли агентът как изглежда „готово“? Условие на целта, файл със спецификация, падащ тест, който трябва да стане зелен. 2. Може ли да се провери сам? Тестове, хук `Stop`, стъпка за ревю. 3. Какво му е позволено да пипа? Правила за разрешения, пясъчник, отделно работно дърво, единствен клон, където може да се прави push. 4. Какво ще го спре? `--max-turns`, `--max-budget-usd`, лимит на разходите. 5. Накъде ще отиде резултатът и кой ще го приеме? Pull request или отчет – и човекът, който одобрява сливането. Самото пускане е `claude -p "задача"` в скрипт или CI. С `--permission-mode dontAsk` всичко, което не е разрешено предварително през `--allowedTools`, се отхвърля, а не виси в очакване на отговор. Да повтаря задача по таймер в отворена сесия умее `/loop`, а `/schedule` създава облачна задача по разписание, която работи и при затворен лаптоп. Започвайте с три файла, а не с триста: погледнете какво е тръгнало накриво, поправете заявката, после пускайте останалото. ## Модели, усилия и пари Работата на агента се състои от стъпки с много различна сложност. Да се разбере задачата, да се намерят файловете, да се приложи промяната, да се провери резултатът. Да държите на всички стъпки най-скъпия модел няма смисъл. Практиката е такава: основната сесия на силен модел, механичната работа се делегира на субагенти на по-лек модел, нивото на усилия се повишава само там, където има трудно разклонение. И скиловете, и субагентите умеят да задават модел и усилия за себе си, така че маршрутизацията може да се опише веднъж: ```markdown title=".claude/skills/dev-changelog/SKILL.md" --- name: dev-changelog description: Събери changelog от историята на комитите между два тага. model: haiku effort: low disable-model-invocation: true --- ``` Уточнение за скиловете: без `context: fork` моделът на скила действа в основния разговор до края на хода. Евтиният модел тогава получава цялата история, а кешът на промпта на основния модел не се разпростира върху него, така че в дълга сесия икономията може да се превърне в свръхразход. С `context: fork` скилът се стартира в собствен субагент и вижда само своите инструкции. Главният регулатор на това колко мисли моделът е нивото на усилия: `low`, `medium`, `high`, `xhigh` и `max`, превключва се с командата `/effort`. При Opus 5.5, Sonnet 5.5 и Haiku 5.5 по подразбиране стои `medium` и за обикновена работа с ясни граници това стига; при останалите модели с нива на усилия по подразбиране е `high`, а при Opus 4.7 – `xhigh`. Струва си да се вдига, когато правилността зависи от лесно пропускани случаи: бъг в чужд код, плаващ тест, промяна на схема, при която трябва да се намерят всички, които я четат. `max` е за трудна задача, която агентът решава без вас; на обикновена той мисли излишно и вие плащате за отговор, не по-добър от този, който би дал `high`. Фрази като „помисли хубаво“ в заявката са обикновен текст и нивото на усилия не повишават. А за един труден въпрос посред рутината има думата `ultrathink`: тя моли да се помисли по-дълбоко само на този ход. Отделна тема са лимитите на абонамента. По подразбиране агентът не ги вижда, затова не може да съобразява разхода: той еднакво лесно пуска много субагенти наведнъж и когато до нулирането има четири часа, и когато бюджетът е на привършване. На човека ги показва `/usage`, при пусканията от скриптове има твърди предели `--max-turns` и `--max-budget-usd`, а при мен това е решено с хук, който носи живите цифри в контекста и забранява пускането на много агенти наведнъж в горещата зона. Подробности има в статията за хуковете. ## MCP и конзолни утилити Два начина да се даде на агента достъп до външния свят. Конзолните утилити са най-икономичният по контекст път. Има ли услугата CLI – агентът го ползва прекрасно: създава задачи, чете коментари, гледа логове, разгръща средата. Непознати утилити той също усвоява, ако го помолите да се оправи по вградената помощ. MCP сървърите са за случая, когато е нужен структуриран достъп: база, тракер, макети, мониторинг. Тук живее и полезна категория сървъри за работа със самия код: символната навигация вместо четене на файловете изцяло спестява много забележимо при големи хранилища. За типизираните езици Claude Code има и официални плъгини за code intelligence върху езикови сървъри: преход към дефиниция вместо grep и четене на няколко файла-кандидата, а след промяна – грешките в типовете веднага, без стартиране на компилатора. Съвет от практиката: свързвайте само това, което наистина ползвате. Пълните описания на инструментите на MCP вече се зареждат при поискване, но имената на инструментите и инструкциите на сървъра са в контекста на всяка сесия и пътуват във всяка заявка, така че десетина сървъра „за всеки случай“ излизат по-скъпо, отколкото изглежда. Ненужните се изключват в `/mcp`. ## Кои съвети са остарели Моделите забележимо се подобриха и част от съветите, които доскоро бяха верни, сега пречат. Ако нещо от това е останало във вашите навици или в инструкциите – смело го изхвърлете: - **„Контекстът е основното ограничение“.** Прозорецът от милион токена и автоматичното свиване направиха блъскането в стената рядкост. Контекстът между задачите все така си струва да се чисти, но заради цената и фокуса. - **„Давайте работата на субагенти, за да спестите контекст“.** Субагентите са добри за паралелна работа, шумен изход и независима проверка и всеки струва токени. - **„Субагентът ще отговори по-добре“.** Същият модел върху същата задача по-умен няма да стане. Помага свежият поглед на ревюъра, но това е друго. - **„Помисли хубаво“ в заявката.** За дълбочината отговаря нивото на усилия, а тези думи са обикновен текст. Работи само `ultrathink` и само за един ход. - **IMPORTANT и главните букви.** Сегашните модели от тях прилагат правилото твърде широко. Не се държи ред – значи файлът е твърде дълъг или това е работа за хук. - **„Не се мързи, продължавай до края“.** Поставената задача моделите и така я довеждат докрай, а такива редове по-скоро предизвикват излишна работа. Друго е да дадете проверка, която трябва да се мине: това все още е полезно. - **Описание на архитектурата и разположението на папките в инструкциите.** Хранилището агентът го чете сам. Пишете само това, което го няма в него. ## Какво е останало вярно от практиките за Cursor Част от съветите от старата статия никъде не са отишли. Те са за работата с модел изобщо. **Декомпозирайте и контролирайте стъпките.** Молбата „направи всичко“ дава код, който работи не така, както сте очаквали, и да го разбереш струва повече, отколкото би струвало да го напишеш. Стъпките трябва да са самодостатъчни: след всяка проектът се билдва. **Логвайте щедро.** На човека конзолата, претоварена с логове, пречи, на агента помага: сравнявайки изхода с кода, той по-точно разбира какво се е счупило. **Искайте свежи версии на библиотеките и гледайте лицензите.** Моделът ще постави версията, която най-често е виждал при обучението, а тя рядко е последната: данните за обучение изостават от излизането на модела с месеци, а честотата на споменаване тегли към версии още по-стари. За лиценза не гледа изобщо, а да вкарате в закрит проект библиотека с копилефт е лесно. **Уточнявайте начина на решение предварително.** Едно нещо може да се направи по пет начина и без уточнение изборът го прави моделът – въз основа на това, което по-често се е срещало в данните за обучение. Попитайте за вариантите и минусите, преди кодът да е написан. **Различни задачи – различни сесии.** Съветът за нов чат за всяка задача е преминал без промени, само че сега има точно обяснение: той е за цената и фокуса на контекста. ## Как да развалите всичко Събрах начините, които виждам най-често. И у себе си също. **Сесия-кочина.** Започнахте с една задача, попитахте за друга, върнахте се към първата. Контекстът е запълнен с всичко наведнъж. **Безкрайни поправки.** Агентът направи не това, поправихте, пак не това. След два кръга е по-евтино да започнете отначало. **Раздути инструкции.** Файлът е пораснал, половината указания са престанали да работят: важното се е загубило. Лекува се с безмилостно съкращаване. **Доверие без проверка.** Правдоподобна реализация, която не покрива граничните случаи. Няма с какво да се провери – не изпращайте. **Безкрайно разузнаване.** „Разбери как е устроено всичко тук“ без граници и сесията е платила за двеста прочетени файла. Широкото търсене Claude Code сам го дава на субагент, но границите ги задавате вие: ограничавайте областта. ## Накратко Ако от статията трябва да вземете само едно: първо настройте средата, после искайте код. Само настройвайте това, което агентът няма да види сам: останалото той ще прочете в кода. Проверка, която агентът може да пусне сам. Кратки инструкции на проекта, където е само това, което той няма да намери в кода. Правила за задължително поведение, скилове за знание при поискване, хукове и забрани за това, което трябва да се случва винаги или никога. Водене на задачите до кода. Съзнателно отношение към контекста – заради цената и фокуса. Работата е еднократна и се отплаща във всяка сесия. И разликата между „агентът постоянно прави не това“ и „агентът прави каквото трябва“ обикновено е именно тук, а не в модела и не във формулировката на поредната заявка. И още веднъж за това, с което започнах: всичко това са промптове. Инструкции, правила, скилове, описания на субагенти. Написани небрежно, те дават точно онзи резултат, който дават небрежните промптове, само че вие плащате за него във всяка сесия, а не веднъж. Техниките, които тук работят, са разгледани в статията [за промпт инженеринга](/bg/prompt-engineering/). За хуковете – механизмът, който прави поведението на агента детерминирано, – има [отделна статия](/bg/claude-code-hooks/) с всички събития и три работни примера.