Refactor agent rules to progressive guidance

[WagerMeister]

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

Сейчас логика примерно такая:

до:

AGENTS.md
├── code conventions
├── database rules
├── protobuf rules
├── OpenAPI rules
└── adapter rules

→ большая часть правил попадает в контекст даже когда к задаче не относится

После патча:

AGENTS.md
├── небольшой core
└── карта маршрутов
    ├── DB/schema/transaction
    │   → references/database.md
    ├── Protobuf/generated
    │   → references/code-generation.md
    ├── OpenAPI
    │   → references/openapi.md
    ├── architecture/client/converter
    │   → references/code-conventions.md
    └── provider flow
        → skills/provider-adapter/SKILL.md
             ├── provider-boundary.md
             ├── state-and-idempotency.md
             ├── template-adaptation.md
             └── testing.md

То есть подробные правила остаются в репозитории, но модель читает их ситуативно.

Примеры:

"почини NPE в service"
→ core

"добавь migration"
→ core + database.md

"измени callback провайдера"
→ core
→ provider-adapter/SKILL.md
→ state-and-idempotency.md
→ testing.md

"адаптер одновременно меняет OpenAPI и DB"
→ provider skill + openapi.md + database.md

Это task-driven routing: нужный контекст определяется самой задачей, а не типом репозитория.

Зачем:

1. Не тащить DB/OpenAPI/adapter-конвенции в каждую обычную задачу.
2. Уменьшить вероятность того, что нерелевантные инструкции начнут влиять на решение.
3. При этом сохранить подробные знания и иметь возможность их расширять.
4. Не навязывать одной репе искусственный профиль adapter или openapi: маршруты могут комбинироваться.
5. То, что можно проверять детерминированно, оставлять hooks/tests/CI, а не инструкциям.

Целевой лайфцикл:

1. my-service подключает code-generation-rules как .agent-rules

2. developer запускает:
   ./.agent-rules/install.sh

3. install.sh:
   ├── читает guidance/core.md
   ├── строит routing text
   ├── обновляет managed block в AGENTS.md
   ├── обновляет managed block в CLAUDE.md
   ├── merge-ит Codex hooks
   └── merge-ит Claude hooks

4. агент начинает работу в my-service

5. агент автоматически видит AGENTS.md

6. AGENTS говорит:
   "если задача X → прочитай файл Y"

7. агент при необходимости открывает:
   .agent-rules/references/Y.md

8. CI может запускать:
   ./.agent-rules/check.sh

   чтобы убедиться, что generated managed block
   соответствует версии submodule

Хуки:

Codex/Claude заканчивает turn
        ↓
Stop / SubagentStop
        ↓
.agent-rules/hooks/format-kotlin.sh
        ↓
есть изменённый Kotlin + ktlint?
        ├── нет → ничего
        └── да → format + check

[D-Baykov]

LGTM, но есть пара моментов:

1. Сейчас я вижу SKILL для адаптера. Как это будет работать для обычного сервиса?
2. Заметил особенность, что ИИ плохо валидирует то, что пишет сейчас, но прекрасно рефакторит. Можно ли как-то указать, чтобы он после написания кода делал финальный прогон по коду?
3. Может в целом первый прогон делать минимально возможным промптом, а уже вторым делать валидацию и рефактоинг?
4. Будто бы в файлах появилось больше воды (субьективно). Мб что-то можно убрать?
5. Я думал будет основной файл скилла с рекомендациями и ссылками на конкретный репозиторий в зависимости от... Сейчас будто бы связи с файлами находятся внутри текста и добавлять/обновлять будет не так просто
6. Мне кажется стоит в ReadMe указать и примеры промптов (шаблоны) если есть необходимость указать какую-то метаинформацию (например, что репа это адаптер)

[vitaxa]

LGTM, но есть пара моментов:

1. Сейчас я вижу SKILL для адаптера. Как это будет работать для обычного сервиса?
2. Заметил особенность, что ИИ плохо валидирует то, что пишет сейчас, но прекрасно рефакторит. Можно ли как-то указать, чтобы он после написания кода делал финальный прогон по коду?
3. Может в целом первый прогон делать минимально возможным промптом, а уже вторым делать валидацию и рефактоинг?
4. Будто бы в файлах появилось больше воды (субьективно). Мб что-то можно убрать?
5. Я думал будет основной файл скилла с рекомендациями и ссылками на конкретный репозиторий в зависимости от... Сейчас будто бы связи с файлами находятся внутри текста и добавлять/обновлять будет не так просто
6. Мне кажется стоит в ReadMe указать и примеры промптов (шаблоны) если есть необходимость указать какую-то метаинформацию (например, что репа это адаптер)

Финальный прогон по коду должен делать sub-agent, но это больше токенов сожрет конечно. А так то в теории сюда добавить sub-agent под claude и codex не проблема