lekss361/gendesign

Fork 0

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

Merged

lekss361 merged 1 commit from chore/claude-config-overhaul-v2 into main

2026-05-24 08:48:42 +00:00

lekss361 commented

2026-05-24 08:43:01 +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.

(Replaces #494 — that branch was cut from feat/tradein-geocode-missing-cron which contained an un-rebased pre-squash commit. This branch is clean from forgejo/main.)

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 "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.

Deterministic enforcement

scripts/claude-hooks/check-no-print.py + PostToolUse hook config: 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 (broken — git cannot re-include files under ignored parent) with explicit per-path ignore list. Now .claude/agents/ and .claude/rules/ properly tracked; local state (cache, sessions, plans, settings) stays ignored.

Out of scope (already applied locally, not in this PR)

MCP server config: Context7 add, postgres dedup, alwaysLoad on obsidian+postgres-gendesign (~/.claude.json / .mcp.json gitignored).
Slash commands → skills migration (vault-write, sort-inbox, retention-pass) — user-level (~/.claude/skills/).
~/.claude/CLAUDE.md edit (chrome-devtools → playwright).
MEMORY.md sweep — deferred; 7 promotion candidates marked in TODO section.

Test plan

Edit any backend/app/**/*.py to add print('test') — hook should block with explanation
Confirm .claude/agents/ and .claude/rules/ tracked: git ls-files .claude/
On next .tsx edit — verify ui-tokens.md + ui-conventions.md auto-load
Forgejo MCP merge flow (already proven in recent PRs)

## 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. (Replaces #494 — that branch was cut from `feat/tradein-geocode-missing-cron` which contained an un-rebased pre-squash commit. This branch is clean from `forgejo/main`.) ## 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 *"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. ### Deterministic enforcement - **`scripts/claude-hooks/check-no-print.py`** + PostToolUse hook config: 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 (broken — git cannot re-include files under ignored parent) with explicit per-path ignore list. Now `.claude/agents/` and `.claude/rules/` properly tracked; local state (cache, sessions, plans, settings) stays ignored. ## Out of scope (already applied locally, not in this PR) - MCP server config: Context7 add, postgres dedup, alwaysLoad on obsidian+postgres-gendesign (`~/.claude.json` / `.mcp.json` gitignored). - Slash commands → skills migration (`vault-write`, `sort-inbox`, `retention-pass`) — user-level (`~/.claude/skills/`). - `~/.claude/CLAUDE.md` edit (chrome-devtools → playwright). - MEMORY.md sweep — deferred; 7 promotion candidates marked in TODO section. ## Test plan - [ ] Edit any `backend/app/**/*.py` to add `print('test')` — hook should block with explanation - [ ] Confirm `.claude/agents/` and `.claude/rules/` tracked: `git ls-files .claude/` - [ ] On next `.tsx` edit — verify `ui-tokens.md` + `ui-conventions.md` auto-load - [ ] Forgejo MCP merge flow (already proven in recent PRs)

lekss361 added 1 commit 2026-05-24 08:43:01 +00:00

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

- 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)

lekss361 referenced this pull request

2026-05-24 08:43:23 +00:00

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

lekss361 merged commit 73bdff41a7 into main

2026-05-24 08:48:42 +00:00

lekss361 referenced this pull request from a commit

2026-05-24 08:48:43 +00:00

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

lekss361 commented

2026-05-24 08:49:14 +00:00

Author

Owner

Merged via deep-code-reviewer — verdict APPROVE (squash, merge commit 73bdff41).

Verified

.gitignore: git ls-files .claude/ returns 20 tracked files (agents/ + rules/ + deep-review-phases/) — explicit per-path list correctly avoids the git "can't re-include under ignored parent" trap; settings.json, cache/, sessions/, plans/ properly ignored.
check-no-print.py: regex (?<!\w)print\s*\( with # noqa escape + skip for backend/tests/ and backend/scripts/. Fall-open safe: JSON parse failure / missing fields / wrong tool / non-.py path → return 0 (does not block save). Exit 2 only on real match.
CLAUDE.md (63 lines): all 7 critical rules preserved (psycopg v3 + CAST trap, vault-only, agent-first, PR mandatory + gh bypassed, no --no-verify, vault-with-code, test-every-merge).
Frontmatter paths: correct on ui-tokens / ui-conventions / ui-microcopy (each scopes to a subset of frontend/**/*.{ts,tsx,css} — overlap is intentional so all three load on a .tsx edit).
tech-analyst.md: model: haiku confirmed. memory: project on code-reviewer, deep-code-reviewer, qa-tester.
.forgejo/workflows/** added to deploy.md paths and devops-engineer scope.
deep-review-phases/ (phase-1, 2, 3, 5) tracked and referenced inline from deep-code-reviewer.md via Read .claude/agents/deep-review-phases/phase-N-...md on-demand directives.

Minor follow-up (not blocking)

.claude/agents/code-reviewer.md:164 still references gh pr create in the "worker committed to main" recovery block. PR description claims code-reviewer.md was updated for the gh-bypass, but the diff only touched the typo fix at line 70 and the memory field. Should be mcp__forgejo__create_pull_request (or curl). Low impact — only triggered in a rare recovery scenario.
deep-review-phases/ has phase-1, 2, 3, 5 but no phase-4-preflight.md (phase 4 is inlined in the agent file). Cosmetic — fine as-is.

No security, correctness, or performance issues. Config-only change with no code path impact.

Merged via deep-code-reviewer — verdict APPROVE (squash, merge commit `73bdff41`). ### Verified - `.gitignore`: `git ls-files .claude/` returns 20 tracked files (agents/ + rules/ + deep-review-phases/) — explicit per-path list correctly avoids the git "can't re-include under ignored parent" trap; `settings.json`, `cache/`, `sessions/`, `plans/` properly ignored. - `check-no-print.py`: regex `(?<!\w)print\s*\(` with `# noqa` escape + skip for `backend/tests/` and `backend/scripts/`. **Fall-open safe**: JSON parse failure / missing fields / wrong tool / non-`.py` path → `return 0` (does not block save). Exit 2 only on real match. - CLAUDE.md (63 lines): all 7 critical rules preserved (psycopg v3 + CAST trap, vault-only, agent-first, PR mandatory + gh bypassed, no `--no-verify`, vault-with-code, test-every-merge). - Frontmatter `paths:` correct on ui-tokens / ui-conventions / ui-microcopy (each scopes to a subset of `frontend/**/*.{ts,tsx,css}` — overlap is intentional so all three load on a `.tsx` edit). - `tech-analyst.md`: `model: haiku` confirmed. `memory: project` on code-reviewer, deep-code-reviewer, qa-tester. - `.forgejo/workflows/**` added to deploy.md paths and devops-engineer scope. - deep-review-phases/ (phase-1, 2, 3, 5) tracked and referenced inline from `deep-code-reviewer.md` via `Read .claude/agents/deep-review-phases/phase-N-...md` on-demand directives. ### Minor follow-up (not blocking) - `.claude/agents/code-reviewer.md:164` still references `gh pr create` in the "worker committed to main" recovery block. PR description claims `code-reviewer.md` was updated for the gh-bypass, but the diff only touched the typo fix at line 70 and the memory field. Should be `mcp__forgejo__create_pull_request` (or curl). Low impact — only triggered in a rare recovery scenario. - `deep-review-phases/` has phase-1, 2, 3, 5 but no `phase-4-preflight.md` (phase 4 is inlined in the agent file). Cosmetic — fine as-is. No security, correctness, or performance issues. Config-only change with no code path impact.

lekss361 referenced this pull request from a commit

2026-05-24 08:56:15 +00:00

chore(claude-rules): promote 3 deferred feedback rules from memory

lekss361 referenced this pull request

2026-05-24 08:56:34 +00:00

chore(claude-rules): promote 3 deferred feedback rules from memory #496