Проверенный на практике набор правил для настройки AI coding агентов: Claude, Gemini, Cursor, Windsurf или Copilot. Эти правила устанавливают консистентное качество кода, практики безопасности и стандарты разработки.
Заточен под Claude Code, переносим куда угодно. Секции 1–8 не привязаны к стеку или конкретному агенту. Две вещи завязаны именно на Claude Code: преамбула отдаёт жёсткие блоки в settings.json permissions + PreToolUse hooks, а §7 проводит решения через скилл /adr-writer (по adr-spec.md). На Gemini, Cursor или Copilot читай это как intent и подключи эквивалент своей платформы — или просто убери.
Применение
Добавьте в корень проекта как:
CLAUDE.md (Anthropic Claude, Claude Code, Cursor)
GEMINI.md (Google AI Studio, Gemini)
AGENTS.md (Generic, Codex, Windsurf)
.cursorrules (Cursor IDE)
AI будет читать эти правила и применять их ко всему генерируемому коду.
Что включено
Code: Семантические имена, иммутабельность, комментарии why-not-what, stdlib-first зависимости
Type Safety: Без обхода типов, валидация границ, честные внешние типы
Shell & Filesystem: Ограниченные пути, проверка целей перед удалением, поиск через rg/fd
Testing: Правильный уровень покрытия, critical paths, детерминизм
Workflow: TDD по умолчанию, file-based бэклог, иммутабельные ADR
Tools & MCP: Жёсткие схемы, структурированные ошибки, least privilege
Промпт
# Core Development Standards
*Assumes a capable agent. Routine craft (clarity, decomposition, root-cause analysis) is expected by default, not restated. Hard blocks on destructive/irreversible actions live in settings.json permissions + PreToolUse hooks — never trusted to this file.*
## 1. Code
-**Naming:** Booleans read as predicates, functions as verbs; follow the language's idiomatic casing.
-**Immutability:** Prefer immutable bindings and pure functions; isolate side effects.
-**Comments:** Explain *why*, never narrate *what*.
-**Dependencies:** Standard library first; justify every new dependency.
## 2. Type Safety
-**No escapes:** Where strict typing is available, never suppress type-checker errors or use unsafe casts/assertions — fix the cause or type it correctly.
-**Boundaries:** Validate at every external boundary (API, DAL, I/O) for runtime safety.
-**External types:** Extend or declare missing third-party types; never weaken your own types to paper over a library gap.
## 3. Shell & Filesystem
-**Search:**`rg` for content, `fd` for files (both respect .gitignore). With bare `find`, always exclude `node_modules`/`.git`.
-**Scope:** Stay inside the workspace — no absolute paths, no `../` escapes.
-**Destructive ops:** List and verify targets before any delete/overwrite.
-**Staged only:** Commit exactly what is staged; never `add -A` unreviewed changes.
## 5. Change Discipline
-**Root cause:** Diagnose *why* before fixing; no band-aids over symptoms.
-**Blast radius:** On rename/migrate, sweep the whole codebase for affected call sites.
-**Reversibility:** Surface assumptions and tradeoffs; confirm before wide-reaching or irreversible changes.
## 6. Testing
-**Right level:** Match Unit/Integration/E2E to the stack and project phase.
-**Critical paths:** Core business logic is always covered.
-**Determinism:** No flaky tests.
## 7. Workflow
-**TDD by default:** Write the failing test that specifies the behavior first, then implement to green, then refactor. The test defines "done"; spikes are the only exception and are thrown away.
-**Deferring work:** When asked to park or postpone, capture it as a file-based issue — never an inline `TODO` or half-finished code. Issues are the backlog's source of truth.
-**Decisions → ADR:** Architectural decisions go through the `/adr-writer` skill against `adr-spec.md`, strictly — never ad hoc. ADRs are immutable: a changed decision is a new ADR marked `Superseded`, never an edit to an accepted one. The skill gates significance — not every choice warrants an ADR.
## 8. Tools & MCP — *only when authoring tools/servers*
- Least privilege; write-ops idempotent or explicitly confirmable.
Почему это важно
Без явных правил AI агенты:
❌ Свободно используют any типы
❌ Запускают опасные shell команды
❌ Создают неаккуратные commit messages
❌ Лепят band-aid исправления, не разобравшись в причине
❌ Оставляют решения и отложенную работу недокументированными
С этими правилами:
✅ Консистентный, типобезопасный код
✅ Ограниченные, проверенные операции в shell
✅ Чистая git история по конвенции
✅ Root cause отладка и test-first воркфлоу
✅ Прослеживаемые решения (ADR) и file-based бэклог
Советы по кастомизации
Добавьте project-specific правила в конце
Включите tech stack предпочтения (React, Astro и др.)
Определите forbidden patterns для вашего codebase
Укажите testing frameworks которые используете
На Claude Code включите enforcement — подкрепите жёсткие блоки на деструктив/необратимое через settings.json permissions и PreToolUse hooks. Промпт декларирует intent; hooks делают его обязательным.
Язык ответов
Личный addendum под русскоязычные ответы — не часть универсального ruleset выше. Когда агент отвечает по-русски, добавляю это в CLAUDE.md отдельным блоком:
## Язык ответов
На русском — живой язык; цель естественность, а не русификация любой ценой.
Режущий слух транслит не перевожу натужно на русский, а возвращаю к оригиналу латиницей: «бумпнуть» → bump, «гвард» → guard, «ретраи» → retry.
Устоявшийся профессиональный жаргон оставляю как есть — он разговорный и понятный: пушить, мержить, дебажить, коммит, деплой, токен, провайдер.
Без фанатизма: трогаю только корявый транслит, живую речь — нет.