ukrainian-tech-docs · git:20261030.553e302 · 2026-10-30 · sha256 a1d880ac35f342db
ukrainian-tech-docs git:20261030.553e302A
Immutable. This exact content never changes and is served at /api/v1/blob/a1d880ac35f342db.
---
name: ukrainian-tech-docs
description: >
Пакет письма технічної документації українською: контракт роботи перед письмом,
дисципліна джерел і маркерів невизначеності, жива мова без ШІ-кліше, жанрові
правила (HLD, LLD, ADR, ТЗ, How-to/runbook, покрокова інструкція, Concept,
Reference, Troubleshooting,
постмортем, схема, план), вилки й питання до суміжників, вивантаження назовні
(.docx, .xlsx, .pdf, лист). Використовувати завжди, коли користувач пише, редагує,
перевіряє або вивантажує будь-який технічний документ українською, малює схему
до нього, формулює питання до суміжного підрозділу чи реєстр відкритих питань,
а також на прохання "переписати документ", "почистити текст", "прибрати воду",
"оформити як нотатку", "зібрати docx", "перекласти технічний текст українською",
"діагностика кальок", "перевір переклад", "фактчекінг", "перевір факти",
"звір із документацією", "тест читача", "чи зрозуміло це без мене", "ТЗ",
"технічне завдання", "специфікація вимог", "перевір ТЗ", "покрокова інструкція",
"степ бай степ", "step-by-step".
---
# Письмо технічних документів
Пакет несе все, що працює безвідносно проєкту й користувача. Дані проєкту —
імена джерел, реєстр кодів, словник термінів, палітри, профілі вивантажень —
лежать у самому проєкті й підключаються через **профіль проєкту**.
Цей файл несе три речі: контракт роботи, таблицю «стадія × жанр → файл» і правило
роботи з профілем. Зміст правил лежить у `references/` і читається за таблицею,
а не цілком.
## 1. Контракт роботи
Фіксується на вході, до першого рядка тексту. Це не план і не обговорення:
сім рядків, які виконавець називає сам і показує власникові. Заперечення
міняє рядок; відсутність заперечення лишає його чинним.
| Рядок | Що в ньому |
|---|---|
| Жанр | Називає власник на вході, або він виводиться з контексту: з назви документа, з теки, з того, що власник просить. Жанру не видно — одне питання, не здогад |
| Читач | Хто читатиме й що він уже знає. Від цього залежить, що пояснюється, а що ні |
| Вихід назовні | Лишається документ у сховищі проєкту чи йде читачеві поза командою. Другий випадок вмикає стадію вивантаження |
| Межа глибини | Для пари HLD/LLD — що лишається в цьому документі, а що йде в сусідній. **Виняток із межі записується тут**: «у цьому HLD значення X лишається в тілі, бо …». Виняток, не записаний у контракт, є дефектом, а не рішенням |
| Звідки наповнення | Джерела, з яких документ пишеться: ноти, файли, документація, стенд. Названий ресурс читається до того, як про нього писати |
| Не робимо | Що з теми в цей документ не йде. Формулюється перед входом у кожен розділ заново |
| Стадії | Які рядки таблиці розд. 3 пройде робота. Стадію визначає те, що відбувається з текстом, а не результат роботи: текст змінюється — у переліку є Письмо й Самоперевірка. Наприкінці цей рядок звіряється із закривальним рядком (розд. 3) |
**Дрібна правка.** Для правки в межах одного абзацу без зміни змісту — описка,
правопис, розділовий знак, заміна слова — виконавець показує лише рядки «Жанр»
і «Стадії»; решта рядків діє за замовчуванням. Правка, що зачіпає твердження,
суб'єкт дії чи сусідній абзац, іде з повним контрактом. Правка, яку повертають
у розмові й не записують у сховище, переліків `evidence.md`, розд. 7, не
потребує: вони супроводжують запис.
Контракт живе в розмові. У документ він не пишеться, крім рядка «Не робимо»,
який за жанровим файлом може осідати в заготовці розділу.
Планування — окрема стадія, і скіл її **не пропонує**. Вона вмикається тільки
за явним посилом власника; тоді читається `references/genres/plan.md`.
## 2. Профіль проєкту
Профіль — один файл у проєкті, заповнений за `templates/project-profile.md`.
Він є точкою входу скіла в проєкт: скіл знає слоти, профіль каже, де в цьому
проєкті лежить їхній вміст.
| Слот | Що скіл із нього бере |
|---|---|
| Сходи джерел | Імена джерел на кожному із шести рівнів пошуку (`evidence.md`, розд. 2) |
| Реєстр кодів із колонкою опори | Які внутрішні коди існують і чи можна на код спиратись як на підставу (`evidence.md`, розд. 5) |
| Термінологія | Словник проєкту: які слова вживаються, яких уникають (`language.md`, частина 2) |
| Куди йдуть відкриті питання | Реєстр або ноти, куди переїжджає питання з адресатом (`forks-and-questions.md`) |
| Реєстр зовнішніх документів | Робочі адреси документів поза сховищем проєкту — для посилань у вивантаженні (`export.md`, розд. 3) |
| Профілі вивантаження | Перелік заповнених `export-profile` для конкретних файлів (`export.md`, розд. 6) |
| Палітри схем | Кольори, набори фігур, розміщення файлів схем (`genres/schema.md`) |
| Місце конвенції метаданих | Де лежать правила frontmatter, тегів, статусів. Скіл метаданих не визначає взагалі |
| Проєктні жанри | Жанри, описані лише в проєкті, і де вони лежать (розд. 3, «Перелік жанрів відкритий») |
| Правила комунікації | Звертання до кількох отримувачів, чи може лист бути першоджерелом факту, чи ставлять питання в коментарі трекера (`genres/general.md`, розд. 3 і 7) |
| Правила проєкту, старші за пакет | Місця, де проєкт свідомо відходить від правила пакета, з причиною. Записане тут — уже рішення; незаписана розбіжність іде за правилом «Старшинство» нижче |
**Порядок.** На вході знайти профіль: вказівник на нього стоїть в інструкціях
проєкту або в його кореневому файлі для агента. Знайшов — прочитати до контракту.
**Що таке вхід.** Вхід — момент, коли із запиту видно, що результатом буде документ,
його правка, аудит або вивантаження. Він раніше за розвідку: профіль і жанровий
файл читаються до матеріалу, бо саме вони кажуть, що в матеріалі шукати. Контракт
показується після розвідки — рядок «Звідки наповнення» без неї не заповнити, — але
до першого рядка тексту й до окреслення обсягу. Обсяг, окреслений до жанрового
файла, складається без межі глибини й без «Не робимо».
**Профілю немає.** Скіл працює на власних правилах, а кожне місце, де потрібен
вміст слота, називається вголос: «сходи джерел без імен — беру форму, імена
питаю». Такі питання йдуть одним пакетом з іншими питаннями цієї роботи
(`references/forks-and-questions.md`, розд. 9). Вигадувати вміст слота не можна.
Якщо робота в проєкті триває довше за один документ — один раз запропонувати
заповнити профіль за шаблоном.
**Старшинство.** Дані профілю старші за приклади скіла. Правило скіла старше
за звичку сусіднього документа. Розбіжність між правилом скіла й правилом
проєкту не розв'язується мовчки: показати обидві редакції і дочекатись рішення.
## 3. Стадія × жанр → файл
Читається тільки те, що стоїть у рядках поточних стадій. Шляхи — від `references/`.
**Стадії не взаємовиключні.** Робота рідко стоїть в одному рядку: вивантаження,
під час якого переписано зміст, — це ще й Письмо та Самоперевірка; аудит із
правкою — теж; фактчекінг, за яким правиться текст, — теж. Стадію визначає те,
що відбувається з текстом, а не назва результату. Текст змінюється — Письмо
й Самоперевірка обов'язкові, яку б стадію не названо в запиті. Жоден рядок
таблиці не замінює іншого.
**Правка вноситься одним заходом.** Спершу зібрати всі зміни й перевірити їх,
потім записати. Кілька записів поспіль, кожен з яких виправляє попередній,
означають, що перевірка йшла після запису, а не до нього.
**Зауваження до одного місця — сигнал перевірити весь текст.** Коли власник
вказує на ваду в одному реченні, той самий клас помилки шукати по всьому
документу: зміст, логіка, адресат вимоги, мова. Правка лише процитованого місця
лишає ту саму ваду поруч.
| Стадія | Коли | Читати |
|---|---|---|
| Вхід | перед першим рядком | цей файл · профіль проєкту · `genres/<жанр>.md` · `genres/general.md` — з кожним жанром |
| Письмо | пишеться або правиться текст | `evidence.md` · `language.md` · `genres/<жанр>.md` |
| Вилка | у тексті з'явився вибір, відкрите питання або звернення до суміжника | `forks-and-questions.md` |
| Схема | у розділі є предмет для схеми або схема правиться | `genres/schema.md` · слот палітр профілю |
| Самоперевірка | перед тим як вважати текст готовим | чек-лист у `genres/<жанр>.md` · фінальний прохід у `language.md` · розд. 7 `evidence.md` перед записом · ноти слотів реєстру кодів і термінології профілю — самі ноти, а не лише профіль, що на них вказує |
| Аудит чужого тексту | перевірка готового документа без правки; «переписати», «почистити», «прибрати воду» — замовлена чистка, поріг S2 її не блокує (`language.md`, «Вага ознак») | `language.md`, розділ «Аудит» · `genres/general.md`, розд. 5 · `genres/<жанр>.md` · перевірка мови — ще `language.md`, розділ «Діагностика кальок», окремим блоком звіту або рядком «не проходив» |
| Тест читача | «тест читача», «чи зрозуміло це без мене»; одним рядком пропонується перед вивантаженням читачеві поза командою, сам не вмикається; нічого не править | `genres/general.md`, розд. 6 |
| Діагностика кальок | «діагностика кальок», «перевір переклад», фінальний прогін мови по готових документах; нічого не править, повертає таблицю підозр на вердикт власника | `language.md`, розділ «Діагностика кальок» · слоти термінології і реєстру кодів профілю · `genres/schema.md`, розд. 3 — якщо в документа є схеми |
| Фактчекінг | «фактчекінг», «перевір факти», «звір із документацією», «чи це досі так»; нічого не править, повертає таблицю тверджень на вердикт власника; виняток — покрокова інструкція (`genres/stepbystep.md`, розд. 7) | `factcheck.md` · `evidence.md`, розд. 1–3 · слоти сходів джерел і реєстру кодів профілю |
| Вивантаження | документ іде назовні: `.docx`, `.xlsx`, `.pdf`, лист, повідомлення | `export.md` · профіль вивантаження з проєкту, якщо він є · для `.docx`, `.xlsx`, `.pdf` — мовний прогін перед збіркою (`export.md`, розд. 0): `language.md`, розділи «Діагностика кальок» і «Фінальний прохід» |
| Планування | тільки за явним посилом власника | `genres/plan.md` |
| Жанр | Файл | Що це |
|---|---|---|
| HLD | `genres/hld.md` | концепції, рішення, компроміси; без значень конкретної збірки |
| LLD | `genres/lld.md` | значення, адреси, параметри, порядок кроків як наслідок рішень HLD |
| ADR | `genres/adr.md` | одне архітектурне рішення з варіантами й компромісом |
| ТЗ | `genres/tz.md` | що потрібно і як це приймають; лише виконувані пункти, без маркерів і відкритих питань |
| How-to, runbook, процедура | `genres/howto.md` | кроки з перевіркою і відкатом; покриття розгортання і експлуатації |
| Покрокова інструкція | `genres/stepbystep.md` | лише дії для читача, який їх ще не виконував: пререквізити з перевіркою, крок за кроком, жодного твердження без джерела |
| Concept | `genres/concept.md` | як працює компонент |
| Reference | `genres/reference.md` | таблиці, схеми даних, коди; без прози |
| Troubleshooting | `genres/troubleshooting.md` | запис випадку: симптом першим |
| Постмортем | `genres/postmortem.md` | закриття інциденту після відновлення сервісу |
| Схема | `genres/schema.md` | топологія і механізм; читаність у друці |
| План | `genres/plan.md` | тільки за явним посилом |
| Усе інше | `genres/general.md` | правила для всіх жанрів; лист, нотатка, README, коментар у трекері задач, аудит готового документа |
**Перелік жанрів відкритий.** Жанр без власного файла працює на `general.md`.
Жанр, який існує тільки в одному проєкті, описується в самому проєкті,
і профіль на нього вказує; у пакет він іде тоді, коли знадобився в другому.
### Закривальний рядок
Перед словом «готово», перед віддачею файла й перед записом у сховище виконавець
пише рядок стадій — які стадії пройдено і які файли на кожній прочитано:
`Стадії: вхід (SKILL, профіль, genres/hld) · письмо (evidence, language) · самоперевірка (чек-лист жанру, фінальний прохід, реєстр кодів, словник) · вивантаження (export, діагностика кальок)`
У рядку стоять файли, які справді прочитано в цій роботі, а не назви стадій із
таблиці: так рядок звіряється з викликами інструментів у розмові. Рядок
звіряється з рядком «Стадії» контракту. Стадії з контракту в рядку немає —
«готово» не пишеться: або стадію пройти, або назвати, чому її пропущено.
**Підсумок маркерів.** Поруч із рядком стадій іде перелік маркерів
`[на погодження]` і `[припущення]`, поставлених у цій роботі, по рядку на
маркер: де стоїть · що вирішено чи припущено · чия зона. Виконавець показує
перелік завжди, навіть порожній: «маркерів не ставив». Мовчання лишає
`[на погодження]` чинним для подальшої роботи, але не погодженим
(`forks-and-questions.md`, розд. 5), а `[припущення]` — твердженням, якого
ніхто не перевіряв: непоказаний маркер стає рішенням без погодження. На
вивантаженні `[на погодження]` без явної відповіді розкривається словами стану
(«Пропонується…», «Очікує погодження…») або йде у відкриті питання, а не
рішенням (`export.md`, розд. 4). Виняток — передача ТЗ у роботу: там мовчання не діє, і власник
закриває кожен рядок явно (`genres/tz.md`, розд. 2).
Підсумок іде разом із двома переліками `evidence.md`, розд. 7, і в тому самому
порядку: у сховище з історією змін запис іде одразу, а підсумок — у звіті
відразу після нього; запис назовні чекає відповіді на підсумок. `[припущення]`, уже внесене
в перелік тверджень без джерела, у підсумку вдруге не стоїть.
**Типи не змішуються в одному файлі.** Якщо в how-to з'явився розділ «Як це
працює всередині» — він виноситься в Concept, і ставиться посилання. Структура
тіла документа й поле жанру в метаданих проєкту — різні осі: значення поля
визначає конвенція метаданих проєкту, не цей пакет.
## 4. Чого пакет не робить
- Не визначає метаданих: frontmatter, теги, статуси, нумерацію — це конвенція проєкту.
- Не пропонує планування і не вмикає його сам.
- Не тримає даних проєкту: імен джерел, кодів, палітр, адрес. Приклади у файлах — приклади.
- Не застосовується до художніх текстів.
## 5. Склад пакета
```
SKILL.md
references/
evidence.md джерела, маркери, коди, перелік перед записом
factcheck.md фактчекінг готового тексту
language.md мова, терміни, аудит чужого тексту
export.md вивантаження назовні
forks-and-questions.md вилки, питання до суміжників, реєстри питань
genres/ hld · lld · adr · tz · howto · stepbystep · concept · reference ·
troubleshooting · postmortem · schema · plan · general
postmortem/ довідники до жанру постмортему
templates/
project-profile.md шаблон профілю проєкту
export-profile.md шаблон профілю вивантаження для конкретного файлу
postmortem-template.md шаблон постмортему
action-item-tracker.md трекер дій після постмортему
```
## 6. Джерела пакета
Готові скіли й статті, з яких узято ідеї. Текст пакета написано наново
українською; англомовні правила перенесено лише там, де вони працюють для
української мови.
- humanizer, MIT: [blader/humanizer](https://github.com/blader/humanizer) —
ознаки ШІ-тексту для частини 1 `language.md` і перевірка «що тут досі звучить
як ШІ» і питання, що додано чи втрачено після правки; англійську специфіку
(тире, регістр заголовків, лапки) як ознаки ШІ не перенесено. Регістр заголовків
і лапки записано окремо, як норму правопису (`genres/general.md`, розд. 1). Залишки чату, заголовок,
повторений першим реченням, і текст про документ замість предмета —
[SKILL.md, §22, §24, §25](https://github.com/blader/humanizer/blob/225a6f3/SKILL.md)
(`language.md`, 1.13).
- humanizer, форк, MIT: [brandonwise/humanizer](https://github.com/brandonwise/humanizer).
- Українські адаптації humanizer, усі MIT, узято лише ідеї, текст власний:
[iosipov27/ukrainian-humanizer](https://github.com/iosipov27/ukrainian-humanizer) —
голос автора перед чисткою (`language.md`, «Переписування зберігає зміст»);
[asaulyuk/humanizer-ukr](https://github.com/asaulyuk/humanizer-ukr) — активні
дієприкметники (1.7), канцелярит й аналітичний ступінь порівняння (1.4), кличний
відмінок і типографіка (`genres/general.md`, розд. 1, 3), невидимі символи
(`export.md`, розд. 0);
[tatet-ua/tatet-humanizer](https://github.com/tatet-ua/tatet-humanizer) —
службові мітки чату (1.13), хвостове заперечення (1.9), прийоми самої чистки;
[majlovskij-cmd/humanizer-ua](https://github.com/majlovskij-cmd/humanizer-ua) —
приклади кальок із російської («Діагностика кальок»);
[OpenMindUA/SimpleUkrainian](https://github.com/OpenMindUA/SimpleUkrainian) —
умова перед дією (`genres/howto.md`, розд. 2), висновок першим
(`genres/general.md`, розд. 1), слова-порожнеча (1.4). Заборону тире, числові
пороги, «додавай голос» і автозаміни «слово → слово» не перенесено.
- technical-writer, MIT: [riekelt/technical-writer](https://github.com/riekelt/technical-writer) —
контрольні питання після переписування: зміст не втрачено, прийом не
повернувся в іншій формі (`language.md`, «Переписування зберігає зміст»).
- humanizer-zh, MIT: [op7418/humanizer-zh](https://github.com/op7418/humanizer-zh) —
те саме для китайської; підтвердження, що перевірка змісту після чистки
потрібна незалежно від мови.
- korean-humanizer з k-skill, MIT:
[nomadamas/k-skill, `korean-humanizer/instruction.md`](https://github.com/nomadamas/k-skill/blob/50d7bb3/korean-humanizer/instruction.md) —
рівні ваги ознак S1/S2/S3 і сортування «лише форматування — правити лише
форматування» (`language.md`, «Вага ознак»). Розкладку пунктів по рівнях
складено наново для української.
- StoryScope: J. Russell et al., «StoryScope: Investigating idiosyncrasies in AI
fiction», COLM 2026, [arXiv 2604.03136](https://arxiv.org/abs/2604.03136) —
підтвердження, що окрема ознака ШІ не доводить, а сигнал дає їх поєднання
(рівень S3).
- J. Liao et al., «Defensive Writing in GPT Models», препринт, 2026,
[arXiv 2610.11355](https://arxiv.org/abs/2610.11355v2) — застереження без
підстави, які модель дописує, коли перевіряє твердження (`language.md`,
«Переписування зберігає зміст»). Знайдено через
[Nanako0129/sepia](https://github.com/Nanako0129/sepia), MIT, де на цій основі
зроблено правило для переписування ділового тексту; текст правила власний.
- Compound Engineering, MIT:
[EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) —
ідея плану перед роботою (`/ce-plan`).
- Matt Van Horn, «Every Agentic Engineering Hack I Know», 2026 — той самий
підхід «спершу план», через статтю.
- doc-coauthoring з anthropics/skills, ліцензію в репозиторії не визначено, узято лише ідею:
[SKILL.md, Stage 3](https://github.com/anthropics/skills/blob/dbd4588/skills/doc-coauthoring/SKILL.md) —
тест читача свіжим субагентом (`genres/general.md`, розд. 6).
- wai-skill-suite, MIT:
[woldinius/wai-skill-suite, `wai-requirements-planning`](https://github.com/woldinius/wai-skill-suite/blob/d83acaf/.claude/skills/wai-requirements-planning/SKILL.md)
і [`grilling-protocol.md`](https://github.com/woldinius/wai-skill-suite/blob/d83acaf/.claude/skills/wai/references/grilling-protocol.md) —
перелік припущень наприкінці роботи (розд. 3, «Підсумок маркерів»), пошук
фактів у фоні й найменший варіант серед альтернатив (`forks-and-questions.md`,
розд. 2–3), три виходи знахідки й формат кількох питань із рекомендацією, де залежне
питання чекає (там само, розд. 8–9), термін із розмови — у словник проєкту
(`language.md`, 2.1), дельта плану з датою
(`genres/plan.md`, розд. 3) і поріг для ADR (`genres/adr.md`). Жорсткий стоп
перед кожним кроком до підтвердження і питання без ліміту не перенесено: вони суперечать правилу
«маркер замість питання».
- mattpocock/skills, MIT: [`domain-modeling/ADR-FORMAT.md`](https://github.com/mattpocock/skills/blob/49dd158/skills/engineering/domain-modeling/ADR-FORMAT.md) —
три умови порогу ADR і класи рішень, які варто записувати (`genres/adr.md`);
[`to-tickets`](https://github.com/mattpocock/skills/blob/49dd158/skills/engineering/to-tickets/SKILL.md) —
міграція зі співіснуванням у три кроки (`genres/howto.md`, розд. 3).
- knowledge-work-plugins, Apache-2.0:
[anthropics/knowledge-work-plugins, `engineering`](https://github.com/anthropics/knowledge-work-plugins/tree/main/engineering) —
розділ «Коли застосовувати» в runbook (`genres/howto.md`, розд. 1) і умова
перегляду рішення в «Наслідках» ADR (`genres/adr.md`).
- archify, MIT: [tt-a1i/archify, `authoring-contract.md`](https://github.com/tt-a1i/archify/blob/d0c8c7e/archify/references/authoring-contract.md) —
лінія крізь чужий вузол як помилка, підпис зв'язку не видаляють, порядок
перевірки, рамка лише для справжньої межі, застарілі ручні маршрути
(`genres/schema.md`, розд. 3). Сам інструмент не перенесено: він малює HTML
через Node.js, а правила тут — для будь-якого інструмента.
- Будова жанру ТЗ (`genres/tz.md`) зведена з кількох шаблонів специфікацій, MIT:
[github/spec-kit](https://github.com/github/spec-kit) — сталі номери вимог,
вимірювані критерії, граничні випадки;
[automazeio/ccpm](https://github.com/automazeio/ccpm) — нефункціональні вимоги
окремим блоком, припущення і обмеження;
[Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — вимога у формі
зобов'язання з умовою приймання;
[EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) —
трасування вимоги до рішення і перевірки;
[addyosmani/agent-skills, `spec-driven-development`](https://github.com/addyosmani/agent-skills/tree/main/skills/spec-driven-development) —
межі виконавця в три яруси;
[mattpocock/skills, `to-spec`](https://github.com/mattpocock/skills/blob/49dd158/skills/engineering/to-spec/SKILL.md) —
ухвалені рішення Замовника серед обмежень специфікації. Користувацькі історії як
обов'язкову форму вимог, оцінку трудомісткості й зупинку на погодження перед
кожною фазою не перенесено. Правило виконуваності — жодного маркера чи
відкритого питання в ТЗ, переданому в роботу, — власне.
- Окремі ідеї взято з README інших публічних скілів; текст власний.