ae0fce3528
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>
97 lines
5 KiB
Markdown
97 lines
5 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 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.
|