# Project Dna > Создание, поддержка и аудит Project DNA — корневого документа проекта с инвариантами, независимыми от реализации. Используй этот скилл ВСЕГДА при: создании нового проекта с нуля, формулировании архитектурных решений, аудите существующего кода на соответствие инвариантам, обновлении доменной модели, пересмотре приоритетов проекта. Триггеры: «создай DNA», «начни проект», «проверь соответствие», «DNA-аудит», «что у нас за инварианты», «обнови DNA», «почему так устроено», «что нельзя нарушить», «что НЕ должно появиться», «негативные инварианты», «pre-action protocol», «что удалить», «проект разросся», «признак нарушения», «это инвариант или гипотеза», «давай с начала». Также при запуске нового проекта, ревью архитектуры, рефакторинге, смене стека, регулярном аудите разрастания проекта. - Skill: `sizovoleg/project-dna` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add sizovoleg/project-dna` - Raw SKILL.md: https://api.skillmd.com/api/skills/sizovoleg/project-dna/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: SizovOleg (https://skillmd.com/u/sizovoleg) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/sizovoleg/project-dna --- # Project DNA — Скилл создания и аудита корневого документа проекта ## Что такое DNA DNA (Decision Nucleic Acid) — компактный документ (2–5 страниц), содержащий только решения, которые верны **независимо от реализации**. Ни одного названия технологии, модели, фреймворка — только «что» и «почему». DNA — корень проектной документации. Все остальные документы (Requirements, TechnicalDesign, DevPrompts, CLAUDE.md) выводятся из него. ## Что НЕ является инвариантом Самая частая порча DNA — смешение инварианта с гипотезой. Инвариант не меняется; гипотеза может оказаться неверной. Если их держать в одном документе, DNA либо окаменевает (гипотезы нельзя пересмотреть, потому что «это же DNA»), либо обесценивается (переписывается каждую неделю, потому что «там всё равно всё меняется»). | | DNA.md | ASSUMPTIONS.md | |---|---|---| | Содержит | Инварианты | Гипотезы | | Меняется | Только формальной мутацией (Режим 4) | По мере проверки — нормальная работа | | Формат | Формулировка + обоснование + признак нарушения | Утверждение → следствие → как проверить | | Статус | — | `VERIFIED` / `UNVERIFIED` / `FAILED` | Проверочный вопрос: **что должно произойти, чтобы это перестало быть верным?** Если ответ «ничего, это свойство предметной области» — инвариант. Если «мы можем обнаружить, что ошиблись» — гипотеза, уезжает в `ASSUMPTIONS.md` с триггером пересмотра. Три категории, которые выглядят как инварианты, но ими не являются: - **Технологические ограничения** («библиотека X не умеет Y») — это гипотеза, проверяемая probe - **Ожидания по объёму** («данных будет около N») — гипотеза, пока не измерено - **Лозунги без признака нарушения** («система должна быть надёжной») — см. ниже ## Критерий инварианта: признак нарушения **Инвариант, который нельзя нарушить наблюдаемо, — не инвариант, а лозунг.** Каждый инвариант в DNA обязан иметь **признак нарушения**: конкретное наблюдаемое состояние кода, данных или поведения системы, по которому видно, что инвариант нарушен. ``` Плохо: «Приоритет качества над скоростью» → нельзя указать состояние, показывающее нарушение Плохо: «Система должна быть надёжной» → то же Хорошо: «Ни один вывод не публикуется без указания источника» Признак нарушения: в выходном артефакте есть запись с непустым значением и пустым полем провенанса ``` Это тот же принцип, что в `architect-cc-workflow` §16 (каждый анти-паттерн имеет тест), поднятый на уровень DNA. Без него DNA наполняется благими намерениями, которые агент не может ни применить, ни проверить. Если признак нарушения сформулировать не удаётся — одно из трёх: 1. Это ценность, а не ограничение → в раздел аксиологии, как разрешённая дилемма 2. Это гипотеза → в `ASSUMPTIONS.md` 3. Формулировка слишком общая → сузить до проверяемой Признаки нарушения — прямой вход для Режима 5 (RNA/Harness): каждый становится проверкой в терминах конкретного стека. ## Философский каркас DNA DNA состоит из четырёх слоёв: ``` DNA = Онтология (что существует и как связано) + Деонтика (что допустимо и что запрещено) + Аксиология (что ценно и что нет) + Праксеология (как действовать) ``` **Онтология** — какие сущности существуют, как связаны, какие категории допустимы. **Деонтика** — что допустимо, что запрещено. Ограничения из практики. **Аксиология** — что ценно, что нет. Разрешённые конфликты приоритетов. **Праксеология** — как действовать. Принципы эволюции и работы. ### Позитивные и негативные инварианты Каждый слой имеет **две стороны**: - **Позитивные** — что должно быть, что разрешено, что ценно - **Негативные** — что НЕ должно появиться, что запрещено намеренно, что отвергнуто и почему Большинство DNA фиксирует только позитивную сторону. Это ошибка: без явных негативных инвариантов проект разрастается через accretion — каждое отдельное добавление выглядит разумным, а сумма разрушает целостность. Негативные инварианты — защита от дрейфа, который невозможно заметить на уровне одного изменения. Сильные продукты определяются не тем, что в них есть, а тем, что в них **намеренно отсутствует**. «Что мы не автоматизируем», «какие решения отвергнуты», «какие зависимости запрещены» — часть DNA, равная по важности позитивным решениям. ## Что известно при написании DNA, а что появляется позже Разделы 6 и 7 просят разного, и требовать их целиком при создании — ошибка. | Раздел | Известно при создании? | |---|---| | 6.1 Намеренно не делаем | **Да.** Это решение об объёме: что за границей проекта и почему. Ради этого раздел и нужен — защита от accretion | | 6.2 Отвергнутые решения | **Нет, по построению.** При создании отвергать ещё нечего. Накапливается в `Decisions.md`; перенос в DNA — отдельная мутация с обоснованием | | 6.3 Запрещённые паттерны | **Частично.** Следующие из онтологии — да. Выведенные из инцидентов — только после инцидентов | | 7. Числовые инварианты | **Только если домен задаёт жёсткие границы.** Пороги, зависящие от стека и трудозатрат оператора, — не инварианты: их место в ANCHORS.md и RNA | Пустой 6.2 при создании — правильное состояние, а не пробел. Записывать в него пересказ инварианта из §3 нельзя: дубль создаёт видимость объёма и расходится с оригиналом при первой же правке. То же с §7: структурное требование вида «либо A, либо B» — не числовой инвариант, его место в §3. Это не теория. При массовой миграции одиннадцати DNA замечания к §6 или §7 получили десять документов из одиннадцати — самые ненадёжные разделы во всей выборке, именно потому, что шаблон требовал заполнить их знанием, которого на тот момент не существовало. Разбор: `ENFORCEMENT_MAP.md`, «Что показала массовая миграция». ## Иерархия документации ``` DNA.md — инварианты, для человека ASSUMPTIONS.md — гипотезы со статусами (рядом, не внутри) ↓ RNA / Harness — enforcement, для агента ├── CLAUDE.md (контракт с агентом) ├── ANCHORS.md (числовые якоря самопроверки, если проект data-heavy) ├── Скиллы (кодифицированный опыт) └── Плагины / MCP (инструментарий) ↓ Requirements → TechnicalDesign → DevPrompts → Код ↑ DNA-аудит (обратная связь) ``` ## Режим 1: Создание DNA для нового проекта ### Когда использовать Пользователь начинает новый проект или говорит «начни с DNA». ### Процесс **0. Проверь готовность предметной разведки (обязательный первый шаг).** Прежде чем формулировать DNA, убедись, что предметная область разведана. DNA без разведки — декларативный документ, опирающийся либо на правдоподобие формулировок ИИ, либо на авторитет чужих источников, но не на обоснованные предпосылки. Задай пользователю пять контрольных вопросов: - **Онтологический.** Можешь ли описать карту сущностей предметной области с опорой на 3+ независимых прецедента (не только учебник или одну статью)? - **Прецедентный.** Знаешь ли 3–5 аналогичных проектов, включая хотя бы один неудачный, и их фактические failure modes? - **Категориальный.** Идентифицированы ли места, где ИИ-агент может перенести категории из training data, ошибочные для этой области? - **Конфликтный.** Известны ли реальные дилеммы аксиологии в этой области и как они решались в прецедентах? - **Граничный.** Можешь ли чётко отделить объект проекта от соседних объектов, с конкретными критериями отсечения? Если на любой вопрос ответ «не уверен» или «частично» — **не переходи к шагу 1**. Направь пользователя в `research-with-ai`, Режим 8 (разведывательное исследование предметной области). Если все пять — уверенные «да» со ссылкой на конкретные прецеденты, переходи к шагу 1. Попроси кратко зафиксировать опорные прецеденты в том же сеансе: это не полноценная разведка, но защита от иллюзии знания. Если есть `domain_scouting.md` (результат Режима 8) — используй как прямой вход. 1. **Собери контекст.** Спроси у пользователя (или извлеки из промта/документов и `domain_scouting.md`): - Зачем система? (миссия — 1–2 предложения) - Какие сущности в предметной области? (онтология) - Что нельзя нарушить? (деонтика) - Что важнее чего **при конкретном конфликте**? (аксиология) - Какие принципы работы? (праксеология) - **Что система НЕ должна делать? Что отвергнуто? Где человек лучше машины?** (негативные инварианты) - **Какие числовые величины домена имеют жёсткие границы?** (числовые инварианты) - Специфика домена (язык, источники, подводные камни) 2. **Кристаллизуй, не формализуй.** Роль — не записать то, что пользователь уже знает, а помочь обнаружить то, что он знает неявно. Задавай вопросы, превращающие интуицию в точные формулировки: «Вы сказали "правильно измерять" — что именно значит правильно? Какой результат вы бы отвергли?» Пользователь часто не знает своих решений, пока не услышит неправильный вариант. 3. **Для каждого инварианта потребуй признак нарушения.** Если не формулируется — разведи по трём категориям (ценность / гипотеза / слишком общая формулировка) и перенеси соответственно. 4. **Сформулируй DNA** по шаблону ниже. Каждый инвариант прослеживаем до опорного прецедента или пункта разведки. Если инвариант ни на что не опирается — он либо не инвариант, либо требует возврата к Режиму 8. 5. **Проверь:** убери мысленно все названия технологий. Если DNA потерял смысл — в нём реализация, нужно вычистить. 6. **Разместимость для агента.** Ключевые инварианты — в начале документа и продублированы в конце. Правило в середине длинного контекста статистически игнорируется агентом (attention architecture, не лень). См. `architect-cc-workflow` §5.3. 7. **Положи** `DNA.md` в корень проекта. Рядом — `ASSUMPTIONS.md` и `domain_scouting.md` (если есть). 8. **Предложи** создать RNA/Harness и первый DevPrompt на основе DNA. ### Шаблон DNA ```markdown # [Название проекта] — Project DNA **Версия:** 1.0 **Дата:** [дата] --- ## Назначение этого документа Корневой документ проекта. Содержит решения, ограничения и критерии качества, независимые от реализации. Все остальные документы выводятся из DNA. ### Правила для AI-агента 1. Прочитай DNA перед началом работы. 2. Любое решение должно быть совместимо с инвариантами. 3. При конфликте — сообщи, не нарушай молча. 4. DNA обновляется только владельцем проекта. 5. Гипотезы — в ASSUMPTIONS.md, не здесь. --- ## 1. Миссия [Зачем система существует. 1–2 предложения.] --- ## 2. Доменная модель (онтология) ### 2.1. Сущности [Какие сущности существуют и почему они разделены.] ### 2.2. Фундаментальные разделения [X ≠ Y, потому что…] ### 2.3. Типизации [Начальные типы/категории, если применимо.] --- ## 3. Ограничения (деонтика) ### 3.1. [Инвариант] **Формулировка:** [что нельзя нарушить] **Обоснование:** [почему — ссылка на прецедент или пункт разведки] **Признак нарушения:** [наблюдаемое состояние, показывающее нарушение] ### 3.2. [Инвариант] ... --- ## 4. Критерии качества (аксиология) ### 4.1. [Этап/компонент] [Что значит «работает правильно» — в проверяемых терминах.] ### 4.2. Разрешённые дилеммы Формат: «Когда нельзя одновременно A и B → выбираем A, потому что […]» - [Дилемма 1 и её разрешение] - [Дилемма 2 и её разрешение] Список ценностей без разрешённых конфликтов — не аксиология, а декорация: агент не может применить перечень хороших вещей, он может применить только правило выбора. --- ## 5. Принципы (праксеология) ### 5.1. Экономическая модель [Что бесплатно, что платно, где граница.] ### 5.2. Масштаб [На какой объём проектируется.] ### 5.3. Эволюция [Как система должна развиваться.] --- ## 6. Негативные инварианты (что НЕ должно появиться) ### 6.1. Намеренно не делаем [Что система сознательно не автоматизирует и не покрывает — и почему. Где человеческое решение лучше машинного.] ### 6.2. Отвергнутые решения [Подходы, рассмотренные и отвергнутые — с причиной, чтобы не возвращаться.] ### 6.3. Запрещённые паттерны [Архитектурные паттерны, зависимости, приёмы, запрещённые в проекте, с обоснованием.] Предложение добавить что-либо из этого списка → обязательная переоценка через формальную мутацию DNA (Режим 4), не молчаливое добавление. --- ## 7. Числовые инварианты домена [Величины с жёсткими границами, независимыми от реализации. Формат: правило + физическое/доменное обоснование.] - [величина] ∈ [диапазон], потому что [обоснование] - [соотношение между величинами], потому что [обоснование] - [единственность значения на сущность / допустимость множественных] Эти правила порождают ANCHORS.md — набор якорей самопроверки агента (см. architect-cc-workflow §14.1). DNA говорит, ПОЧЕМУ величина такая; ANCHORS.md и constants-файл — КАКАЯ она конкретно. --- ## 8. Pre-action protocol Перед изменением, затрагивающим инвариант DNA, фиксируется в DEVLOG: **Обязательно:** 1. **Что меняется?** (одной фразой) 2. **Почему?** (конкретная цель или проблема, не «улучшение вообще») 3. **Какому инварианту DNA это соответствует?** Если ни одному — STOP: либо обнови DNA (Режим 4), либо отмени изменение. **При триггерах:** 4. Persistent state или необратимая операция (БД, файловая система, деплой, релиз) → **Как откатить?** 5. Handoff или публикация (передача коллеге, публичный релиз, документация для других) → **Кто и как поддерживает?** 6. Diff > 100 строк ИЛИ затронуто > 3 модулей → **Какие компоненты?** Вопросы 1–3 защищают от ad-hoc решений и дрейфа. Вопросы 4–6 нужны не всегда — только при срабатывании триггера. --- ## 9. Специфика предметной области [Что делает задачу непохожей на generic-решение.] --- ## 10. Типовые запросы / сценарии [Для каких вопросов и задач система проектируется.] --- ## Ключевые инварианты (повтор для агента) [3–5 самых важных инвариантов из разделов 3 и 6, дословно. Дублирование намеренное: правило, стоящее только в середине документа, статистически игнорируется агентом.] --- ## Версионирование | Версия | Дата | Изменения | |--------|------|-----------| | 1.0 | [дата] | Первичная формализация | ``` ## Режим 2: DNA-аудит существующего проекта ### Когда использовать Пользователь говорит «проверь соответствие DNA» / «DNA-аудит» / после крупного этапа разработки. Регулярные триггеры (не только по запросу): - Завершение фазы разработки - Смена стека или крупная зависимость - Возврат к проекту после паузы > 1 месяца - Перед публикацией или передачей ### Процесс 1. **Прочитай `DNA.md`** и `ASSUMPTIONS.md`. 2. **Изучи** код, схемы БД, промты, тесты, конфигурацию. 3. **Проверь сам DNA на исправность** (до проверки кода): ``` 🩺 Качество инвариантов: - [инвариант без признака нарушения] — лозунг, требует переформулировки - [инвариант, являющийся гипотезой] — перенести в ASSUMPTIONS.md - [аксиология без разрешённых дилемм] — перечень вместо правила выбора ``` 4. **Для каждого раздела DNA** выдай: ``` ### [Раздел DNA] ✅ Соответствует: - [что реализовано корректно] ❌ Нарушения: - [что противоречит DNA, файл/строка, со ссылкой на признак нарушения] ⚠️ Не реализовано: - [что есть в DNA, но нет в коде] 🔍 Не задокументировано в DNA: - [что есть в коде, но нет в DNA] 🚫 Нарушение негативных инвариантов: - [что появилось в коде вопреки разделу 6] ``` 5. **Не предлагай исправления** в этом проходе. Только диагностика. 6. **Отметь**, что требует ручной проверки (качество распознавания, предметная корректность). ## Режим 3: Извлечение DNA из существующего проекта ### Когда использовать Проект существует, DNA не формализован. «Выдели DNA» / «что у нас за инварианты». ### Процесс 1. **Изучи** все проектные документы (Requirements, TechnicalDesign, CLAUDE.md, промты, код). 2. **Для каждого решения спроси:** «Это верно и для другой БД, и для файлов, и для модели с 10M контекстом?» - Да → кандидат в DNA - Нет → реализация (TechnicalDesign) 3. **Для каждого кандидата спроси:** «Что должно произойти, чтобы это перестало быть верным?» - Ничего, это свойство домена → DNA - Можем обнаружить ошибку → `ASSUMPTIONS.md` 4. **Для каждого инварианта DNA сформулируй признак нарушения.** Не удаётся — вернуть на шаг 3 или перевести в аксиологию. 5. **Найди негативные инварианты.** Их почти никогда не записывают, но они есть в решениях: что команда отвергла, почему что-то не автоматизировано. Спроси прямо: «Что вы решили НЕ делать и почему?» 6. **Сгруппируй** по слоям, сформулируй без технологий, предложи на ревью. ## Режим 4: Мутация DNA ### Когда использовать «Обнови DNA» / «это решение устарело» / «добавь в DNA». ### Процесс 1. **Покажи** текущую версию затронутого раздела. 2. **Проверь категорию:** это мутация инварианта или изменение гипотезы? Если гипотеза — правится `ASSUMPTIONS.md`, DNA не трогается. 3. **Предложи** формулировку изменения **вместе с признаком нарушения**. 4. **Обоснуй** — почему это мутация DNA, а не изменение реализации. 5. **После согласования** — обнови `DNA.md`, версию и таблицу версионирования. 6. **Предложи** запустить DNA-аудит для выявления расхождений кода с новым DNA. ## Режим 5: Создание RNA из DNA ### Когда использовать DNA готов, нужно создать RNA / Harness для конкретного стека и агента. ### Процесс 1. **Прочитай `DNA.md`.** 2. **Узнай стек:** язык, БД, агент, CI. 3. **Для каждого инварианта** переведи **признак нарушения** в: - Конкретную проверку в терминах стека - Тест или CI-правило - Правило для `CLAUDE.md` / `AGENTS.md` 4. **Для раздела 7** (числовые инварианты) сформируй `ANCHORS.md`: структурные правила → `assert`'ы в коде, reference-значения → сверка при обработке. 5. **Для раздела 6** (негативные инварианты) сформируй запреты в `CLAUDE.md` и, где возможно, lint-правила. 6. **Сформируй** `RNA.md` / `Harness.md`. Признак нарушения — это и есть спецификация проверки. Инвариант без признака нарушения непереводим в RNA; это ещё одна причина требовать его на этапе создания DNA. 7. **Подключи `harness/dna_lint.py`** как pre-commit hook или CI-шаг проекта: структурная исправность самого DNA перестаёт зависеть от дисциплины и становится падающей проверкой (ступень 5). Запуск: `python3 dna_lint.py DNA.md`. ## Режим 6: Subtraction-аудит (что удалить) ### Когда использовать Регулярно (раз в 2–3 месяца) для активных проектов, или по запросу: «что удалить», «проект разросся», «давай почистим». Особенно когда стек проектов растёт и фокус размывается. ### Зачем Проекты разрастаются через accretion: каждое добавление выглядит разумным, сумма разрушает целостность. Дефолтный режим работы — добавлять. Subtraction-аудит — сознательное противодействие: регулярный вопрос «что можно убрать?». Добавление фич может превратить инструмент в то, против чего он создавался. Удаление половины roadmap бывает лучшим продуктовым решением. ### Процесс 1. **Прочитай `DNA.md`**, особенно раздел 1 (миссия) и раздел 6 (негативные инварианты). 2. **Для каждого компонента/фичи спроси:** - Обслуживает ли это миссию напрямую, или это accretion? - Если убрать — что сломается на самом деле, не гипотетически? - Не противоречит ли существование негативным инвариантам? - Приняли бы мы это решение сегодня заново, или это legacy? 3. **Выдай три списка:** ``` ### Кандидаты на удаление - [компонент] — почему не обслуживает миссию, что освободит удаление ### Кандидаты в негативные инварианты - [отвергнутый паттерн] — зафиксировать в разделе 6, чтобы не вернулся ### Оставить, несмотря на сомнения - [компонент] — явное обоснование, почему всё-таки нужен ``` 4. **Не удаляй сам.** Предложи владельцу. Удаление — решение владельца, как и мутация DNA. 5. **После согласования** отвергнутое заносится в раздел 6 с причиной, чтобы не вернулось через полгода. ## Ключевые правила - DNA **никогда** не содержит названий технологий, моделей, фреймворков - DNA **всегда** компактный (2–5 страниц) - DNA обновляется **только** владельцем проекта; агент предлагает — не вносит - При конфликте задачи с DNA агент **сообщает**, не нарушает молча - Тест качества DNA: «убери все технологии — остался ли смысл?» - Второй тест: **каждый инвариант имеет признак нарушения**. Нет признака — лозунг, гипотеза или ценность, но не инвариант - Гипотезы живут в `ASSUMPTIONS.md`, не в DNA. Смешение — причина, по которой DNA либо окаменевает, либо обесценивается - Аксиология — **разрешённые дилеммы**, а не список ценностей. Агент применяет правило выбора, не перечень - DNA фиксирует **обе стороны**: что должно быть и что не должно появиться. Без негативной стороны нет защиты от accretion-дрейфа - Роль агента при создании DNA — **кристаллизация**, не формализация. Помогай обнаружить неявное. `[эвристика по существу — признака нарушения нет и не будет; это нормально, но это не спецификация, и удивляться её «несрабатыванию» не нужно]` - Ключевые инварианты — в начале документа и продублированы в конце - Структурная исправность DNA проверяется механически: `harness/dna_lint.py` (технологии, компактность, признаки нарушения, разделы 6–7, блок ключевых инвариантов, наличие ASSUMPTIONS.md). Содержательное качество признаков линт не проверяет — это закрывает блок 🩺 Режима 2 ## Связанные скиллы - **`research-with-ai`, Режим 8** — **предшествует** Режиму 1. Разведка предметной области перед формулированием DNA; `domain_scouting.md` — опорный материал. - **`architect-cc-workflow`** — **активируется ПОСЛЕ создания DNA**, для execution phase. DNA определяет инварианты («что» и «почему»), workflow — как взаимодействовать с агентом при реализации. Комплементарны попарно: признак нарушения (DNA) ↔ regression suite (§16); pre-action protocol (DNA) ↔ Phase-end report (§«При phase transitions»); числовые инварианты (DNA раздел 7) ↔ verification anchors (§14.1). - **`prd-coauthoring`** — создание Requirements (выводятся из DNA) - **`pipeline-development`** — реализация (TechnicalDesign + DevPrompts, совместимые с DNA) - **`peer-review`** — ревью на соответствие DNA как критерий качества ## Полная методология Философское основание, биологическая метафора, жизненный цикл, роли, антипаттерны и сравнение с ADR / Harness Engineering / Spec-Driven Development / CodeSpeak / DDD: - [`references/methodology-ru.md`](references/methodology-ru.md) - [`references/methodology-en.md`](references/methodology-en.md) Методология едет вместе со скиллом: при установке в `~/.claude/skills/` или заливке в аккаунт файлы оказываются рядом с `SKILL.md`, а не остаются в репозитории.