Личные глобальные правила AGENTS.md

Это набор глобальных правил для Claude code и codex, который я накопил для себя. Его можно положить в AGENTS.md или CLAUDE.md в корне проекта; для новичков это очень удобное правило.

Идея дизайна: Progressive Spec

Ядро этих правил — прогрессивная спецификация (Progressive Specification): требования разной сложности проходят процессы разной глубины, чтобы не переусложнять простые задачи и одновременно давать достаточно ограничений сложным задачам.

Проще говоря: случайную сложность нужно максимально сжимать, а сущностной сложностью действительно стоит управлять.

Обзор процесса кодинга

Ключевые железные правила:

• No Spec, No Code — для средней и выше сложности без Spec нельзя трогать код
• HARD-GATE — после написания Spec нужно дождаться явного подтверждения пользователя, только потом кодить
• Reverse Sync — если в ходе выполнения обнаружено расхождение, сначала исправить Spec, затем код

Свобода каждого этапа четко определена: на исследовании можно свободно изучать, в проектировании можно раскрыться, но на этапе выполнения свобода равна нулю: строго по плану, при расхождении сразу остановиться и спросить.

О поведении разных AI

На Codex эти правила работают очень хорошо: он в целом строго соблюдает процесс и стабилен, когда ограничения ясны.

У Claude есть некоторые собственные "идеи": иногда он делает дополнительные вещи без явной инструкции или по-своему интерпретирует правила, его гибкость выше ожидаемой. В целом он менее "послушен", чем Codex, но в творческих задачах и проектировании решений раскрывается лучше.

У обоих есть свои плюсы и минусы; лучший эффект дает сочетание по типу задачи.

Полный текст правил (можно скопировать в один клик)

# Язык

- Язык общения со мной по умолчанию — китайский

# Внимание

По умолчанию не создавайте новые пояснительные документы или файлы документации.
Не генерируйте автоматически README.md, дизайн-документы, инструкции по использованию, архитектурные описания и т. п.
Создавать или изменять документацию разрешено только когда я явно прошу "написать документацию / сгенерировать README / написать пояснительный документ".

# Стиль кода

- Код должен содержать понятные китайские комментарии; у всех функций и ключевой логики должны быть комментарии

---

# Workflow Orchestration

## 1. Прогрессивный Spec: сложность по необходимости

Требования разной сложности проходят процессы разной глубины — случайную сложность нужно максимально сжимать:

| Масштаб требования | Процесс |
|---------|------|
| Простое (изменить поле, исправить bug) | Выполнять напрямую, Spec не нужен |
| Среднее (3+ шага, есть архитектурные решения) | Написать легкий Spec, кодить после HARD-GATE |
| Сложное (несколько модулей, несколько систем) | Полный Propose → Apply → Review |

**Три железных правила Spec** (только для средней и выше сложности):
1. **No Spec, No Code** — без Spec нельзя писать код
2. **Spec is Truth** — если Spec и код конфликтуют, ошибается код
3. **Reverse Sync** — если в ходе выполнения обнаружено расхождение, сначала исправить Spec, затем код

**HARD-GATE**: после полного создания Spec обязательно ждать явного подтверждения пользователя, только потом начинать кодить. До подтверждения запрещены любые изменения кода.

**Research должен иметь источник**: при описании текущего состояния кода каждый вывод должен быть отмечен путем к файлу + именем функции; не принимаются рассуждения "обычно так" или предположения без основы.

**Поэтапное подтверждение Spec**: не генерировать весь Spec одним блоком. Выводить по этапам (анализ текущего состояния → функциональные пункты → риски и решения), после каждого этапа ждать подтверждение пользователя. Чем раньше найти расхождение, тем дешевле исправить.

## 2. Plan Node Default

- Для любой задачи средней и выше сложности входить в plan mode
- При проблеме сразу остановиться и перепланировать, не продавливать дальше
- Plan mode относится и к проверке, а не только к этапу сборки

## 3. Subagent Strategy

- Активно использовать subagent, чтобы держать основной context чистым
- Research, изучение и параллельный анализ отдавать subagent
- Для сложных проблем привлекать больше вычислений через subagent
- Каждый subagent делает только одну задачу и работает сфокусированно

## 4. Кривая свободы выполнения

| Этап | Свобода | Принцип |
|------|--------|------|
| Исследование | Средняя | Свободное изучение, но выводы должны иметь источник в коде |
| Проектирование решения | Высокая | Полноценно придумывать, давать варианты + рекомендацию |
| Планирование | Низкая | Точно до путей файлов и сигнатур функций |
| Выполнение | Нулевая | Строго по плану; при расхождении сразу остановиться и спросить |
| Приемка | Средняя | Свободно проверять, но выводы должны иметь основание |

## 5. Self-Improvement Loop

- После каждого исправления от пользователя: записывать паттерн в `tasks/lessons.md`
- Писать правило, чтобы такая ошибка не повторилась
- В начале каждой сессии review соответствующие правила из lessons
- Ценные ошибки и доменные находки активно предлагать сохранить в базу знаний проекта

## 6. Железное правило Verification

- Нельзя помечать задачу завершенной без проверки
- Нужно показывать проверяемые доказательства (вывод компиляции / результат тестов / лог запуска)
- Запрещены фразы вроде "должно быть нормально" без доказательств
- При необходимости сравнивать поведение до и после изменения

## 7. Demand Elegance (умеренно)

- Для не простых изменений остановиться и спросить: "есть ли более элегантный способ?"
- Если решение выглядит hacky: "зная это, реализовать элегантное решение"
- Простые очевидные исправления делать напрямую, без переинжиниринга

## 8. Autonomous Bug Fixing

- Если дан bug report, идти исправлять, не ждать пошаговых указаний
- Указывать на лог, ошибку или failing test, затем решать
- Не требовать от пользователя переключать контекст
- Если CI test падает, активно исправлять

---

# Task Management

1. **Сначала написать план**: записать план в `tasks/todo.md` с checkable task items
2. **Выполнять после подтверждения**: для задач средней и выше сложности начинать реализацию только после HARD-GATE
3. **Отслеживать прогресс**: сразу отмечать пункт после завершения
4. **Объяснять изменения**: на каждом шаге давать высокоуровневое объяснение
5. **Записывать результат**: добавить review-раздел в конец `tasks/todo.md`
6. **Фиксировать уроки**: после исправления пользователя обновлять `tasks/lessons.md`

---

# Core Principles

- **Simplicity First**: каждое изменение делать максимально простым. Минимизировать область влияния.
- **No Laziness**: искать корень причины, не ставить заплатки, работать по стандарту senior developer.
- **Minimal Impact**: менять только необходимый код, не вносить новые проблемы.
- **Разделение намерений**: за один раз обрабатывать только один тип намерения — исследование, решение, выполнение и review не смешивать.