Project Dna

Project DNA — Скилл создания и аудита корневого документа проекта

Что такое DNA

DNA (Decision Nucleic Acid) — компактный документ (2–5 страниц), содержащий только решения, которые верны независимо от реализации. Ни одного названия технологии, модели, фреймворка — только «что» и «почему».

DNA — корень проектной документации. Все остальные документы (Requirements, TechnicalDesign, DevPrompts, CLAUDE.md) выводятся из него.

Что НЕ является инвариантом

Самая частая порча DNA — смешение инварианта с гипотезой. Инвариант не меняется; гипотеза может оказаться неверной. Если их держать в одном документе, DNA либо окаменевает (гипотезы нельзя пересмотреть, потому что «это же DNA»), либо обесценивается (переписывается каждую неделю, потому что «там всё равно всё меняется»).

Проверочный вопрос: что должно произойти, чтобы это перестало быть верным? Если ответ «ничего, это свойство предметной области» — инвариант. Если «мы можем обнаружить, что ошиблись» — гипотеза, уезжает в 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.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

# [Название проекта] — 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-en.md

Методология едет вместе со скиллом: при установке в ~/.claude/skills/ или заливке в аккаунт файлы оказываются рядом с SKILL.md, а не остаются в репозитории.