Use the kit for documents, analysis and contracts

Функции в этом руководствеFunctions in this guideФункції в цьому посібнику

Подогнать метод под работу, которая не кодFit the method to work that is not codeПідігнати метод під роботу, що не є кодомСопоставьте слова метода с вашим видом работы, найдите проверку, которая у вас уже есть, и удалите правила слоя кода, которым нечего применять.Map the method's nouns to your kind of work, find the check you already have, and delete the code-layer rules that have nothing to apply to.Зіставте слова методу з вашим видом роботи, знайдіть перевірку, яка у вас уже є, і видаліть правила шару коду, яким нічого застосовувати.
Заполнить плейсхолдеры файла правил под свой проектFill the placeholders of the rules file for your projectЗаповнити плейсхолдери файлу правил під свій проєктЗаполните одиннадцать токенов первого яруса, нужных любому проекту, шесть токенов слоя кода только если проект собирается или запускается, и удалите правила без предмета.Fill the eleven tier-1 tokens every project needs, the six code-layer tokens only if the project builds or runs, and delete the rules that have no subject.Заповніть одинадцять токенів першого ярусу, потрібних усім, шість токенів шару коду лише якщо проєкт збирається чи запускається, і видаліть правила без предмета.
Доказать, что правка работает, прежде чем объявлять её готовойProve a change works before calling it doneДовести, що правка працює, перш ніж оголошувати її готовоюВозьмите самую дешёвую проверку, которая доказывает именно эту правку, запишите ожидаемое и фактическое и называйте шаг готовым, только прочитав результат.Pick the lowest check that proves this change, write down expected and actual, and call the step done only after you have read the result.Візьміть найдешевшу перевірку, що доводить саме цю правку, запишіть очікуване й фактичне та називайте крок готовим, лише прочитавши результат.
Научить агента искать, а не угадыватьMake the agent look things up instead of guessingНавчити агента шукати, а не вгадуватиФиксированный порядок поиска и, для большого проекта, поддерживаемый индекс вашего материала: каждый путь, символ и API, названные агентом, проверены.A fixed order for finding things and, for a big project, a maintained index of your material, so every path, symbol and API the agent states has been verified.Фіксований порядок пошуку і, для великого проєкту, підтримуваний індекс вашого матеріалу: кожен шлях, символ і API, названі агентом, перевірені.
Превратить технические заметки в понятные, дружелюбные доки и тексты интерфейсаTurn technical notes into clear, friendly docs and UI copyПеретворити технічні нотатки на зрозумілі, дружні доки й тексти інтерфейсуАгент среднего уровня пишет и переписывает документацию, README, справку, онбординг, заметки к релизу и тексты интерфейса дружелюбно, сохраняя технические факты.A mid-tier agent writes or rewrites docs, README, help, onboarding, release notes and interface strings in a friendly voice, with every technical fact kept.Агент середнього рівня пише чи переписує документацію, README, довідку, онбординг, нотатки до релізу та рядки інтерфейсу дружнім тоном, зберігаючи всі технічні факти.

ШагиStepsКроки

Пересчитайте пять вещей, которые предполагает метод: рабочая папка с историей, к которой можно откатиться; артефакты; единицы работы с честным статусом; проверки; агент, умеющий читать и писать ваши файлы. Нет истории? Копируйте папку перед большой правкой. Затем найдите свой столбец в таблице словаря в разделе формы проектов: софт, данные и аналитика, тексты и документация, юридическое и комплаенс, операции и админ. Скопируйте этот столбец в репозиторий, чтобы новичок или агент мог сопоставить правило с вашей реальностью.Count the five things the method assumes: a workspace with history you can roll back, artifacts, work items with a true status, checks, and an agent that can read and write your files. No history? Copy the folder before a big change. Then find your column in the vocabulary table of project shapes: software, data and analysis, writing and documentation, legal and compliance, or operations and admin. Copy that column into the repo, so a newcomer or an agent can map a rule to your reality.Перелічіть п'ять речей, які припускає метод: робоча тека з історією, до якої можна відкотитися; артефакти; одиниці роботи з чесним статусом; перевірки; агент, що вміє читати й писати ваші файли. Немає історії? Копіюйте теку перед великою правкою. Потім знайдіть свій стовпець у таблиці словника в розділі форми проєктів: софт, дані та аналітика, тексти й документація, юридичне та комплаєнс, операції та адмін. Скопіюйте цей стовпець у репозиторій, щоб новачок чи агент міг зіставити правило з вашою реальністю.
Заполните плейсхолдеры первого яруса этими словами: <WORK_ROOT> - где лежит настоящий материал, <INDEX_DOC> - карта, которую агент читает первой (словарь данных, оглавление, реестр дел), <ARTIFACT_LANGUAGE> - язык сдачи работы: юрист, переводчик или аналитик может поставить язык самого документа, <READONLY_ZONES> - сырые данные и всё уже исполненное или поданное, либо none, <ID_SCHEME> - схема номеров тикетов. <CHECK_CMD> - проверка, которую вы назовёте на четвёртом шаге. В docs/REPLACES.md есть готовые значения для каждого вида проекта.Fill the tier-1 placeholders in those words: <WORK_ROOT> is where your real material lives, <INDEX_DOC> the map the agent reads first (a data dictionary, a table of contents, a matter index), <ARTIFACT_LANGUAGE> the language you deliver in, which a lawyer, translator or analyst may set to the document's own, <READONLY_ZONES> the raw data and anything already executed or filed, or none, and <ID_SCHEME> your ticket ids. <CHECK_CMD> is the check you name in step 4. docs/REPLACES.md has worked values for each kind of project.Заповніть плейсхолдери першого ярусу цими словами: <WORK_ROOT> - де лежить справжній матеріал, <INDEX_DOC> - мапа, яку агент читає першою (словник даних, зміст, реєстр справ), <ARTIFACT_LANGUAGE> - мова здавання роботи: юрист, перекладач чи аналітик може поставити мову самого документа, <READONLY_ZONES> - сирі дані й усе вже виконане чи подане, або none, <ID_SCHEME> - схема номерів тікетів. <CHECK_CMD> - перевірка, яку ви назвете на четвертому кроці. У docs/REPLACES.md є готові значення для кожного виду проєкту.
Удаляйте то, чему нечего применять, а не приспосабливайте. По формам проектов уходят слои и направление зависимостей (<ARCH_LAYERS>), тонкие точки входа, фасад логирования (<LOGGER>), метки верификации, если ваши артефакты не дают журнала, по которому можно искать, и ступень компиляции в лестнице: ваша лестница просто начинается со следующей ступени. Вместе с ними уходят структурные правила в docs/CODE_QUALITY.md и строки про стек в агентах implementer и rd-lead; места перечислены в разделе о плейсхолдерах.Delete what has no subject, instead of adapting it. In project shapes these go: layering and dependency direction (<ARCH_LAYERS>), thin entry points, the logging facade (<LOGGER>), verification tags unless your artifacts produce a log you can grep, and the compile rung of the ladder. Your ladder simply starts at the next rung. The structural rules in docs/CODE_QUALITY.md and the stack lines in the implementer and rd-lead agents go too; the placeholder page lists the places.Видаляйте те, чому нічого застосовувати, а не пристосовуйте. За формами проєктів йдуть шари й напрям залежностей (<ARCH_LAYERS>), тонкі точки входу, фасад логування (<LOGGER>), мітки верифікації, якщо ваші артефакти не дають журналу, по якому можна шукати, і щабель компіляції в драбині: ваша драбина просто починається з наступного щабля. Разом із ними йдуть структурні правила в docs/CODE_QUALITY.md і рядки про стек в агентах implementer та rd-lead; місця перелічено в розділі про плейсхолдери.
Найдите свою проверку, спросив себя: что было бы стыдно отправить? Каждый ответ - проверка: сумма, которая должна сойтись с другой суммой; имя, которое должно существовать в другом месте; структура, которая должна держаться; ссылка, которая должна разрешаться; сборка, которая должна получиться. Запишите её один раз командой или описанной процедурой и поставьте в <CHECK_CMD>. Какая ступень нужна каждому виду правки, показывает лестница проверок.Find your check by asking what you would be embarrassed to send. Each answer is a check: a total that must match another total, a name that must exist elsewhere, a structure that must hold, a reference that must still resolve, a rendering that must succeed. Write it down once as a command or a stated procedure and put it in <CHECK_CMD>. The validation ladder shows which rung each kind of change needs.Знайдіть свою перевірку, спитавши себе: що було б соромно відправити? Кожна відповідь - перевірка: сума, яка має зійтися з іншою сумою; ім'я, яке має існувати в іншому місці; структура, що має триматися; посилання, що має розв'язуватися; збірка, що має вдатися. Запишіть її один раз командою або описаною процедурою й поставте в <CHECK_CMD>. Який щабель потрібен кожному виду правки, показує драбина перевірок.
Доказывайте каждую правку самой низкой подходящей ступенью. Документ или текст: найдите grep'ом в файле то, что, по вашим словам, написали. Скрипт: запустите, и он завершится с 0 или выдаст ожидаемый артефакт. Конфигурация или файл сборки: целевая сборка проходит. Набор данных, таблица или договор: сначала структурная проверка, затем сверка. Записывайте expected до запуска и actual после. Верхняя ступень обычно за человеком, а проверка человеком, которой ещё не было, - не зачёт, а ожидание.Prove each change at the lowest rung that fits. A document or text: grep the file for what you claim you wrote. A script: run it, and it exits 0 or produces the expected artifact. A config or build file: the target build passes. A dataset, sheet or contract: the structural check first, then the reconciliation. Write expected before the run and actual after. The top rung is usually a human, and a human check that has not happened is pending, not a pass.Доводьте кожну правку найнижчим відповідним щаблем. Документ чи текст: знайдіть grep'ом у файлі те, що, за вашими словами, написали. Скрипт: запустіть, і він завершиться з 0 або видасть очікуваний артефакт. Конфігурація чи файл збірки: цільова збірка проходить. Набір даних, таблиця чи договір: спершу структурна перевірка, потім звірка. Записуйте expected до запуску й actual після. Верхній щабель зазвичай за людиною, а перевірка людиною, якої ще не було, - не залік, а очікування.
Превратите индекс кода в индекс вашего материала: словарь данных, библиотеку формулировок, реестр документов или таблицу источников. Правила поиска те же: называйте путь или имя, только проверив их, обращайтесь к индексу до поиска, пересобирайте его после изменений и не правьте вручную. Реестр документов проверяйте в обе стороны: каждая запись указывает на файл, а у каждого файла области есть запись или названное исключение. Заводите индекс, только когда поиск стал налогом; устаревший хуже, чем никакого.Turn the code index into an index of your material: a data dictionary, a clause library, a document register or a table of sources. The research rules stay the same: state a path or a name only after you verified it, query the index before searching, regenerate it after changes and never hand-edit it. Check a document register both ways: every record points at a file, and every file in the area has a record or a named exclusion. Add an index only when searching has become a tax; a stale one is worse than none.Перетворіть індекс коду на індекс вашого матеріалу: словник даних, бібліотеку формулювань, реєстр документів чи таблицю джерел. Правила пошуку ті самі: називайте шлях чи ім'я, лише перевіривши їх, звертайтеся до індексу до пошуку, перезбирайте його після змін і не правте вручну. Реєстр документів перевіряйте в обидва боки: кожен запис указує на файл, а в кожного файлу області є запис або названий виняток. Заводьте індекс, лише коли пошук став податком; застарілий гірший, ніж жодного.
Составьте свой список признаков мусора: у семи кодовых шаблонов есть аналоги в ваших артефактах. docs/CODE_QUALITY.md называет приметы, которые агент выдаёт охотно, которые выглядят нормально и портят кодовую базу; ваши могут быть такими: текст, пересказывающий свой заголовок, число без источника, плейсхолдер, забытый в готовом документе, устаревшая ссылка. Собирайте список из того, что реально поймали на ревью, а не из воображения.Write your own quality list, because the seven code patterns have analogues in your artifacts. docs/CODE_QUALITY.md names what an agent emits that looks fine and rots a codebase; yours might be text that restates its heading, a number with no source, a placeholder left in a finished document or a stale cross-reference. Build the list from what you actually caught in review, not from imagination.Складіть власний список ознак сміття: у семи кодових шаблонів є аналоги у ваших артефактах. docs/CODE_QUALITY.md називає прикмети, які агент видає охоче, що виглядають нормально й псують кодову базу; ваші можуть бути такими: текст, що переказує свій заголовок, число без джерела, плейсхолдер, забутий у готовому документі, застаріле посилання. Збирайте список із того, що справді впіймали на рев'ю, а не з уяви.
Само письмо отдайте doc-writer, когда работа - документ, README, справка, онбординг, заметки к релизу или тексты интерфейса. Он сначала определяет аудиторию, сохраняет каждый технический факт, нужный тексту, при расплывчатом источнике просит у вас недостающее решение, а не заполняет пробел стилем, а юридические тексты, условия использования и машиночитаемые артефакты оставляет формальными и нейтральными.Hand the writing to doc-writer when the work is a doc, a README, help text, onboarding, release notes or interface strings. It identifies the audience first, keeps every technical fact the text needs, asks you for a missing decision when the source is vague instead of filling the gap with style, and keeps legal text, terms of service and machine-readable artifacts formal and neutral.Саме письмо віддайте doc-writer, коли робота - документ, README, довідка, онбординг, нотатки до релізу чи тексти інтерфейсу. Він спершу визначає аудиторію, зберігає кожен технічний факт, потрібний тексту, за розпливчастого джерела просить у вас бракуюче рішення, а не заповнює прогалину стилем, а юридичні тексти, умови користування та машиночитні артефакти лишає формальними й нейтральними.
Знайте границы. Для одного сплошного документа с одним автором механика тикетов - лишняя нагрузка. Если работа не состоит из файлов, kit сказать нечего: сначала запишите её, тогда это станет проектом. Если у проекта несколько форм, не плодите своды правил: держите один и позвольте командам проверки различаться по областям, как docs/VALIDATION.md ограничивает проверку видом изменения. Подробности - в разделе формы проектов.Know the limits. For one flowing document with one author, the ticket machinery is overhead. Where the work is not files, the kit has nothing to say: write it down first, and then it is a project. If your project has several shapes, do not fork the rulebook: keep one and let the check commands differ by area, the way docs/VALIDATION.md scopes a gate by the kind of change. The details are in project shapes.Знайте межі. Для одного суцільного документа з одним автором механіка тікетів - зайве навантаження. Якщо робота не складається з файлів, kit нічого не скаже: спершу запишіть її, тоді це стане проєктом. Якщо в проєкту кілька форм, не плодіть зводи правил: тримайте один і дозвольте командам перевірки відрізнятися за ділянками, як docs/VALIDATION.md обмежує перевірку видом зміни. Подробиці - в розділі форми проєктів.

Что вы должны увидетьWhat you should seeЩо ви маєте побачити

Ваш столбец таблицы словаря лежит в репозитории, самая дешёвая настоящая проверка названа в <CHECK_CMD>, правила слоя кода без предмета удалены, а не приспособлены, а законченная правка заканчивается строками expected и actual, которые вы прочли.Your column of the vocabulary table is in the repo, the cheapest real check is named in <CHECK_CMD>, the code-layer rules without a subject are deleted rather than adapted, and a finished change ends with expected and actual lines you have read.Ваш стовпець таблиці словника лежить у репозиторії, найдешевшу справжню перевірку названо в <CHECK_CMD>, правила шару коду без предмета видалено, а не пристосовано, а завершена правка закінчується рядками expected і actual, які ви прочитали.

Применять kit для документов, анализа и договоровUse the kit for documents, analysis and contractsЗастосовувати kit для документів, аналізу й договорів

Функции в этом руководствеFunctions in this guideФункції в цьому посібнику

ШагиStepsКроки

Термины на этой страницеTerms on this pageТерміни на цій сторінці