Когда это нужноWhen to reach for itКоли це потрібно
Построена новая или переименованная видимая пользователю возможность, либо вы спрашиваете «не забыл ли я что-нибудь», «обнови документацию» или «README устарел». В плане ему место в последней фазе docs-cleanup, после сборки и до закрытия тикета.A new or renamed user-visible capability is built, or you ask 'did I forget anything', 'update the docs' or 'the README is out of date'. In a plan it belongs to the final docs-cleanup phase, after the build and before the ticket closes.Збудовано нову або перейменовану видиму користувачеві можливість, або ви питаєте «чи не забув я щось», «онови документацію» чи «README застарів». У плані йому місце в останній фазі docs-cleanup, після збірки й до закриття тікета.
ТребованияRequirementsВимоги
- Где доступноAvailable inДе доступно
- Каждая загрузка kitEvery download of the kitКожне завантаження kit
- К чему обращаетсяWhat it touchesДо чого звертається
- Читает файлы проектаReads the files of your projectЧитає файли проєкту
- Правит файлы проектаEdits files in your projectЗмінює файли проєкту
- Работает сWorks withПрацює з
- Сделано для Claude Code; другие агенты адаптируютBuilt for Claude Code; other agents adapt itЗроблено для Claude Code; інші агенти адаптують
- Где выполняются шагиWhere the steps happenДе виконуються кроки
- Чат вашего агента и ваши собственные файлы. Ни то ни другое не интерфейс этого сайта, поэтому шаги описаны текстом, а не скриншотами.Your agent's chat and your own files. Neither is an interface of this site, so the steps are text and not screenshots.Чат вашого агента і ваші власні файли. Ні те, ні інше не є інтерфейсом цього сайту, тому кроки описано текстом, а не скриншотами.
- Где это лежит в kitWhere it lives in the kitДе це лежить у kit
.claude/skills/surfaces/SKILL.md
Прежде чем начатьBefore you startПерш ніж почати
Он правит только источники: никогда не публикует, не выкладывает и не отправляет карточку, и этот необратимый шаг остаётся за вами. Поверхность, которой нет в таблице, он не правит, а сгенерированную меняет в её источнике и пересобирает, но не вручную. Изменение, которого никто не видит, сразу заканчивается строкой surfaces: not user-visible - <reason>.It edits sources only: it never publishes, deploys or submits a listing, and that irreversible step stays yours. It never edits a surface the table does not list, and a generated surface is changed in its source and regenerated, never by hand. A change nobody can see ends at once with surfaces: not user-visible - <reason>.Він править лише джерела: ніколи не публікує, не викладає й не подає картку, і цей незворотний крок лишається за вами. Поверхню, якої немає в таблиці, він не править, а згенеровану змінює в її джерелі й перегенеровує, але не вручну. Зміна, якої ніхто не бачить, одразу завершується рядком surfaces: not user-visible - <reason>.
ШагиStepsКроки
- Запустите
/surfacesдля текущего diff,/surfaces <ticket-id>для изменения тикета (тикет только читается) или/surfacesс однострочным описанием изменения.Run/surfacesfor the current diff,/surfaces <ticket-id>for the change of a ticket (the ticket is only read), or/surfacesfollowed by a one-line description of the change.Запустіть/surfacesдля поточного diff,/surfaces <ticket-id>для зміни тікета (тікет лише читається) або/surfacesз однорядковим описом зміни. - Сначала он спрашивает, может ли пользователь увидеть это изменение, воспользоваться им или удивиться из-за него. Если нет, как при внутреннем рефакторинге, тесте или правке сборки, он сообщает
surfaces: not user-visible - <reason>и останавливается.It first asks whether a user can see, do or be surprised by the change. If not, as with an internal refactor, a test or a build tweak, it reportssurfaces: not user-visible - <reason>and stops.Спершу він питає, чи може користувач побачити цю зміну, скористатися нею або здивуватися через неї. Якщо ні, як за внутрішнього рефакторингу, тесту чи правки збірки, він повідомляєsurfaces: not user-visible - <reason>і зупиняється. - Он перечисляет все места, где пользователь встречает возможность; они находятся в проекте, а не предполагаются: строки интерфейса (по строке на авторскую локаль), справка и подсказки, README и его переводы, пользовательская документация, сайт, журнал изменений, карточки в магазинах и каталогах пакетов, скриншоты, примеры, шаблоны. Он идёт от собственного манифеста поверхностей проекта, если он есть, и расширяет его. Таблица печатается до любых правок.It lists every place a user meets the capability, found in the project and never assumed: UI strings (one row per authored locale), help and tooltips, the README and its translations, user docs, the site, the change log, store or package listings, screenshots, examples and samples, templates. It starts from the project's own surface manifest if there is one and extends it. The table is printed before any edit.Він перелічує всі місця, де користувач зустрічає можливість; вони знаходяться в проєкті, а не припускаються: рядки інтерфейсу (по рядку на авторську локаль), довідка й підказки, README та його переклади, користувацька документація, сайт, журнал змін, картки в магазинах і каталогах пакетів, знімки екрана, приклади, шаблони. Він іде від власного маніфесту поверхонь проєкту, якщо він є, і розширює його. Таблиця друкується до будь-яких правок.
- В таблице три столбца: Surface, Touched / not applicable и Reason. Каждая строка с пометкой «не применимо» называет причину, например «на сайте нет списка возможностей» или «ни один скриншот не показывает это меню». Строка без причины не проходит проверку: именно так прячется забытая поверхность.The table has the columns Surface, Touched / not applicable and Reason. Every row marked not applicable names its reason, such as 'the site lists no features' or 'no screenshot shows this menu'. A row without one fails the check, because that is how a forgotten surface hides.У таблиці три стовпці: Surface, Touched / not applicable і Reason. Кожен рядок із позначкою «не застосовно» називає причину, наприклад «на сайті немає списку можливостей» або «жоден знімок екрана не показує це меню». Рядок без причини не проходить перевірку: саме так ховається забута поверхня.
- Он записывает изменение так, как пользователь хотел бы его услышать, сначала задача, на языке
<ARTIFACT_LANGUAGE>: «Invoices can be exported as PDF», а не «added a PDF renderer». Ключевое существительное, название самой вещи, - единственное имя, которое используют все поверхности, а каждая авторская локаль передаёт его своим закреплённым термином.It writes the change as a user would want it told, task first, in<ARTIFACT_LANGUAGE>: 'Invoices can be exported as PDF', not 'added a PDF renderer'. The key noun, the name of the thing, is the one name every surface uses, and each authored locale renders it with its own fixed term.Він записує зміну так, як користувач хотів би її почути, спершу завдання, мовою<ARTIFACT_LANGUAGE>: «Invoices can be exported as PDF», а не «added a PDF renderer». Ключовий іменник, назва самої речі, - єдине ім'я, яке використовують усі поверхні, а кожна авторська локаль передає його своїм закріпленим терміном. - Он правит каждую строку с пометкой «затронуто», каждую авторскую локаль в той же правке. Сгенерированная поверхность меняется в своём источнике и пересобирается, но не правится вручную.It edits every row marked touched, each authored locale in the same edit. A generated surface is changed in its source and regenerated, never edited by hand.Він править кожен рядок із позначкою «зачеплено», кожну авторську локаль у тій самій правці. Згенерована поверхня змінюється у своєму джерелі й перегенеровується, але не правиться вручну.
- Он ищет ключевое существительное и любое прежнее имя, которое оно заменяет, по всем затронутым поверхностям, в термине каждой локали, и читает найденное. Каждая поверхность должна говорить одно и то же под одним именем. Каждое устаревшее упоминание, например старое имя, убранный параметр или скриншот старого экрана, исправляется или попадает в отчёт.It greps the key noun, and any old name it replaces, across every touched surface in each locale's term, and reads the hits. Each surface must say the same thing under the same name. Every stale mention, such as an old name, a removed option or a screenshot of the old screen, is fixed or listed in the report.Він шукає ключовий іменник і будь-яке попереднє ім'я, яке той замінює, по всіх зачеплених поверхнях, у терміні кожної локалі, і читає знайдене. Кожна поверхня має казати те саме під одним іменем. Кожна застаріла згадка, наприклад старе ім'я, прибраний параметр чи знімок старого екрана, виправляється або потрапляє до звіту.
- Он повторно печатает таблицу с итоговым состоянием, затем одну строку:
surfaces: <sentence>. Touched N, not applicable N, stale mentions fixed N, listed N. Noun: "<noun>".It re-prints the table with the final state, then one line:surfaces: <sentence>. Touched N, not applicable N, stale mentions fixed N, listed N. Noun: "<noun>".Він повторно друкує таблицю з підсумковим станом, потім один рядок:surfaces: <sentence>. Touched N, not applicable N, stale mentions fixed N, listed N. Noun: "<noun>".
Что вы должны увидетьWhat you should seeЩо ви маєте побачити
Итоговая таблица и одна строка отчёта. Каждая затронутая поверхность говорит одно и то же под одним именем в каждой авторской локали, а отчёт называет каждую локаль, которой ещё не хватает.The final table and one report line. Every touched surface says the same thing under the same name in each authored locale, and the report names each locale still missing.Підсумкова таблиця й один рядок звіту. Кожна зачеплена поверхня каже те саме під одним іменем у кожній авторській локалі, а звіт називає кожну локаль, якої ще бракує.
СоветыTipsПоради
- Он стоит после сборки изменения и до закрытия тикета. /spec-tech направляет через него последнюю фазу docs-cleanup, если раздел 8 стратегической спеки требует обновить документацию, /spec-dev обновляет документацию после сборки без пересборки, а /spec-check пользовательские поверхности не правит: его строка User docs лишь проверяет результат.It sits after the build of a user-visible change and before the ticket closes. /spec-tech routes the final docs-cleanup phase through it when the strategic spec's section 8 mandates a docs update, /spec-dev runs doc updates after the build without a rebuild, and /spec-check never edits a user surface; its User docs row only checks the result.Він стоїть після збірки зміни й до закриття тікета. /spec-tech спрямовує через нього останню фазу docs-cleanup, якщо розділ 8 стратегічної спеки вимагає оновити документацію, /spec-dev оновлює документацію після збірки без перезбирання, а /spec-check користувацьких поверхонь не править: його рядок User docs лише перевіряє результат.
- Это правило файла правил «после изменения» в виде процедуры: новая видимая пользователю возможность попадает на каждую поверхность и в каждую авторскую локаль в том же изменении. Почему оно работает, объясняет лестница проверок.This is the rules file's post-change rule as a procedure: a new user-visible capability reaches every surface and every authored locale in the same change. The reason it holds is in the validation ladder.Це правило файлу правил «після зміни» у вигляді процедури: нова видима користувачеві можливість потрапляє на кожну поверхню й у кожну авторську локаль у тій самій зміні. Чому воно працює, пояснює драбина перевірок.
- Локали, которые никто в команде не пишет вручную, могут расходиться позже, одним проходом на границе релиза, если она у проекта есть;
/surfacesлишь называет каждую недостающую. У сайта или непрерывно публикуемой библиотеки такой границы нет, и там весь разворот остаётся частью одной правки.Locales nobody on the team writes by hand may fan out later, in one pass at a release boundary, where the project has one;/surfacesonly names each one still missing. A site or a rolling library has no such boundary, and there the whole fan-out stays part of the one edit.Локалі, які ніхто в команді не пише вручну, можуть розходитися пізніше, одним проходом на межі релізу, якщо вона в проєкту є;/surfacesлише називає кожну відсутню. У сайту чи бібліотеки, що публікується безперервно, такої межі немає, і там увесь розворот лишається частиною однієї правки. - Расхождения исправляются только в строках, которых вы касаетесь; более старые попадают в отчёт как находка или откладываются через /park. Второе имя для той же вещи - дефект, а не вопрос стиля: /ui-clarify спрашивает о новом синониме до сборки, а эта команда ищет старое имя после неё.Drift is fixed only in the lines you touch; older drift is reported as a finding or parked with /park. A second name for the same thing is a defect, not a style choice, so /ui-clarify asks about a new synonym before the build and this command greps for the old name after it.Розбіжності виправляються лише в рядках, яких ви торкаєтеся; давніші потрапляють до звіту як знахідка або відкладаються через /park. Друге ім'я для тієї самої речі - дефект, а не питання стилю: /ui-clarify питає про новий синонім до збірки, а ця команда шукає старе ім'я після неї.
Связанные функцииRelated functionsПов'язані функції
- Разбить утверждённую спеку на поэтапный план с проверкой каждого шагаTurn an approved spec into a phased plan with a check on every stepРозбити затверджену спеку на поетапний план із перевіркою кожного кроку
/spec-techпишет тактический план: индекс и файлы фаз, каждый шаг кончается статической проверкой, а порядок фаз сам проверяется до смены статуса./spec-techwrites the tactical plan: an index and phase files, each step ending in a static check, with the phase order self-reviewed before the status flips./spec-techпише тактичний план: індекс і файли фаз, кожен крок закінчується статичною перевіркою, а порядок фаз сам перевіряється до зміни статусу. - Выполнить тактический план по одному проверенному шагуImplement a tactical plan one verified step at a timeВиконати тактичний план по одному перевіреному кроку
/spec-devидёт по плану шаг за шагом, проверяет каждый шаг до отметки о готовности и жёстко останавливается на первом сбое или неоднозначности, не угадывая./spec-devruns the plan step by step, checks each step before marking it done and hard-stops on the first failure or ambiguity instead of guessing forward./spec-devіде за планом крок за кроком, перевіряє кожен крок до позначки про готовність і жорстко зупиняється на першому збої чи неоднозначності, не вгадуючи. - Проверить реализацию по спеке и выставить статус тикета по фактуAudit a build against its spec and set the ticket status from realityПеревірити реалізацію за спекою й виставити статус тікета за фактомСверяет тикет с тем, что реально лежит в файлах, и выставляет статус: Verified, Partial или Broken, а пока открыта ручная проверка, BlockNeedUserTest.Audits a ticket against what the files really contain and sets its status: Verified, Partial or Broken, or BlockNeedUserTest while a manual check is open.Звіряє тікет із тим, що справді лежить у файлах, і виставляє статус: Verified, Partial чи Broken, а поки відкрита ручна перевірка, BlockNeedUserTest.
- Решить, что увидит пользователь, до начала разработкиSettle what the user will see before you build itВирішити, що побачить користувач, до початку розробки
/ui-clarifyне пускает к реализации, пока не определены место, видимость, формулировки, сбои и путь каждого читателя, и завершаетсяBLOCKEDилиREADY./ui-clarifyblocks implementation until placement, visibility, wording, failure behaviour and each reader's path are explicit, and ends inBLOCKEDorREADY./ui-clarifyне пускає до реалізації, доки не визначено місце, видимість, формулювання, збої та шлях кожного читача, і завершуєтьсяBLOCKEDабоREADY. - Провести тикет по жизненному циклу с проверкой на каждом шагеMove a ticket through the lifecycle with a gate at every stepПровести тікет життєвим циклом із перевіркою на кожному кроціТикет - это один Markdown-файл со строкой статуса. Каждый навык требует входной статус и выдаёт выходной, поэтому этап нельзя пропустить на глаз.A ticket is one Markdown file with a status line. Each skill requires an entry status and produces an exit status, so no stage is skipped on a hunch.Тікет - це один Markdown-файл із рядком статусу. Кожна навичка вимагає вхідний статус і видає вихідний, тож етап не можна пропустити на око.