Skip to content

Commit 40498e9

Browse files
KanoCiferKanoCifer
committed
v2.6.3
1 parent e4eaae3 commit 40498e9

16 files changed

Lines changed: 2143 additions & 448 deletions

File tree

‎CLAUDE.md‎

Lines changed: 169 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,188 @@
11
# CLAUDE.md
22

3-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3+
Repository guidance for agentic coding assistants in this project.
44

5-
## 🤖 Agent Rules
6-
> Important: The following rules apply to development agents only
7-
- When the user asks in Chinese, respond in Chinese
8-
- When editing existing files, prefer the `edit` tool over the `write` tool
9-
- After editing frontend code, run `pnpm type-check`. **Do NOT auto-run `pnpm build`** unless explicitly requested
10-
- Before committing code, run the corresponding language's formatting and linting commands
11-
- Do NOT add code comments unless explicitly asked
12-
- Keep responses concise and technical; avoid conversational filler
5+
## 1) Agent Rules (Highest Priority)
6+
7+
- 用户使用中文提问时，使用中文回复。
8+
- 编辑已有文件时，使用增量修改，不做无关重写。
9+
- 修改前端代码后，必须运行：`pnpm run type-check`。
10+
- **不要自动运行 `pnpm run build`**，除非用户明确要求。
11+
- 提交前执行对应语言的格式化与 lint。
12+
- 未经用户要求，不主动添加代码注释。
13+
- 回复保持简洁、技术化。
14+
- `/init-deep` 类任务仅更新 `CLAUDE.md`，不要创建/修改 `AGENTS.md`。
15+
16+
---
17+
18+
## 2) Project Overview
19+
20+
- Stack: FastAPI + Vue 3 + TypeScript
21+
- Ports: backend `:5555`, frontend `:5173`
22+
- Main domains: auth, books, blog, messages, RSS, AI, admin/monitoring
23+
24+
### Key directories
25+
26+
```text
27+
backend/
28+
app/api/v1/ # route layer
29+
app/services/ # business logic
30+
app/repositories/ # data access
31+
app/schemas/ # request/response contracts
32+
app/models/ # SQLAlchemy + Beanie
33+
app/core/ # config/security/logging
34+
app/tasks/ # async jobs
35+
app/main.py # FastAPI entry
36+
test/ # pytest tests
37+
dev.py # backend dev entry
38+
39+
frontend/
40+
src/views/ # page-level components
41+
src/components/ # reusable UI
42+
src/auth/ # auth logic
43+
src/service/ # API adapters
44+
src/stores/ # Pinia stores
45+
src/router/ # route and guards
46+
src/types/ # shared TS types
47+
package.json # command entry
48+
vitest.config.ts # unit test config
49+
50+
scripts/
51+
package.json # utility scripts
52+
```
1353

1454
---
1555

16-
## Project Overview
17-
Full-stack reading list management and personal blog system built with FastAPI + Vue 3. Features include user authentication, book management, WeRead import, blog system, guestbook, RSS reader, AI assistant, and admin monitoring.
56+
## 3) Build / Lint / Test Commands
57+
58+
> Commands should run in the indicated directory.
1859
19-
## Common Commands
60+
### Backend (`cd backend`)
2061

21-
### Backend (run from `backend/`)
2262
```bash
23-
python dev.py # Start dev server (:5555)
24-
ruff format . && ruff check . # Format + lint
25-
ruff check . --fix # Auto-fix lint issues
26-
alembic revision --autogenerate -m "desc" # Generate migration
27-
alembic upgrade head # Run all migrations
28-
29-
# Testing
30-
python -m pytest # All tests
31-
python -m pytest test/test_main.py -v # Single file
32-
python -m pytest test/core/test_config.py::test_config_loading -v # Single function
33-
python -m pytest -k "config" -v # Filter by keyword
34-
python -m pytest --tb=short # Short traceback
63+
# run dev server
64+
python dev.py
65+
66+
# format + lint
67+
ruff format . && ruff check .
68+
ruff check . --fix
69+
70+
# migrations
71+
alembic revision --autogenerate -m "desc"
72+
alembic upgrade head
73+
74+
# tests
75+
python -m pytest
76+
python -m pytest test/test_main.py -v
77+
python -m pytest test/core/test_config.py::test_config_loading -v
78+
python -m pytest -k "config" -v
79+
python -m pytest --tb=short
3580
```
3681

37-
### Frontend (run from `frontend/`)
82+
### Frontend (`cd frontend`)
83+
3884
```bash
39-
pnpm run dev # Start dev server (:5173)
40-
pnpm run format # Prettier format
41-
pnpm run lint # Oxlint + ESLint check
42-
pnpm run type-check # TypeScript type-check (vue-tsc)
43-
pnpm run build # Full build (type-check + compile)
44-
pnpm run build-only # Build only (skip type-check)
45-
46-
# Testing
47-
pnpm run test:unit # Vitest unit tests
48-
pnpm run test:unit -- src/path/to/file.test.ts # Single file
49-
pnpm run test:unit -- -t "should render title" # By test name
50-
pnpm run test:unit -- src/path/to/file.test.ts -t "should render title" # File + test name
51-
pnpm run test:unit -- src/path/to/file.test.ts:42 # File + line
52-
npx playwright test # Playwright E2E
53-
npx playwright test --headed # E2E with browser UI
54-
npx playwright test --debug # Debug E2E
85+
# dev and quality
86+
pnpm run dev
87+
pnpm run format
88+
pnpm run lint
89+
pnpm run type-check
90+
91+
# build (only if user asks)
92+
pnpm run build
93+
pnpm run build-only
94+
95+
# vitest
96+
pnpm run test:unit
97+
pnpm run test:unit -- src/path/to/file.test.ts
98+
pnpm run test:unit -- -t "should render title"
99+
pnpm run test:unit -- src/path/to/file.test.ts -t "should render title"
100+
pnpm run test:unit -- src/path/to/file.test.ts:42
101+
102+
# playwright
103+
npx playwright test
104+
npx playwright test --headed
105+
npx playwright test --debug
106+
npx playwright test tests/foo.spec.ts:42
107+
npx playwright test -g "should login"
55108
```
56109

57-
## Architecture
58-
```
59-
backend/app/
60-
├── api/v1/ # API endpoints (auth, books, blog, messages, weread, rss, admin, ai, todos, monitor)
61-
├── models/ # SQLAlchemy 2.0 (models.py) + MongoDB Beanie (beanie.py)
62-
├── schemas/ # Pydantic schemas (per-domain: auth, book, blog, rss, etc.)
63-
├── repositories/ # Data access layer
64-
├── services/ # Business logic
65-
├── core/ # Config, logging, AI agent
66-
├── utils/ # Utility functions
67-
├── tasks/ # Taskiq async tasks
68-
└── main.py # FastAPI entry point
69-
70-
frontend/src/
71-
├── views/ # Page components
72-
├── components/ # Reusable Vue components
73-
├── auth/ # Authentication logic
74-
├── service/ # API calls and business logic
75-
├── stores/ # Pinia state management
76-
├── router/ # Vue Router config
77-
├── types/ # TypeScript type definitions
78-
├── lib/ # Third-party library wrappers
79-
├── utils/ # Utility functions
80-
├── layouts/ # Layout components
81-
└── assets/ # Static assets
110+
### Scripts (`cd scripts`)
111+
112+
```bash
113+
npm run parse-ua
82114
```
83115

84-
## Tech Stack
85-
- **Backend**: FastAPI, SQLAlchemy 2.0, Alembic, PostgreSQL, MongoDB (Beanie), Redis, Taskiq
86-
- **Frontend**: Vue 3.5, TypeScript, Vite, Tailwind CSS v4, Pinia, shadcn-vue, motion-v
87-
- **AI**: Agno
88-
- **Ports**: Backend `:5555`, Frontend `:5173`
116+
### Single-test strategy
117+
118+
- Pytest: prefer exact node id (`file::test_name`).
119+
- Vitest: prefer `file:line`, fallback to `-t`.
120+
- Playwright: prefer `file:line`, fallback to `-g`.
121+
- Use fuzzy matching only when exact location is unknown.
89122

90-
## Code Style
123+
---
124+
125+
## 4) Code Style Guidelines
91126

92127
### Backend (Python)
93-
- Ruff config (`ruff.toml`): 79 char line width, 4-space indent, double quotes, Python 3.14 target
94-
- Type annotations: modern Python 3.14+ syntax (`list[str]` not `List[str]`)
95-
- Naming: `snake_case` for functions/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants
96-
- No bare `except:` — always specify exception type
97-
- Google-style docstrings for all public functions/classes
98-
- Use `async/await` for all database operations
99-
- Import order: stdlib → third-party → local (isort)
100-
- Absolute imports only: `from app.xxx import ...`
101-
- Schemas split by domain in `app/schemas/` (auth, book, blog, rss, etc.)
102-
103-
### Frontend (Vue/TypeScript)
104-
- Always use `<script setup lang="ts">` + Composition API (no Options API)
105-
- Strict TypeScript: avoid `any`, use `unknown` + type guards
106-
- Naming: `camelCase` for functions/variables, `PascalCase` for components/types
107-
- Component files: `PascalCase.vue`, utility files: `camelCase.ts`
108-
- Prefer Tailwind CSS utilities over custom CSS
109-
- Use `@/` alias for imports from `frontend/src/`
110-
- Package manager: `pnpm` only, never `npm`
111-
112-
### Error Handling
113-
- Backend: raise custom exceptions in services, catch in API layer with proper HTTP status codes
114-
- Frontend: use try/catch in async handlers, show user-friendly messages via notification store
115-
- Never swallow errors silently — always log or notify
116-
117-
## Commit Guidelines
118-
1. Backend pre-commit: `cd backend && ruff format . && ruff check .`
119-
2. Frontend pre-commit: `cd frontend && pnpm format && pnpm lint && pnpm type-check`
120-
3. Commit messages: Conventional Commits (`feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`)
121-
4. Branch naming: `feature/xxx`, `fix/xxx`, `refactor/xxx`
122-
5. Never commit: `.env`, `node_modules/`, `.venv/`, `__pycache__/`, temp files
128+
129+
- Python: `>=3.14`; Ruff target: `py314`
130+
- Formatting: line length `79`, 4-space indent, double quotes, LF
131+
- Imports:
132+
- absolute imports only (`from app...`)
133+
- no relative imports
134+
- order: stdlib → third-party → first-party/local
135+
- Types: modern annotations (`list[str]`, `dict[str, str]`, `A | B`)
136+
- Naming:
137+
- functions/variables: `snake_case`
138+
- classes: `PascalCase`
139+
- constants: `UPPER_SNAKE_CASE`
140+
- Error handling:
141+
- never use bare `except:`
142+
- services raise domain errors, API layer maps HTTP responses
143+
- never swallow errors silently
144+
- Async: prefer async/await for DB-related operations
145+
146+
### Frontend (Vue + TypeScript)
147+
148+
- Use `<script setup lang="ts">` + Composition API
149+
- Type safety:
150+
- avoid `any`
151+
- use `unknown` + narrowing for external inputs
152+
- keep props/emits/store types explicit
153+
- Naming:
154+
- variables/functions: `camelCase`
155+
- components/types: `PascalCase`
156+
- component file: `PascalCase.vue`
157+
- utility file: `camelCase.ts`
158+
- Imports: use alias `@/` for `frontend/src/*`
159+
- Styling: prefer Tailwind utilities
160+
- Package manager: frontend uses `pnpm` only
161+
- Error handling:
162+
- async flows use try/catch
163+
- narrow caught values before property access
164+
- route user-visible failures to notification flows
165+
166+
---
167+
168+
## 5) Architecture & Boundaries
169+
170+
- Backend layering: `api -> service -> repository`
171+
- Keep business logic in services; keep data access in repositories
172+
- Keep request/response contracts in schemas
173+
- Frontend layering:
174+
- `views/`: page composition
175+
- `components/`: reusable UI
176+
- `stores/`: state management
177+
- `service/`: API communication
178+
- `router/`: route definitions and guards
179+
180+
## 6) Cursor / Copilot Rules Status
181+
182+
Checked in repository:
183+
184+
- `.cursorrules`: not found
185+
- `.cursor/rules/`: not found
186+
- `.github/copilot-instructions.md`: not found
187+
188+
If these files are added later, merge their explicit constraints here.

0 commit comments

Comments
 (0)