001ПАПКА ПРОЕКТА ДЛЯ АГЕНТА

Промпт для разворачивания описания проекта

Создай в корне моего проекта два файла-описания: AGENTS.md и CLAUDE.md.

Перед записью, изучи проект:
- какие папки внутри и за что отвечает каждая
- какой стек технологий используется
- какие команды запуска есть (посмотри package.json или pyproject.toml)
- есть ли уже README, и если да, не дублируй его

В AGENTS.md напиши коротко (40-80 строк):
- структура проекта (по папкам, одна строка на папку)
- команды (запуск, сборка, тесты, деплой если есть)
- правила оформления кода (4-5 пунктов, не больше)
- как делать коммиты (Conventional Commits если применимо)
- порядок чтения для агентов:
  1. AGENTS.md (этот файл)
  2. CLAUDE.md
  3. .claude/rules/*.md
  4. .claude/agents/*.md
  Ближайший в дереве побеждает.

В CLAUDE.md напиши (60-100 строк):
- где что лежит (бизнес-логика, роуты, схема БД)
- архитектурные правила (что нельзя ломать)
- инфра и деплой (одна короткая секция)
- грабли проекта (что часто ломали раньше, спроси меня
  или оставь заглушку «дополнить по мере появления»)

Перед записью, покажи мне план обоих файлов, я подтвержу.
Не добавляй маркетинговых слов вроде «революционный»
или «мощный». Длинные тире не использовать.

Создать AGENTS.md в корне

Файл рядом с package.json или pyproject.toml. Минимальный скелет, около 80 строк:

# AGENTS.md

## Repo structure
- `src/`, исходный код
- `tests/`, тесты
- `scripts/`, служебные скрипты

## Commands
- `npm run dev`, разработка
- `npm run build`, сборка
- `npm run test`, тесты
- `npm run lint`, проверка стиля

## Code style
- TypeScript strict mode
- Файлы кода до 250 строк
- Без `any`

## Commits
Conventional Commits: feat, fix, refactor, docs, test, chore.

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

Создать CLAUDE.md в корне

Дополняет AGENTS.md проектной операционкой. Минимальный скелет, около 100 строк:

# CLAUDE.md

## Code navigation
- Бизнес-логика, `src/services/`
- API-роуты, `src/routes/`
- Схема БД, `src/db/schema.ts`

## Architectural invariants
- Один сервис, одна ответственность
- API-контракты валидируются Zod
- Никаких прямых SQL в роутах, только через repository-слой

## Infra & deploy
- Production, ветка `main`
- Деплой, `bash deploy.sh` (blue/green)
- Откат, `bash deploy.sh rollback`

## Gotchas
- Миграции применяются вручную перед деплоем
- При правке схемы, обновить `src/db/types.ts` (не автогенерится)

Под gotchas попадает всё, что один раз сломали. Не «частые ошибки в индустрии», а конкретные грабли проекта.

Прописать read order в самом AGENTS.md

В верх AGENTS.md добавляешь блок:

## How agents should read this repo

1. AGENTS.md (this file), contributor contract
2. CLAUDE.md, operations guide
3. .claude/rules/*.md, behavioural rules
4. .claude/agents/*.md, subagents

Nearest in tree wins. Project files override global ~/.claude/.

Это страховка: даже если агент почему-то не загрузил иерархию через хук, он прочтёт её прямо из документа.

Промпт для создания первого готового навыка

В этом проекте у меня есть процедура, которую я повторяю
часто. Опишу её здесь:

  <ОПИШИ СВОЮ ПРОЦЕДУРУ В 1-2 ПРЕДЛОЖЕНИЯХ. НАПРИМЕР:
  «после правки фронтенд-компонента нужно прогнать снимки
  тестов, и если они упали, посмотреть диффы и обновить
  только те, где разница ожидаемая»>

Преврати её в готовый навык. Сделай так:

1. Создай папку .claude/skills/<короткое-имя-навыка>/
2. Внутри файл SKILL.md со следующей структурой:
   - сверху блок описания (frontmatter):
     name: <короткое-имя-навыка>
     description: краткое описание триггерных фраз,
       какие слова я скажу, по которым этот навык
       должен подключиться
     allowed-tools: список только тех инструментов,
       которые реально нужны (Read, Edit, Bash и т.п.)
   - дальше тело: пронумерованные шаги, что именно
     надо сделать, что проверить, что сделать при ошибке.

3. Покажи мне получившийся файл и попроси подтверждение.

4. После создания, открой новую беседу и проверь, что навык
   подключается, когда я говорю триггерную фразу. Если не
   подключился, переформулируй описание триггера, добавь
   ещё несколько вариантов фраз.

Важно: каждый шаг в навыке должен быть конкретным действием,
а не «запусти всё подряд». Не добавляй права на инструменты,
которые не нужны процедуре.

Создать первый скилл

В проекте есть процедура, которую ты повторяешь регулярно. Например: «обновить snapshot тестов после правки UI-компонента».

Создай каталог:

mkdir -p .claude/skills/update-snapshots

Файл .claude/skills/update-snapshots/SKILL.md:

---
name: update-snapshots
description: Обнови snapshot-тесты после правки UI. Триггеры,
  «прогнал snapshot-тесты, упали», «нужно обновить snapshots»,
  «снапшоты разъехались».
allowed-tools:
  - Bash
  - Read
---

# Update snapshots

1. Покажи список упавших snapshot-тестов:
   `npm run test -- --testPathPattern=snapshot`

2. Сравни диффы. Для каждого:
   - Если разница ожидаемая (новый дизайн), пометь для обновления
   - Если неожиданная (баг), останови процедуру и доложи

3. Обнови подтверждённые:
   `npm run test -- -u --testPathPattern=snapshot`

4. Перезапусти все тесты, убедись что зелёно.

Проверить, что скилл найден

Запусти агент в проекте. В новой сессии напиши: «снапшоты разъехались, обнови».

Агент в ответе должен явно упомянуть, что использует skill update-snapshots. Если упоминания нет, проблема в описании: триггер не семантически зацепился за фразу пользователя. Переформулируй description, добавив варианты формулировок.

Глобальные vs проектные скиллы

Скилл может лежать в ~/.claude/skills/ (доступен во всех проектах) или в <project>/.claude/skills/ (только в этом проекте).

Глобальные подходят для универсальных процедур: «housekeep», «code-navigation», «commit-commands». Проектные, для специфики стека: «как обновить миграцию в этом проекте», «как выкатить blue/green в этом проекте».

При совпадении имени проектный перебивает глобальный.

Создать первый subagent

Файл .claude/agents/code-validator.md:

---
name: code-validator
description: Read-only critic. Запускается после имплементации
  фичи. Проверяет синтаксис, типы, импорты, структурные
  ошибки. НЕ проверяет бизнес-логику, это уже работа человека.
tools: Read, Grep, Glob
model: claude-haiku-4-5
---

# Code validator

Ты read-only критик. У тебя нет прав на запись.

1. Прочитай diff последнего коммита.
2. Проверь по списку:
   - все импорты резолвятся
   - типы согласованы по сигнатурам
   - нет orphan-ссылок на удалённые символы
   - нет очевидных синтаксических ошибок
3. Верни короткий отчёт: max 10 пунктов, по каждому,
   file:line + 1 строка причины. Без воды.

Допуск только Read/Grep/Glob: критик не должен ничего менять. Модель Haiku, дешевле и быстрее на простых проверках синтаксиса.

Вызвать subagent из основной сессии

В диалоге пишешь:

Закончил имплементацию фичи. Запусти code-validator subagent
на последнем коммите, верни его отчёт.

Основной агент спавнит subagent, ждёт результат, возвращает в твой диалог только итоговый отчёт. Длинные чтения файлов и Grep-выводы остаются в контексте subagent-а и не попадают в твою историю.

Промпт для развёртывания базовой защиты

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

Сделай так:

1. Создай маленький сторожевой скрипт в моей домашней
   папке агента (~/.claude/hooks/guard-bash.sh).
   Скрипт должен останавливать с понятным сообщением
   следующие классы команд:

   а) Удаление папок верхнего уровня в системе:
      /opt, /etc, /var, /usr, /home, корня /, домашней ~.
   б) Принудительный откат локальных правок,
      который потеряет несохранённый код.
   в) Удаление веток без подтверждения слияния.
   г) Полное стирание таблиц или баз данных
      (DROP DATABASE, DROP TABLE, TRUNCATE).
   д) Остановка nginx, postgres, redis, docker.
   е) Запись в файлы вида .env через перенаправление вывода.

   Когда команда блокируется, в сообщении должно быть видно,
   почему именно. Чтобы агент понял причину и пошёл другим путём.

2. Подключи скрипт как защитный хук на запуск Bash в файле
   ~/.claude/settings.json. Если файл уже есть, аккуратно
   допиши, не затирай существующее.

3. Поставь второй защитный хук на правку секретных файлов
   (.env и подобные). Этот хук срабатывает, когда агент
   пытается отредактировать или перезаписать такой файл.
   Сообщение об ошибке должно объяснять, какой именно файл
   защищён и почему.

4. После установки, попроси меня выполнить две команды
   для проверки. Безопасную (например, ls /opt) и опасную
   (rm -rf /opt/test-XXXX). Безопасная должна пройти,
   опасная, заблокироваться с понятным сообщением.

Не добавляй классы блокировки, которые я не упомянул.
Хочу понимать, что именно стоит на защите.

Создать guard-bash.sh

Файл ~/.claude/hooks/guard-bash.sh:

#!/usr/bin/env bash
# Pre-bash guard: блокирует деструктив до выполнения.

CMD="${CLAUDE_TOOL_INPUT_COMMAND:-}"

block() {
  local reason="$1"
  echo "BLOCKED: $reason" >&2
  echo "Command: $CMD" >&2
  exit 2
}

# rm -rf на системные пути
if echo "$CMD" | grep -qE 'rm[[:space:]]+-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*[[:space:]]+(/|/opt|/etc|/var|/usr|/home|~)([[:space:]]|$)'; then
  block "rm -rf on system path is forbidden"
fi

# git push --force
if echo "$CMD" | grep -qE 'git[[:space:]]+push[[:space:]]+.*(--force|-f([[:space:]]|$))'; then
  block "git push --force is forbidden, create a new commit instead"
fi

# git reset --hard
if echo "$CMD" | grep -qE 'git[[:space:]]+reset[[:space:]]+.*--hard'; then
  block "git reset --hard loses uncommitted work"
fi

# DROP/TRUNCATE
if echo "$CMD" | grep -qiE '\b(DROP[[:space:]]+(DATABASE|TABLE|SCHEMA)|TRUNCATE)\b'; then
  block "destructive SQL is forbidden, use migration"
fi

# systemctl stop critical
if echo "$CMD" | grep -qE 'systemctl[[:space:]]+(stop|disable)[[:space:]]+(nginx|postgresql|postgres)'; then
  block "stopping critical service is forbidden"
fi

# .env через redirect
if echo "$CMD" | grep -qE '(>|>>|tee)[[:space:]]+\.env'; then
  block "writing .env via shell redirect bypasses protections"
fi

exit 0

Сделать исполняемым:

chmod +x ~/.claude/hooks/guard-bash.sh

Зарегистрировать хук в settings.json

Файл ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/guard-bash.sh"
          }
        ]
      }
    ]
  }
}

matcher: "Bash" означает, что хук срабатывает только перед вызовами инструмента Bash. На Edit и Write он не срабатывает — для них есть отдельная защита, которую регистрируешь следующим шагом.

Добавить блокировку чувствительных файлов

Защита бэша не покрывает прямые правки .env через Edit/Write. Добавь второй PreToolUse-хук, инлайн в settings.json:

{
  "matcher": "Edit|Write|MultiEdit",
  "hooks": [
    {
      "type": "command",
      "command": "FILE=\"${CLAUDE_TOOL_INPUT_FILE_PATH:-}\"; case \"$FILE\" in *.env|*.env.*|*credentials*|*secrets*) echo \"BLOCKED: $FILE protected\" >&2; exit 2;; esac"
    }
  ]
}

Этот хук читает путь файла из переменной, и если он попадает под опасный паттерн, блокирует операцию. Без него агент может перезаписать .env через Write и снести продакшн-конфиг.

Промпт для базового набора правил поведения

Дополни мой глобальный файл ~/.claude/CLAUDE.md
универсальными правилами поведения агента. Правила оформи
как блоки прогрессивного раскрытия — это значит, в файле
сверху текст вида:

  <important if="условие, при котором правило подключается">
  ...текст правила...
  </important>

Агент сам решает, подходит ли условие к текущей задаче,
и подгружает только нужные блоки. Так файл может быть
большим, но в каждой беседе агент тратит контекст
только на актуальное.

Минимальный набор блоков (если каких-то ещё нет — добавь;
существующие не дублируй):

1. if="writing or modifying code":
   - один источник правды (одно значение живёт в одном месте)
   - размер файла кода до 250 строк, иначе разбивать
   - любая временная заплатка попадает в «Известные проблемы»
     проектного CLAUDE.md

2. if="user asks to estimate or compute a number":
   - не выдавать числа от себя; либо формула с источником,
     либо «не могу проверить, нужно посмотреть X»

3. if="user pushes back, disagrees, or sends conflicting evidence":
   - не защищаться, а перепроверять: открывать файл/лог заново
   - был неправ — говорить прямо; прав — приводить новое
     доказательство, не повторение старого

4. if="closing a task or finishing a sub-step":
   - не предлагать «продолжим завтра», «на сегодня хватит»
   - либо доделать сейчас, либо честно объяснить
     почему сейчас нельзя

ОТДЕЛЬНО: загляни в .claude/rules/ этого проекта. Если папки
нет — не создавай (она нужна только если есть проектная
специфика). Если папка есть — пройдись по существующим
правилам и скажи, не дублируются ли они с тем, что я добавляю
в ~/.claude/CLAUDE.md (если да — их можно убрать из проекта).

После работы покажи: какие блоки добавил в ~/.claude/CLAUDE.md,
что было в .claude/rules/, что предлагаешь оставить в проекте.

Универсальные блоки — в ~/.claude/CLAUDE.md, не в проект

Правила вроде basic-conduct и pushback — про поведение агента вообще, не про конкретный проект. Им место в ~/.claude/CLAUDE.md (глобальный поведенческий файл). Дописываешь туда блоки прогрессивного раскрытия:

# ~/.claude/CLAUDE.md (фрагмент)

<important if="writing or modifying code">
- Single source of truth (значения из больше одного места живут в одном)
- Файл кода до 250 строк
- Любой TODO/stub попадает в Known Issues файла CLAUDE.md
</important>

<important if="user pushes back or sends conflicting evidence">
Re-verify, не защищаться.

1. Перечитай релевантный файл с нуля
2. Сообщи, что нашёл, даже если противоречит предыдущему ответу
3. Был неправ, скажи прямо
4. Прав, покажи новые доказательства, не повторение старых
</important>

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

Папку <project>/.claude/rules/ заводи только если есть проектная специфика, которую стоит вынести в правила. Если такой специфики ещё нет — папка не нужна, появится позже.

# создать только когда есть что туда положить
mkdir -p .claude/rules

Пример проектного правила (не универсального):

# .claude/rules/db-migrations.md

<important if="writing SQL migration or editing schema.sql">
- Миграции нумеруются NNN_*.sql, ADD COLUMN IF NOT EXISTS
- Применять через scripts/migrate.ts (SET LOCAL ROLE)
- НЕ sudo -u postgres psql -f file.sql — owner станет postgres,
  deploy упадёт
</important>

Добавить /plan и /work для нетривиальных фич

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

/plan <описание> — slash-команда, которая создаёт структурированный план в файле .claude/memory/plans/<slug>.md. Папка memory/ внутри .claude/ — место, где агент держит артефакты, переживающие одну сессию. План кладётся именно туда, потому что работа может растянуться на несколько заходов: при следующем запуске агент перечитает план с того места, где остановился, и не потеряет контекст. План имеет фазы. У каждой фазы:

• Task list — что конкретно сделать, с путями к файлам
• Auto-checks — команды, которые должны зелёно отработать (типы, тесты, линтер)
• Critic-check — ревью только-на-чтение от подагента code-validator
• Manual verification — что должен проверить человек глазами

/work [plan-path] [--auto] — slash-команда, исполняющая следующую незакрытую фазу:

• Делает по списку всё, что отмечено как «надо сделать»
• Прогоняет Auto-checks с лимитом в 3 попытки исправления на ошибку
• Запускает code-validator как read-only critic (критик с правами только на чтение, не может ничего испортить)
• Делает коммит на ветке claude/<feature-slug>
• Останавливается с блоком «Фаза N готова, нужна ручная проверка»

Это превращает работу с агентом из «вайбкодинга с надеждой» в воспроизводимый процесс: одна задача — один план — набор фаз с проверками — в конце уборка доков.

Промпт для разворачивания обеих команд. Slash-команды Claude Code лежат в ~/.claude/commands/<name>.md. Скопируй промпт ниже, агент создаст оба файла:

Создай две глобальные slash-команды в ~/.claude/commands/:
plan.md и work.md. Они должны работать в любом git-проекте.

ОБЩЕЕ для обоих файлов:
- frontmatter с полями description и allowed-tools
  (Bash, Read, Write, Edit, Grep, Glob, Agent)
- блок ## Context с командными подсказками !`git branch --show-current`,
  !`pwd`, !`ls .claude/memory/plans/`, !`test -f AGENTS.md` — это
  динамический контекст, который Claude Code подставляет при вызове
- блок ## Your task с пошаговой логикой

PLAN ($ARGUMENTS = описание фичи):

Step 1 — Branch guard:
  1a. Если не git-репо — refuse, стоп.
  1b. Если git status грязный И ветка main/master/dev/develop —
      STOP, печатает первые 10 грязных файлов, спрашивает: stash /
      commit / discard / ignore. Ждёт ответ. На stash или ignore —
      продолжает. На commit/discard — просит сделать руками
      и заново вызвать /plan.
  1c. Если ветка уже claude/plan-* и грязная — продолжать без
      вопросов (это своя работа).
  1d. Slug из $ARGUMENTS (kebab-case, до 40 символов).
      Создаёт ветку claude/plan-<slug> от main.

Step 2 — Read context:
  - AGENTS.md, CLAUDE.md, .claude/rules/ если есть.
  - Stack-detect по package.json/pyproject.toml/Cargo.toml/go.mod —
    это нужно для шага 4 (auto-checks подбираются под стек).

Step 3 — Plan template:
  Файл .claude/memory/plans/<slug>.md, формат:
    # <Slug>
    Status: planning | in-progress | done
    Branch: claude/plan-<slug>
    ## Goal (одно предложение)
    ## Out of scope (явные non-goals)
    ## Constraints (live)
    (сюда /work пишет директивы пользователя по ходу)
    ## Phase 1 — <name>
    ### Task
    - [ ] <что сделать, file:line если применимо>
    ### Auto-checks
    - [ ] <команда из stack-detect>
    ### Critic-check
    - [ ] code-validator subagent
    ### Manual verification
    - [ ] <что должен проверить человек>
    ## Phase 2 — ...

Step 4 — Doc update rules (для каждой фазы добавить чекбокс
  на обновление доков по триггеру):
  - API route → docs/api.md
  - DB schema/миграция → docs/schema.md + KNOWN_ISSUES.md
    для breaking changes
  - Shared util в lib/ → MAP.md
  - User-facing → CHANGELOG.md
  - Env var → .env.example
  - Skill/agent/hook → .claude/agents/ description
  - Если триггера нет — явно "- [ ] No doc updates required"

WORK ($ARGUMENTS = опциональный путь плана и/или флаги
  --auto, --phases=N,M):

Step 0 — Branch guard:
  Если current branch не claude/* — refuse, стоп. /work
  коммитит per phase, на main/dev никогда.

Step 1 — Locate plan:
  - Путь дан → читай его.
  - Не дан → list .claude/memory/plans/*.md. Если ровно один
    open — используй. Несколько — спроси какой. Ноль — попроси
    сначала /plan.
  - Sanity check: поле Branch в плане == current branch.

Step 2 — Pre-flight: читай ТОЛЬКО файлы из Task block
  следующей фазы, не пре-loaдь весь репо.

Step 3 — Implement: исполни Task checkboxes. Если план
  оказался неверным (по ходу выяснилось) — STOP, propose
  amendment, не молча отклоняйся от плана.

Step 4 — Auto-checks: запусти каждую команду. До 3 fix-attempts
  на одну ошибку. Если 3 не хватило — STOP, surface к пользователю.

Step 5 — Critic-pass: spawn code-validator subagent (read-only,
  build-grade not correctness-grade — синтаксис/типы/импорты,
  не бизнес-логика). До 3 итераций fix-loop.

Step 6 — Update plan: отметь чекбоксы фазы как done.

Step 7 — Git checkpoint: git commit -m "chore(plan): phase N — <name>".
  Refuse если не на claude/*. Никогда --no-verify. Не пуши на remote.

Step 8 — Pause for manual verification: выведи "Phase N complete —
  Ready for manual verification" со списком automated и manual
  чеков. Жди явного "ok" / "go" от пользователя.

Auto-mode (--auto): пропусти паузу до последней фазы.
  Auto-stop при: auto-check fail (3х), critic fail (3х),
  context >70%, новая директива от пользователя, 5 фаз
  подряд без surface.

Constraint emergency rule (всегда активно во время /work):
  если пользователь шлёт директиву по ходу ("don't touch X",
  "always Y") — ОБЯЗАН перед следующим code action:
  1. Открыть план
  2. Append в Constraints (live): - [<YYYY-MM-DD HH:MM>] <directive>
  3. Подтвердить вслух: "Constraint logged: ..."
  4. Только потом продолжать.

Plan-complete doc-sync: когда все фазы done, перед
  status: done — запусти housekeep skill (если есть),
  surface findings, спроси «фиксим сейчас или закрываем
  как есть?». После выбора → status: done.

После создания обоих файлов покажи мне tree
~/.claude/commands/ и попроси подтверждение.

Не использовать длинные тире в файлах (это моё стилевое
предпочтение — заменяй запятыми и двоеточиями).

После запуска промпта у тебя в ~/.claude/commands/plan.md и ~/.claude/commands/work.md появятся два глобальных файла. Проверка: в любом проекте набери /plan починить пагинацию в /api/users — Claude Code должен предложить план в .claude/memory/plans/fix-users-pagination.md и переключиться на ветку claude/plan-fix-users-pagination.

Правило о новых ограничениях по ходу работы

В английском это называется «constraint emergency rule» — буквально «правило об экстренной фиксации ограничения». Зачем оно нужно: если во время /work ты бросаешь агенту директиву в чат («не трогай X», «всегда делай Y»), велика вероятность, что через 20 реплик она утонет в шуме и агент про неё забудет. Правило обязывает агента перед следующим действием в коде:

1. Открыть файл плана
2. Дописать в секцию Constraints (live): - [<YYYY-MM-DD HH:MM>] <директива>
3. Вслух подтвердить: «Constraint logged: ...»
4. Только потом продолжать работу

Так директива переезжает из шумного чата в файл, который /work перечитывает каждую фазу. Закрывает большую часть «ты просил, я забыл».

Промпт для регулярного пересмотра шкафа

Открой агента в проекте. Раз в месяц или после крупного рефакторинга скопируй:

Проверь содержимое моего шкафа инструкций (.claude/ и
корневые файлы AGENTS.md, CLAUDE.md). Найди расхождения
с реальностью проекта:

1. Команды в описании. Все ли ещё работают?
   Запусти каждую с флагом --help, посмотри, что отвечает.

2. Папки и файлы. Все ли пути ещё существуют?
   Проверь по фактической структуре проекта.

3. Готовые навыки. Каждый описывает реальную процедуру?
   Если процедура изменилась, обнови шаги.

4. Защита. Какие правила блокировок ещё актуальны?
   Может, что-то стало нормальным и должно перестать
   блокироваться.

5. Размер файлов. Что-то стало слишком длинным
   (больше 250 строк)? Предложи разбить.

В конце сделай короткий отчёт: что обновил,
что предлагаешь обновить с моим подтверждением.
Без подтверждения, ничего не удаляй.

Регулярный пересмотр (audit) инструкций

Audit здесь — буквально «ревизия»: пройтись по содержимому шкафа и сверить с реальностью проекта. Раз в месяц или после крупного рефакторинга, онбординга нового сотрудника или мажорной смены стека — прогоняй промпт:

Сделай ревизию (audit) моей инфры для агентов в этом проекте.

Проверь по списку:

1. AGENTS.md / CLAUDE.md
   - Все ли упомянутые команды (npm/cargo/python/bash) ещё работают?
     Прогони каждую с --help или dry-run, проверь exit code.
   - Все ли пути в code navigation существуют? (ls -la каждый)
   - Размер файла? Если больше 250 строк, предложи план декомпозиции.

2. .claude/agents/*.md
   - Каждый subagent описывает текущую реальность?
   - Поле tools (список инструментов) совпадает с тем, что агент реально делает?
   - Описание триггера в description ещё семантически релевантно?

3. .claude/skills/*/SKILL.md
   - Шаги в теле скилла отражают текущий процесс?
   - Триггеры в description совпадают с тем, как я реально
     формулирую запрос?

4. .claude/rules/*.md
   - Условия <important if="..."> ещё актуальны?
   - Не противоречат ли два правила друг другу?

5. settings.json hooks
   - Каждый pre/post-tool hook ещё нужен?
   - Pre-bash паттерны не блокируют ставшие нормальными команды?

В конце дай отчёт по каждой категории: PASS / WARN / FAIL.
По FAIL предложи конкретные правки. Не применяй автоматически,
дождись моего подтверждения по списку.

Автоматизировать напоминание о пересмотре

Чтобы не полагаться на «вспомню сам», добавь хук на SessionStart, который проверяет дату последнего аудита. Простейший вариант:

#!/usr/bin/env bash
# ~/.claude/hooks/audit-reminder.sh
LAST_AUDIT_FILE=".claude/.last-audit"
if [ -f "$LAST_AUDIT_FILE" ]; then
  LAST=$(stat -c %Y "$LAST_AUDIT_FILE" 2>/dev/null || echo 0)
  NOW=$(date +%s)
  AGE_DAYS=$(( (NOW - LAST) / 86400 ))
  if [ "$AGE_DAYS" -gt 35 ]; then
    echo "[reminder] .claude/ audit last run $AGE_DAYS days ago. Consider rerun." >&2
  fi
else
  echo "[reminder] .claude/ audit never run in this project." >&2
fi

После аудита, touch .claude/.last-audit. Хук в settings.json:

{
  "hooks": {
    "SessionStart": [{
      "type": "command",
      "command": "~/.claude/hooks/audit-reminder.sh"
    }]
  }
}

Сообщение появляется в stderr при старте сессии: ненавязчиво, но не пропустишь.