---
title: "Global Claude Code Rules (CLAUDE.md)"
aliases: [claude-md-rules, global-rules, claude-global-config]
tags: [claude-code, configuration, workflow, rules, skills, mcp]
sources: [raw/Claude Code Global Rules (CLAUDE.md).md]
created: 2026-05-15
updated: 2026-05-15
---

# Global Claude Code Rules (CLAUDE.md)

The global `CLAUDE.md` file sets the operating contract for Claude Code across all projects. It enforces engineering discipline, context hygiene, and consistent conventions.

---

## Core Principles

- **Simplicity first** — minimum code that solves the task; no speculative abstractions.
- **No laziness** — fix root cause, not symptoms; senior-dev standard.
- **Minimal blast radius** — change only what's necessary; smaller diff = fewer regressions.

---

## Workflow Rules

| Rule | Detail |
|------|--------|
| **Plan-first** | 3+ steps or architecture → plan mode. Exceptions: typos, renames, one-liners. |
| **Subagents over main context** | Research/exploration/parallel analysis → Agent tool. Non-trivial impl → `isolation: "worktree"`. |
| **Verify before done** | Backend: `pytest` + type check. Frontend: `npm run build` + lint. DB: `alembic upgrade head` + rollback. Docker: build + up + healthcheck. |
| **Demand elegance** | Pause before finalizing: "is there a more elegant solution?" Skip for hotfixes/one-liners/config changes. |
| **Autonomous bug fixing** | Log/failed test → read trace, fix, re-run immediately. Never ask "how to fix." |
| **Explain non-trivial changes** | 1–3 lines high-level after any non-trivial edit. |

---

## Escalation Thresholds

- **3 failed fix attempts** → STOP, show what was tried, ask for direction.
- **Breaking change** (public API / schema migration / breaking rename) → confirm before applying.
- **Uncertain root cause** → show 2–3 hypotheses, ask.

---

## Change Limits

- **>5 files or >200 lines diff** → pause, show plan, confirm.
- **Unrequested refactoring** → don't do it; offer as a separate task.

---

## Token Discipline

- **20+ messages OR noticeable slowdown** → suggest `/compact`.
- **Topic switch** (different project/feature) → new session, not `/compact`.
- **Subagent returned >2000 words** → summarize to 200 words before inserting into context.

---

## Self-Improvement Loop

```
PreCompact/SessionEnd hooks → flush.py → daily/YYYY-MM-DD.md
  → compile.py (21:00) → wiki/concepts/ in Obsidian
  → SessionStart injects back
```

**Guaranteed lesson persistence** — write in final reply:
```
Lesson: <rule>
Reason: <reason>
Scope: global | project:<name> | skill:<name> | shared:<pattern>
```
`compile.py` routes `Scope: shared:*` → `wiki/shared-patterns/`.

- **Session tasks:** `TaskCreate` / `TodoWrite`. Never create `tasks/todo.md`.
- **Session logs** are written by Stop/SessionEnd hooks — don't duplicate manually.

---

## Language Policy

- Respond to user in **Russian**.
- Code, comments, file names, commits, variables, docs — strictly **English**.

---

## Don'ts

- No `try/except` without specific error handling.
- No files created "for the future" (empty modules, placeholder configs).
- No formatting/style changes in files unrelated to the task.
- No logic duplication — find existing util/helper first.
- Never say "I can't" — find a workaround, then report the limitation.

---

## Skills Routing

### Always Active (Obsidian)

| Skill | When |
|-------|------|
| `obsidian:defuddle` | Instead of WebFetch for any URL (articles, docs). Skip: `.md` URLs, raw APIs. |
| `obsidian:obsidian-markdown` | Creating/editing `.md` in Obsidian vault. |
| `obsidian:obsidian-cli` | Reading/writing/searching vault notes via CLI. |
| `obsidian:obsidian-bases` | `.base` files (database views). |
| `obsidian:json-canvas` | `.canvas` files. |

### By Trigger

| Trigger | Skill |
|---------|-------|
| `.py`, script, module | `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` |
| 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` |
| 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 = main action; secondary = consult only.

---

## MCP Routing

| MCP | When |
|-----|------|
| `context7` | Docs for FastAPI, Next.js, React, etc. |
| `basic-memory` | Save solution mid-session / recall past-session context |
| `postgres` | Direct SQL queries to project DB without writing scripts |
| `redis` | Redis operations (cc-dashboard, ai-cost-tracker, video-accessibility) |
| `sequential-thinking` | Complex multi-step architectural tasks |

Built into harness (no config needed): Playwright, Figma MCP, Magic.

---

## Second Brain — Obsidian Vault

**Before asking user — search vault first.**

**Lookup order:**
1. Session-start context → do NOT re-read (already in window).
2. `Read 01 Projects/<project>/*.md` → only if task is project-specific.
3. `Read wiki/_master-index.md` → only if pattern/architecture needed.
4. Ask user → last resort if info truly absent.

---

## Git Rules

- **Commit format:** `type(scope): description` (conventional commits)
- **Types:** `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
- **Branch naming:** `feature/<short-desc>`, `fix/<short-desc>`
- **Atomic commits:** one concern = one commit
- **Worktrees:** multiple branches + new task → offer worktree; Agent for non-trivial impl → `isolation: "worktree"`
- **Agent conflicts:** two agents must NOT edit the same file; if unavoidable — sequential, not parallel

---

## Dependencies Policy

- New package → check: existing analogue in project; size; license; last commit.
- Prefer stdlib / already-installed packages.
- Adding dependency → explicitly notify user.

---

## Secrets Policy

- **NEVER** hardcode secrets in code, commits, logs.
- Before commit → check diff for keys/passwords/tokens.
- `.env` files → always in `.gitignore`. Create `.env.example` with placeholders.
- Found leaked secret → immediately notify user.

---

## Server Operations

- **NEVER** run commands on remote servers without explicit user instruction.
- **NEVER** destructive commands (`rm -rf`, `DROP TABLE`, `TRUNCATE`, `git push --force`) without explicit confirm.
- **Production DB** → `SELECT` only. Any write → confirm + remind about backup.

---

## Code Reuse

### Search Before Write

1. Search current project → `grep`/`rg` by functionality.
2. Search vault `wiki/shared-patterns/` → already-solved patterns.
3. Search shared-libs → ready package.
4. Search neighboring projects (subagent) → similar implementation.
5. Only if 1–4 empty → write from scratch.

### Standard Library Choices

| Task | Standard | Avoid |
|------|----------|-------|
| 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 directly |
| Logging (Python) | `structlog` | print, stdlib logging |
| Task queue | `celery` / `arq` | custom implementations |
| DB migrations | `alembic` (Python) | raw SQL scripts |

### Anti-Duplication

- Copy-paste spotted inside project → offer extract (don't do silently).
- Pattern repeated in 3+ projects → flag: "worth moving to shared".
- Never sync copies manually — divergence = signal to extract shared package.

---

## Key Takeaways

- All Claude Code sessions operate under these rules globally via `~/.claude/CLAUDE.md`.
- Plan mode is mandatory for 3+ step tasks; subagents protect main context.
- Verification is non-negotiable before marking work done.
- Skills are invoked by trigger (file type, task type) — always before starting work.
- Git uses conventional commits + atomic changes; worktrees for parallel agent work.
- Code reuse: search 4 places before writing from scratch; standard library table is authoritative.
- Session self-improvement loop: hooks → flush.py → compile.py → Obsidian wiki → re-injected next session.

---

## Related

- [[wiki/claude-code/dot-claude-folder|dot-claude-folder]] — `.claude/` folder structure (CLAUDE.md location, hooks, skills, agents)
- [[wiki/claude-code/skills|skills]] — Skills system: creation, storage scopes, invocation
- [[wiki/claude-code/custom-subagents|custom-subagents]] — Subagent patterns referenced in workflow rules
- [[wiki/claude-code/oliver-skills-config|oliver-skills-config]] — Oliver Agency skills selection rationale
- [[wiki/claude-code/scheduled-tasks|scheduled-tasks]] — `/loop`, `CronCreate` tools for session scheduling
- [[wiki/architecture/new-project-checklist|new-project-checklist]] — New project stub note procedure

---

## Sources

- `raw/Claude Code Global Rules (CLAUDE.md).md`
