chore(claude-config): align with 2026 best practices #494

Closed

lekss361 wants to merge 2 commits from chore/claude-config-overhaul into main

lekss361 commented

2026-05-24 08:40:50 +00:00

Owner

Summary

Comprehensive overhaul of Claude Code configuration to align with Anthropic 2026 best practices + community patterns. Audit report covered 17 instruction files across CLAUDE.md, .claude/rules/, .claude/agents/, slash commands, and MCP setup.

Changes

Critical fixes (active conflicts)

gh CLI → Forgejo MCP/curl across git-pr.md, deploy.md, code-reviewer.md, deep-code-reviewer.md. gh was bypassed 2026-05-16 but rules still referenced it (per-Anthropic "if two files give different guidance, Claude may pick one arbitrarily").
mcp__postgres__ → mcp__postgres-gendesign__ typo in code-reviewer.md:70 (tool didn't exist).
.forgejo/workflows/** added to deploy.md paths and devops-engineer scope (deploy migrated to Forgejo Actions in PR #192).

Context reduction (Anthropic: "target under 200 lines per CLAUDE.md")

CLAUDE.md: 97 → 63 lines. Dropped ## Commands block (per official "Exclude anything Claude can figure out by reading code") and ## Don't duplicates already covered by .claude/rules/*.
deep-code-reviewer.md: 391 → 135 lines. Phase 1/2/3/5 details split into .claude/agents/deep-review-phases/ — loaded on demand instead of every spawn.
ui-ux.md (215 lines): split into ui-tokens.md (87), ui-conventions.md (129), ui-microcopy.md (29) under narrower paths: to reduce hot-context per .tsx edit by ~40%.

Optimizations

tech-analyst model: sonnet → haiku — agent is read-only research (like built-in Explore), Haiku gives ~10x cost reduction per spawn.
memory: project field added to code-reviewer, deep-code-reviewer, qa-tester — agents accumulate recurring patterns across sessions (per Anthropic subagent persistent memory).

Deterministic enforcement (vs CLAUDE.md guidance)

scripts/claude-hooks/check-no-print.py + PostToolUse hook config in .claude/settings.json: blocks print( calls introduced in backend/**/*.py (skips tests/, scripts/; allows # noqa escape hatch). Per Anthropic: "hooks are deterministic and guarantee the action happens".

`.gitignore` fix

Replaced .claude/ + !.claude/agents/** whitelist pattern (broken — git cannot re-include files under ignored parent) with explicit per-path ignore list. Now .claude/agents/ and .claude/rules/ are properly tracked while local state (cache, sessions, plans, settings) stays ignored.

Out of scope (not in this PR)

MCP changes (Context7 add, postgres dedup, alwaysLoad) — local user/project config (~/.claude.json, .mcp.json gitignored), already applied.
Slash commands → skills migration (vault-write, sort-inbox, retention-pass) — user-level personal files in ~/.claude/skills/.
~/.claude/CLAUDE.md edits — personal cross-project config.
MEMORY.md sweep — deferred, 7 promotion candidates marked in ~/.claude/projects/.../memory/MEMORY.md TODO section.

Test plan

Verify hook fires: edit any backend/app/**/*.py to add print('test') — should be blocked with explanation
Verify Forgejo MCP works for review/merge (already proven in recent PRs)
Confirm .claude/agents/ and .claude/rules/ properly tracked (git ls-files .claude/)
On next frontend/src/**/*.tsx edit — verify ui-tokens.md + ui-conventions.md auto-load (smaller context than old ui-ux.md)

Notes for reviewer

Branch base: chore/claude-config-overhaul was cut from current session branch feat/tradein-geocode-missing-cron (after PR #490 merged). All commits independent — clean apply on top of main.

Audit details: see config-overhaul session report (executed 2026-05-24).

## Summary Comprehensive overhaul of Claude Code configuration to align with Anthropic 2026 best practices + community patterns. Audit report covered 17 instruction files across CLAUDE.md, `.claude/rules/`, `.claude/agents/`, slash commands, and MCP setup. ## Changes ### Critical fixes (active conflicts) - **gh CLI → Forgejo MCP/curl** across `git-pr.md`, `deploy.md`, `code-reviewer.md`, `deep-code-reviewer.md`. `gh` was bypassed 2026-05-16 but rules still referenced it (per-Anthropic *"if two files give different guidance, Claude may pick one arbitrarily"*). - **`mcp__postgres__` → `mcp__postgres-gendesign__`** typo in `code-reviewer.md:70` (tool didn't exist). - **`.forgejo/workflows/**`** added to `deploy.md` paths and `devops-engineer` scope (deploy migrated to Forgejo Actions in PR #192). ### Context reduction (Anthropic: "target under 200 lines per CLAUDE.md") - **CLAUDE.md**: 97 → 63 lines. Dropped `## Commands` block (per official *"Exclude anything Claude can figure out by reading code"*) and `## Don't` duplicates already covered by `.claude/rules/*`. - **`deep-code-reviewer.md`**: 391 → 135 lines. Phase 1/2/3/5 details split into `.claude/agents/deep-review-phases/` — loaded on demand instead of every spawn. - **`ui-ux.md` (215 lines)**: split into `ui-tokens.md` (87), `ui-conventions.md` (129), `ui-microcopy.md` (29) under narrower `paths:` to reduce hot-context per `.tsx` edit by ~40%. ### Optimizations - **`tech-analyst` model: sonnet → haiku** — agent is read-only research (like built-in `Explore`), Haiku gives ~10x cost reduction per spawn. - **`memory: project` field** added to `code-reviewer`, `deep-code-reviewer`, `qa-tester` — agents accumulate recurring patterns across sessions (per Anthropic [subagent persistent memory](https://code.claude.com/docs/en/sub-agents#enable-persistent-memory)). ### Deterministic enforcement (vs CLAUDE.md guidance) - **`scripts/claude-hooks/check-no-print.py`** + PostToolUse hook config in `.claude/settings.json`: blocks `print(` calls introduced in `backend/**/*.py` (skips tests/, scripts/; allows `# noqa` escape hatch). Per Anthropic: *"hooks are deterministic and guarantee the action happens"*. ### `.gitignore` fix - Replaced `.claude/ + !.claude/agents/**` whitelist pattern (broken — git cannot re-include files under ignored parent) with explicit per-path ignore list. Now `.claude/agents/` and `.claude/rules/` are properly tracked while local state (cache, sessions, plans, settings) stays ignored. ## Out of scope (not in this PR) - **MCP changes** (Context7 add, postgres dedup, alwaysLoad) — local user/project config (`~/.claude.json`, `.mcp.json` gitignored), already applied. - **Slash commands → skills migration** (`vault-write`, `sort-inbox`, `retention-pass`) — user-level personal files in `~/.claude/skills/`. - **`~/.claude/CLAUDE.md` edits** — personal cross-project config. - **MEMORY.md sweep** — deferred, 7 promotion candidates marked in `~/.claude/projects/.../memory/MEMORY.md` TODO section. ## Test plan - [ ] Verify hook fires: edit any `backend/app/**/*.py` to add `print('test')` — should be blocked with explanation - [ ] Verify Forgejo MCP works for review/merge (already proven in recent PRs) - [ ] Confirm `.claude/agents/` and `.claude/rules/` properly tracked (`git ls-files .claude/`) - [ ] On next `frontend/src/**/*.tsx` edit — verify `ui-tokens.md` + `ui-conventions.md` auto-load (smaller context than old `ui-ux.md`) ## Notes for reviewer Branch base: `chore/claude-config-overhaul` was cut from current session branch `feat/tradein-geocode-missing-cron` (after PR #490 merged). All commits independent — clean apply on top of `main`. Audit details: see [config-overhaul session report](https://git.gendsgn.ru/lekss361/gendesign/pulls/) (executed 2026-05-24).

lekss361 added 2 commits 2026-05-24 08:40:51 +00:00

fix(tradein): geocode backfill + remove Avito exclusion from estimator fdfb74ca88

После C-5 fix (PR #487) Avito coords либо NULL либо реальные. Estimator
исключал source='avito' из radius search потому что раньше там был jitter
(±0.005°) от 5 anchor cron'ов. Сейчас:
- 3580 Avito + 641 Yandex + 106 N1 + 38 Cian listings без coords
- estimator._fetch_analogs ловил только cian/yandex/n1 = ~30% эффективной базы

Bundled fix:
1. app/tasks/geocode_missing.py — batch geocoder (Nominatim 1/s, dedup по address)
2. POST /admin/scrape/geocode-missing-listings + GET status — manual trigger
3. estimator.py: убран AND source <> 'avito' — после backfill Avito включён в radius

Result: после backfill +4166 Avito listings в radius search = +40% эффективной
data. Confidence "high" будет в ~70% случаев вместо ~30%.

Tests: 11 новых tests/tasks/test_geocode_missing.py — all pass.

chore(claude-config): align with 2026 best practices 13dbe6e681

- CLAUDE.md: 97->63 lines, drop dev-commands and Don't duplicates
  already covered by .claude/rules/*
- git-pr.md, deploy.md: replace gh CLI with Forgejo MCP/curl
- code-reviewer.md: fix mcp__postgres__ -> mcp__postgres-gendesign__
- tech-analyst.md: sonnet -> haiku
- deep-code-reviewer.md: 391->135 lines, phase details split into
  .claude/agents/deep-review-phases/ (loaded on demand)
- qa-tester, code-reviewer, deep-code-reviewer: add memory: project
- ui-ux.md: split into ui-tokens/ui-conventions/ui-microcopy
- scripts/claude-hooks/check-no-print.py + PostToolUse hook
- .gitignore: explicit list (git whitelist limitation)