ai-commons

Общие правила для AI-агентов + автосохранение Claude-диалогов. Поставляется как npm-зависимость и поддерживает четыре популярных таргета:

| Агент / стандарт | Файл в потребителе | Режим | |---|---|---| | Claude Code | CLAUDE.md | управляемый блок (@AGENTS.md import) | | OpenAI Codex / стандартный AGENTS.md | AGENTS.md | управляемый блок (встроенное содержимое) | | Cursor | .cursor/rules/ai-commons.mdc | весь файл принадлежит ai-commons |

В файлах с управляемым блоком (CLAUDE.md, AGENTS.md) содержимое между метками <!-- ai-commons:begin --> и <!-- ai-commons:end --> перезаписывается; всё остальное в файле — твоё, не трогается.

Дополнительно для Claude:

• SessionStart-хук обновляет все три target-файла на каждом старте сессии.
• Stop / SessionEnd-хук сохраняет диалог в .ai-dialogs/YYMMDD-HHII-<topic>.md. Папку коммить — в .gitignore не добавляется (и из старых установок чистится).

Установка в новый проект

cd my-new-project
npm init -y                                             # если package.json ещё нет
npm i -D /Users/os/okneigres-repos/ai-commons

postinstall всё настраивает автоматически. Запустить вручную:

npx ai-commons install      # идемпотентно: можно гонять сколько угодно раз
npx ai-commons uninstall    # снять блоки, хуки и Cursor-файл

Правила

Лежат в RULES.md — это публичный контракт, его содержимое targets.js копирует во все target-файлы потребителей. AGENTS.md в этом репо — заметки для работы над самим ai-commons, в потребителей не попадает.

Как обновить правила во всех проектах

1. Правишь RULES.md здесь.
2. git commit && git push (или просто коммит, если репо локальный).
3. В каждом потребителе:
   • Claude: ничего делать не надо — SessionStart-хук подтянет новые правила в следующей сессии (для file:-зависимостей) или после npm update ai-commons (для опубликованных).
   • Codex / Cursor: npm install (или npx ai-commons install) — перепишет блоки и Cursor-файл.

Сохранение диалогов (только Claude)

После каждого Claude Stop (и при завершении сессии) хук пишет .ai-dialogs/YYMMDD-HHII-<topic>.md:

• Timestamp — момент первой реплики пользователя в сессии.
• <topic> — ai-title из транскрипта Claude Code, fallback на первую пользовательскую реплику.
• Файл переписывается на каждом Stop в пределах одной сессии (то есть всегда содержит полный диалог).
• Thinking-блоки модели не сохраняются — только пользовательский текст, ответы ассистента, tool calls и их результаты.

.ai-dialogs/ коммитятся — installer не добавляет их в .gitignore (и убирает запись, если она осталась от установок <0.2.12).

Структура репо

ai-commons/
├── RULES.md                           — источник правды (правила), копируется в потребителей
├── AGENTS.md                          — заметки для работы над самим ai-commons
├── package.json                       — bin + postinstall
├── bin/ai-commons.js                  — CLI: install / uninstall
├── scripts/
│   ├── postinstall.js                 — npm-хук, запускает installer.install
│   ├── installer.js                   — установка/удаление в потребителе
│   ├── targets.js                     — список таргет-файлов (Claude/Codex/Cursor)
│   └── managed-block.js               — вставка/обновление блока в markdown
└── hooks/
    ├── ensure-rules-pointer.js        — SessionStart-хук (рефреш всех таргетов)
    └── save-dialog.js                 — Stop / SessionEnd-хук

Переменные окружения

• AI_COMMONS_SKIP_POSTINSTALL=1 — отключить автоустановку (CI и т.п.).

Что не делается

• permissions и env из settings.json потребителя не трогаются — только свой набор хуков (SessionStart / Stop / SessionEnd) мержится.
• Старый формат Cursor (.cursorrules в корне) не поддерживается — только современный .cursor/rules/*.mdc.
• Автосейв диалогов реализован только для Claude (у других агентов нет аналогичных hook'ов).