refactor(claude): split CLAUDE.md 700 → 97 lines + .claude/rules/ #188

Merged

lekss361 merged 1 commit from refactor/claude-md-rules-split into main

2026-05-15 20:06:34 +00:00

lekss361 commented

2026-05-15 19:59:46 +00:00

(Migrated from github.com)

Summary

Old CLAUDE.md was 700 lines — exceeded Anthropic recommended 200-line limit. Adherence visibly degraded (rules drowned each other). Refactor per research findings.

Changes

File	Before	After	Notes
`CLAUDE.md`	700	97	Essentials only, pointers to rules
`.claude/rules/backend.md`	—	81	psycopg v3, CAST trap, SAVEPOINT, SQL injection, ruff
`.claude/rules/frontend.md`	—	48	TS strict, React 19/Next 15, TanStack Query, XSS safeUrl
`.claude/rules/sql.md`	—	69	NN_ naming, idempotency, VIEW deps, CAST trap
`.claude/rules/git-pr.md`	—	105	branch+PR, polling, auto-merge scope, sequential PRs
`.claude/rules/deploy.md`	—	48	GHA triggers, caddy reload, .env safety
`~/.claude/CLAUDE.md`	—	21	Personal cross-project (NOT in repo)

Memory cleanup (NOT in repo, lives in ~/.claude/projects/<repo>/memory/):

Deleted 12 feedback_*.md promoted to proper layer
7 remaining = operational workflow details
MEMORY.md index rewritten

Why

Anthropic recommends ≤200 lines for CLAUDE.md. HumanLayer keeps theirs under 60. With path-scoped rules, each session loads:

97 lines (CLAUDE.md) + 21 lines (~/.claude) = 118 lines always
+ relevant .claude/rules/<topic>.md only when touching matching files

vs prior 700 lines always-loaded.

Conflict resolved

no_self_review vs pre_push_review — now single rule in git-pr.md:

Pre-push (локально): spawn code-reviewer на staged → lint pass
Post-push (external window): bot posts reviews as lekss361; main session не дублирует

.gitignore

Added !.claude/agents/** + !.claude/rules/** exceptions so team-shared agents + rules are git-tracked, but .claude/cache/, .claude/settings.local.json, .claude/scheduled_tasks.lock remain ignored.

Code-reviewer fixes applied

paths: frontmatter добавлен в git-pr.md
Auto-merge scope blocked-list расширен: PR меняющий .claude/rules/*.md Auto-merge scope → требует human approval (prevents self-extending rules)

Test plan

Открыть новую сессию Claude Code → проверить что rules загружаются при работе с matching paths (открыть backend file → backend.md в context, открыть SQL file → sql.md в context)
/memory команда показывает обновлённый MEMORY.md
Existing .claude/agents/ без изменений — subagent routing работает как раньше

Related: research report по Claude Code best practices (memory hierarchy, path-scoped rules, hook enforcement).

## Summary Old CLAUDE.md was 700 lines — exceeded Anthropic recommended 200-line limit. Adherence visibly degraded (rules drowned each other). Refactor per research findings. ### Changes | File | Before | After | Notes | |---|---|---|---| | `CLAUDE.md` | 700 | **97** | Essentials only, pointers to rules | | `.claude/rules/backend.md` | — | 81 | psycopg v3, CAST trap, SAVEPOINT, SQL injection, ruff | | `.claude/rules/frontend.md` | — | 48 | TS strict, React 19/Next 15, TanStack Query, XSS safeUrl | | `.claude/rules/sql.md` | — | 69 | NN_ naming, idempotency, VIEW deps, CAST trap | | `.claude/rules/git-pr.md` | — | 105 | branch+PR, polling, auto-merge scope, sequential PRs | | `.claude/rules/deploy.md` | — | 48 | GHA triggers, caddy reload, .env safety | | `~/.claude/CLAUDE.md` | — | 21 | Personal cross-project (NOT in repo) | **Memory cleanup** (NOT in repo, lives in `~/.claude/projects/<repo>/memory/`): - Deleted 12 `feedback_*.md` promoted to proper layer - 7 remaining = operational workflow details - MEMORY.md index rewritten ### Why Anthropic recommends ≤200 lines for CLAUDE.md. HumanLayer keeps theirs under 60. With path-scoped rules, each session loads: - 97 lines (CLAUDE.md) + 21 lines (~/.claude) = **118 lines always** - `+ relevant .claude/rules/<topic>.md` only when touching matching files vs prior 700 lines always-loaded. ### Conflict resolved `no_self_review` vs `pre_push_review` — now single rule in `git-pr.md`: - **Pre-push** (локально): spawn code-reviewer на staged → lint pass - **Post-push** (external window): bot posts reviews as `lekss361`; main session не дублирует ### .gitignore Added `!.claude/agents/**` + `!.claude/rules/**` exceptions so team-shared agents + rules are git-tracked, but `.claude/cache/`, `.claude/settings.local.json`, `.claude/scheduled_tasks.lock` remain ignored. ### Code-reviewer fixes applied - `paths:` frontmatter добавлен в git-pr.md - Auto-merge scope blocked-list расширен: PR меняющий `.claude/rules/*.md` Auto-merge scope → требует human approval (prevents self-extending rules) ## Test plan - [ ] Открыть новую сессию Claude Code → проверить что rules загружаются при работе с matching paths (открыть backend file → backend.md в context, открыть SQL file → sql.md в context) - [ ] `/memory` команда показывает обновлённый MEMORY.md - [ ] Existing `.claude/agents/` без изменений — subagent routing работает как раньше Related: research report по Claude Code best practices (memory hierarchy, path-scoped rules, hook enforcement).

lekss361 commented

2026-05-15 20:06:24 +00:00

(Migrated from github.com)

Review

Pure docs/config refactor (+1077/-540, 13 files). CI infra failed (5s, no steps, runner_id=0) — известный transient GH Actions pattern (#187 имел тот же симптом). Cross-check (agent) подтверждает корректность.

✅ YAML frontmatter в `.claude/rules/*.md` валиден

backend.md: paths: backend/**/*.py
frontend.md: paths: frontend/**/*.{ts,tsx,jsx,js}
sql.md: paths: data/sql/**/*.sql
git-pr.md: paths: list (.claude/**, .github/**)
deploy.md: paths: list (docker-compose*.yml, Caddyfile, .github/workflows/**)

Все 5 фронтматтеров валидны.

✅ `.gitignore` корректен

.claude/ ignored + !.claude/agents/**, !.claude/rules/** negations. Cache/lock files остаются ignored через blanket. Нет accidental untracking важных файлов.

✅ Conflict resolved + self-extending protection

git-pr.md разделяет pre-push (local) и post-push (external). Blocked-list explicitly требует human approval для PR меняющих .claude/rules/*.md.

✅ Agent integrity

6 новых agents с валидным frontmatter, unique names, "Use proactively for..." pattern.

✅ CLAUDE.md essentials сохранены

psycopg v3, CAST trap, SQL injection, "approve merge" marker, memory layer — всё referenced через pointers.

✅ Risk

Pure docs/config, no runtime code → bounded blast.

approve merge

## Review Pure docs/config refactor (+1077/-540, 13 files). CI infra failed (5s, no steps, runner_id=0) — известный transient GH Actions pattern (#187 имел тот же симптом). Cross-check (agent) подтверждает корректность. ### ✅ YAML frontmatter в `.claude/rules/*.md` валиден - `backend.md`: `paths: backend/**/*.py` - `frontend.md`: `paths: frontend/**/*.{ts,tsx,jsx,js}` - `sql.md`: `paths: data/sql/**/*.sql` - `git-pr.md`: `paths:` list (`.claude/**`, `.github/**`) - `deploy.md`: `paths:` list (`docker-compose*.yml`, `Caddyfile`, `.github/workflows/**`) Все 5 фронтматтеров валидны. ### ✅ `.gitignore` корректен `.claude/` ignored + `!.claude/agents/**`, `!.claude/rules/**` negations. Cache/lock files остаются ignored через blanket. Нет accidental untracking важных файлов. ### ✅ Conflict resolved + self-extending protection `git-pr.md` разделяет pre-push (local) и post-push (external). Blocked-list explicitly требует human approval для PR меняющих `.claude/rules/*.md`. ### ✅ Agent integrity 6 новых agents с валидным frontmatter, unique names, "Use proactively for..." pattern. ### ✅ CLAUDE.md essentials сохранены psycopg v3, CAST trap, SQL injection, "approve merge" marker, memory layer — всё referenced через pointers. ### ✅ Risk Pure docs/config, no runtime code → bounded blast. approve merge