lekss361/gendesign
1
0
Fork 0
Code Issues 57 Pull requests Projects Releases Packages Wiki Activity Actions
gendesign/CLAUDE.md
lekss361 ae0fce3528
refactor(claude): split 700-line CLAUDE.md into path-scoped .claude/rules/ (#188) 
Old CLAUDE.md was 700 lines — exceeded Anthropic 200-line recommendation,
adherence degraded under context pressure.

Refactor per research findings:

- CLAUDE.md 700 -> 97 lines (essential only, pointers to rules)
- .claude/rules/{backend,frontend,sql,git-pr,deploy}.md (NEW, path-scoped)
- ~/.claude/CLAUDE.md (NEW, 21 lines) — personal cross-project prefs
- memory/ — deleted 12 feedback files promoted to proper layer (CLAUDE.md
  rules table, .claude/rules/, ~/.claude/CLAUDE.md). 7 remaining = workflow
  details.
- .gitignore: !.claude/agents/, !.claude/rules/ exceptions

Total auto-loaded per session: 97 (CLAUDE.md) + 21 (~/.claude) = 118 lines
vs prior 700. Rules in .claude/rules/ load only when matching paths touched.

Resolves conflict no_self_review vs pre_push_review: now single rule in
git-pr.md Review workflow section (pre-push = local lint; post-push =
external Claude window posting as lekss361).

Code-reviewer feedback applied:
- paths: frontmatter added to git-pr.md
- Auto-merge scope blocked-list now includes .claude/rules/*.md changes
  to prevent self-extending rules without human approval.

Co-authored-by: lekss361 <claudestars@proton.me>
2026-05-15 23:06:33 +03:00

5 KiB
Raw Blame History

GenDesign

Site Finder (AI-подбор инвест-участков) + Generative Design (концепции застройки) для девелоперов РФ. Live: https://gendsgn.ru/ — Свердловская обл. (ЕКБ, ПЗЗ, МСК-66).

Stack

Слой Stack
Backend Python 3.12, FastAPI, SQLAlchemy 2.0, GeoAlchemy2, Pydantic v2, Celery + Redis, httpx, Shapely 2
DB PostgreSQL 16 + PostGIS 3.4 (~50 таблиц, partitioned rosreestr_deals, GIST на geom)
Frontend Next.js 15 app router, React 19, TypeScript 5 strict, Tailwind 4, TanStack Query
Export WeasyPrint (PDF), ezdxf (DXF), openpyxl (Excel)
Tooling uv, ruff, mypy strict (selective), pytest, pre-commit, prettier
Deploy Beget VPS · GHA → GHCR → SSH → docker-compose · Caddy
Knowledge Obsidian vault obsidian.gendsgn.ru (CouchDB LiveSync)

Commands

# Dev (Docker):
docker compose up -d --build
curl http://localhost:8000/health

# Backend without Docker:
cd backend && uv sync && uv run uvicorn app.main:app --reload

# Frontend:
cd frontend && npm install && npm run dev

# Migrations:
make migration NAME=add_foo_column   # Alembic
# или raw SQL: data/sql/NN_topic.sql  # views, partitions, indexes

# Tests:
cd backend && uv run pytest
cd frontend && npm test

# Lint + typecheck:
cd backend && uv run --no-project --with ruff ruff check app/
cd frontend && npx tsc --noEmit && npm run lint

# Regen TS types from OpenAPI:
cd frontend && npm run codegen

Critical rules

  1. Knowledge = Obsidian vault only. mcp__obsidian__* tools. Local mirror: C:\Users\user\Documents\gendesign-memory. Deprecated: memory/memory-gendesign.jsonl — не читай, не пиши.

  2. Branch + PR mandatory. Никаких direct push в main. feat/... / fix/... / refactor/... / docs/... / chore/... → gh pr create → PR URL пользователю. После PR create — сразу ScheduleWakeup polling. Полные правила: .claude/rules/git-pr.md.

  3. Agent-first workflow. Main session orchestrates ONLY — не пишет код inline. Любая задача >1 файл / >50 строк → subagent. Pre-push: spawn code-reviewer subagent на staged changes. Post-push review — внешнее окно Claude (НЕ дублировать).

  4. psycopg v3 only. import psycopg2 → ModuleNotFoundError. CAST(:x AS type) в SQL — никогда :x::type. Полные правила: .claude/rules/backend.md + sql.md.

  5. No --no-verify / --force / --amend. Pre-commit hooks обязательны. Hook падает → fix root cause.

  6. Vault обновляется вместе с кодом — в той же сессии. Bug → fixes/, module → code/modules/, decision → decisions/, runbook → runbooks/.

  7. Тестируй каждый merge — chrome-devtools MCP или curl ДО/сразу после deploy. Не доверяй "тесты прошли" без verify.

Subagents (.claude/agents/)

Agent Scope
tech-analyst Нечёткая / cross-domain задача → план
backend-engineer backend/app/** — FastAPI, Celery, scrapers, services
frontend-engineer frontend/src/** — Next.js, React, hooks
database-expert data/sql/**.sql, Alembic, EXPLAIN ANALYZE
devops-engineer docker-compose*.yml, Caddyfile, .github/workflows/**
code-reviewer Pre-push lint (security, correctness, conventions)

Routing: тривиально (typo, 1-line) → main session. Single-domain clear → worker. Cross-domain / нечётко → tech-analyst first. Worker → code-reviewer → main commits → push → PR.

Where to look

  • Path-scoped rules: .claude/rules/ (backend, frontend, sql, git-pr, deploy) — auto-loaded при работе с соответствующими файлами
  • Personal preferences: ~/.claude/CLAUDE.md (cross-project: no auto-commit, no Co-Authored-By, no @claude)
  • Workflow memory: ~/.claude/projects/<repo>/memory/MEMORY.md index
  • Vault MOCs: meta/, domains/<area>/<area>-MOC.md, decisions/, fixes/, limitations/, code/patterns/
  • DB access: SSH tunnel ssh -N gendesign → localhost:15432 · Credentials: vault meta/00_credentials.md

Don't

  • ❌ import psycopg2 — только psycopg v3
  • ❌ Direct push в main / merge без approval
  • ❌ --no-verify / --amend / git push --force
  • ❌ print() в prod-коде — только logger.*
  • ❌ requests — только httpx
  • ❌ Knowledge-файлы вне vault (docs/research/, notes/, wiki/)
  • ❌ DROP TABLE / TRUNCATE без явного approval
  • ❌ Hardcode credentials в коде / коммитах

Maintenance: этот файл обновляется когда меняется tech stack, добавляются новые critical rules, или меняется структура rules/. Цель: ≤150 lines. Детали → .claude/rules/ или vault.