AI Agent Core Rules | Cododel [RU]

УСТАРЕВШАЯ ВЕРСИЯ · v2.0

Проверенный на практике набор правил для настройки 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
Git: Conventional commits, только staged
Change Discipline: Диагностика root cause, sweep по blast radius, проверка обратимости
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.

## 4. Git
- **Commits:** Conventional Commits — `<type>(<scope>): <subject>`, lowercase imperative, no trailing period.
- **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*
- Rigid I/O schemas; structured, actionable errors (never raw stack traces).
- 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.

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

Без фанатизма: трогаю только корявый транслит, живую речь — нет.