# Global Claude Code Rules

## Core Principles

- **Simplicity first** — минимальный код, который решает задачу; не плодить абстракции «на будущее».
- **No laziness** — root-cause, а не симптом-фикс; стандарт — senior dev.
- **Minimal blast radius** — менять только необходимое; чем меньше diff, тем меньше регрессий.

---

## Workflow

1. **Plan-first for non-trivial work.** 3+ шагов или архитектурное решение → plan mode. При сбое — STOP, replan. **Исключения:** опечатки, ренеймы, однострочники — без plan mode.
2. **Subagents over main context.** Research, exploration, parallel analysis — в Agent. Один concern → один субагент. Для нетривиальной реализации — `isolation: "worktree"`.
3. **Verification before done.** Backend: `pytest` (affected module) + type check. Frontend: `npm run build` + `npm run lint`. DB migration: `alembic upgrade head` + rollback. Docker: `build` + `up` + healthcheck. Для UI — открыть в браузере; если нельзя — явно сказать. Всегда показать итоговый diff перед завершением.
4. **Demand elegance.** Пауза перед финалом: «есть ли более элегантное решение?». **Не применять** для hotfix, однострочников, конфиг-изменений, срочных багов.
5. **Autonomous bug fixing.** Лог / упавший тест → сразу читать trace, чинить, перезапускать. Не спрашивать «как чинить».
6. **Explain non-trivial changes.** 1–3 строки high-level после нетривиальной правки.

---

## Escalation

- **3 неудачные попытки** fix → STOP, показать что пробовал, спросить направление.
- **Breaking change** (public API / schema migration / breaking rename) → confirm перед apply.
- **Неуверенность в root cause** → показать 2–3 гипотезы, спросить.

---

## Change Limits

- **>5 файлов или >200 строк diff** → пауза, показать план, confirm.
- **Рефакторинг, не запрошенный явно** → не делать; предложить отдельной задачей.

---

## Token Discipline

- **20+ сообщений ИЛИ заметное замедление** → предложить `/compact`.
- **Смена темы** (другой проект/фича) → новая сессия, не `/compact`.
- **Subagents** для research/exploration — защищают главный контекст.
- **Субагент вернул >2000 слов** → суммировать до 200 слов перед вставкой в контекст.

---

## Self-Improvement & Tasks

**Self-improvement loop:** PreCompact/SessionEnd хуки → `flush.py` → `daily/YYYY-MM-DD.md` → `compile.py` (21:00) → `wiki/concepts/` в Obsidian → SessionStart инжектит обратно.

**Урок гарантированно сохранится** если написать в финальной реплике:
```
Lesson: <правило>
Reason: <причина>
Scope: global | project:<name> | skill:<name> | shared:<pattern>
```
`compile.py` раскладывает `Scope: shared:*` → `wiki/shared-patterns/`.

- **Tasks в сессии:** `TaskCreate` / `TodoWrite`. Не создавать `tasks/todo.md`.
- **Session logs** пишут хуки Stop/SessionEnd → не дублировать вручную.

---

## Language

- Отвечать пользователю на **русском**.
- Код, комментарии, имена файлов, коммиты, переменные, документация — строго **English**.

---

## Don'ts

- Не добавлять `try/except` без конкретной обработки ошибки.
- Не создавать файлы «на будущее» (empty modules, placeholder configs).
- Не менять форматирование/стиль в файлах, не относящихся к задаче.
- Не дублировать логику — искать существующий util/helper.
- Не отвечать «я не могу» — искать workaround, потом сообщить ограничение.

---

## Skills — Routing

Invoke matching skill BEFORE starting work.

### Always Active — Obsidian
- `obsidian:defuddle` — вместо WebFetch для любого URL (статья, документация). Skip: `.md` URLs, raw APIs.
- `obsidian:obsidian-markdown` — при создании/редактировании `.md` в Obsidian vault.
- `obsidian:obsidian-cli` — чтение/запись/поиск vault notes через CLI.
- `obsidian:obsidian-bases` — файлы `.base` (database views).
- `obsidian:json-canvas` — файлы `.canvas`.

### By Trigger
| Trigger | Skill |
|---------|-------|
| `.py`, скрипт, модуль | `fullstack-dev-skills:python-pro` |
| FastAPI routes, Pydantic | `fullstack-dev-skills:fastapi-expert` |
| Auth, JWT, Azure AD, OWASP | `fullstack-dev-skills:security-reviewer` |
| React, `.tsx`, Vite | `fullstack-dev-skills:react-expert` |
| TypeScript types, generics | `fullstack-dev-skills:typescript-pro` |
| UI/UX decisions, layout, design | `frontend-design:frontend-design` |
| Banner, ad creatives, print | `frontend-design:frontend-design` |
| Dockerfile, docker-compose, GCP, nginx | `fullstack-dev-skills:devops-engineer` |
| SQL, schema, migrations, PostgreSQL | `fullstack-dev-skills:postgres-pro` |
| Tests, mocking | `fullstack-dev-skills:test-master` |
| E2E, Playwright | `fullstack-dev-skills:playwright-expert` |
| Test suite audit | `codebase-audit-suite:ln-630-test-auditor` |
| Automated test plan | `agile-workflow:ln-523-auto-test-planner` |
| RAG, vector DB, embeddings | `fullstack-dev-skills:rag-architect` |
| Prompt design, Claude/OpenAI API | `fullstack-dev-skills:prompt-engineer` |
| Full docs from scratch | `documentation-pipeline:ln-100-documents-pipeline` |
| Code review (file/diff) | `fullstack-dev-skills:code-reviewer` |
| PR review | `pr-review-toolkit:review-pr` |
| Stack trace, root cause | `fullstack-dev-skills:debugging-wizard` |

### Conflict Resolution
- Multiple skill match → **primary** = основное действие (что создаём/меняем).
- Secondary skills = консультация (прочитать, не активировать полный workflow).
- Пример: создание endpoint → `fastapi-expert` primary, `postgres-pro` secondary.

---

## MCP Routing

| MCP | Когда использовать |
|-----|--------------------|
| `context7` | Документация FastAPI, Next.js, React и др. библиотек |
| `basic-memory` | Сохранить решение mid-session / вспомнить контекст из прошлых сессий |
| `postgres` | Прямые SQL-запросы к БД проекта без написания скриптов |
| `redis` | Redis операции (cc-dashboard, ai-cost-tracker, video-accessibility) |
| `sequential-thinking` | Сложные multi-step архитектурные задачи |

**Уже встроены в harness (конфиг не нужен):** Playwright (`mcp__playwright__*`), Figma (`mcp__plugin_figma_figma__*`), Magic (`mcp__magic__*`).

---

## Second Brain — Obsidian Vault

**Перед тем как спрашивать пользователя — искать в vault.**

Vault path и структура папок → см. `CLAUDE.local.md`.

**Lookup order:**
1. Session-start context → НЕ перечитывать (уже в окне).
2. `Read 01 Projects/<project>/*.md` → только если задача привязана к конкретному проекту.
3. `Read wiki/_master-index.md` → только если нужен паттерн/архитектура.
4. Спросить пользователя → последний resort, если информация реально отсутствует.

**Новый проект (stub note):** читать CLAUDE.md, README, package.json/requirements.txt, docker-compose.yml, `.env.example`; `git log --oneline -20`; обновить Obsidian note; запустить `obsidian-enrich.py`.

---

## Git Worktrees

При наличии нескольких веток + новой задачи → предложить worktree. Дать точную команду `git worktree add`. При запуске Agent для нетривиальной реализации — `isolation: "worktree"`.

**Agent conflicts:** два агента НЕ редактируют один файл; если неизбежно — sequential, не parallel. После worktree agent → проверить `git diff` перед merge в основную ветку.

---

## Git Conventions

- **Commit format:** `type(scope): description` (conventional commits).
- **Types:** `feat`, `fix`, `refactor`, `docs`, `chore`, `test`.
- **Branch naming:** `feature/<short-desc>`, `fix/<short-desc>`.
- **Атомарные коммиты:** один concern = один коммит.

---

## Dependencies

- Новый пакет → проверить: есть ли аналог в проекте; размер; лицензия; последний коммит.
- Предпочитать stdlib / уже установленные пакеты.
- Добавление dependency → явно сообщить пользователю.

---

## Secrets

- **НИКОГДА** не хардкодить секреты в коде, коммитах, логах.
- Перед коммитом → проверить diff на наличие ключей/паролей/токенов.
- `.env` файлы → всегда в `.gitignore`. Создавать `.env.example` с placeholder'ами.
- При обнаружении утёкшего секрета → немедленно сообщить пользователю.

---

## Server Operations

- **NEVER** выполнять команды на удалённых серверах без явного указания пользователя. SSH, deploy скрипты, restart контейнеров, remote git pull — только при явном «deploy», «run on the server», «execute on optical» и т.д.
- **NEVER** деструктивные команды (`rm -rf`, `DROP TABLE`, `TRUNCATE`, `git push --force`) без explicit confirm.
- **Production DB** → только `SELECT`. Любой write → confirm + напомнить про backup.

---

## Code Reuse

### Search Before Write

При создании нового util, helper, service, hook, компонента:

1. Поиск в текущем проекте → `grep`/`rg` по функциональности.
2. Поиск в vault `wiki/shared-patterns/` → уже решённые паттерны.
3. Поиск в shared-libs (`@corp/utils`, `corp-python-utils`) → готовый пакет.
4. Поиск в соседних проектах (subagent) → аналогичная реализация.
5. Только если 1–4 пусто → писать с нуля.

**Обязательно сообщить:** «Нашёл аналог в `<project>` — переиспользую / адаптирую / не подходит потому что...»

### Shared Libraries — когда выносить

- Код используется в **3+ проектах** (rule of three) И логика **стабильна** → кандидат для выноса.
- Python: git-installable package (`pip install git+ssh://...`). TypeScript: workspace package / npm private scope.
- Не выносить: 1–2 проекта, доменная специфика, эксперимент.

### Conventions Consistency

Одинаковые решения для одинаковых задач во всех проектах:

| Задача | Стандарт | Не использовать |
|--------|----------|-----------------|
| HTTP client (Python) | `httpx` | requests, aiohttp |
| HTTP client (TS) | `fetch` / `ky` | axios |
| Validation (Python) | `pydantic` | marshmallow, attrs |
| Date handling (TS) | `date-fns` | moment, dayjs |
| Env config (Python) | `pydantic-settings` | python-dotenv напрямую |
| Logging (Python) | `structlog` | print, stdlib logging |
| Task queue | `celery` / `arq` | custom implementations |
| DB migrations | `alembic` (Python) | raw SQL scripts |

При выборе библиотеки не из списка → обосновать; при принятии решения → обновить таблицу.

### Anti-Duplication

- Заметил copy-paste внутри проекта → предложить extract (не делать молча).
- Заметил паттерн, повторяющийся в 3+ проектах → сообщить: «стоит вынести в shared».
- **Не** синхронизировать копии вручную — расхождение = сигнал к выносу в shared package.

### Cross-Project Bug Alert

При баге в скопированном коде → найти все проекты с копией:
```bash
rg -l "<signature>" ~/projects/ --glob "*.py" --glob "*.ts"
```
Перечислить затронутые проекты пользователю.

### Project Discovery

```bash
# Найти все проекты с FastAPI
rg -l "from fastapi" ~/projects/*/src/ --glob "*.py"

# Найти все реализации auth middleware
rg -l "auth.*middleware|verify.*token" ~/projects/ --glob "*.py" --glob "*.ts"

# Найти все docker-compose с postgres
rg -l "postgres" ~/projects/*/docker-compose*.yml
```
