From 928a35b7cb5fdf9180110de81d9f842a18ffb999 Mon Sep 17 00:00:00 2001 From: Dream Hunter Date: Wed, 4 Mar 2026 10:06:43 +0800 Subject: [PATCH] docs: update CLAUDE.md and remove AGENTS.md (#854) Consolidate AGENTS.md into CLAUDE.md with enhanced guidance: - Add post-task checklist requiring changelog and docs updates - Add auth headers reference - Add squash merge convention Co-authored-by: Claude Opus 4.6 --- AGENTS.md | 35 ---------------------------- CLAUDE.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 67 insertions(+), 36 deletions(-) delete mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 77f97b58..00000000 --- a/AGENTS.md +++ /dev/null @@ -1,35 +0,0 @@ -# Repository Guidelines - -## Project Structure -- Backend: `worker/` (Workers API; entry `worker/src/worker.ts`, APIs under `worker/src/*_api/`). -- Frontend: `frontend/` (Vue 3 app; routes in `frontend/src/router/`). -- Pages middleware: `pages/functions/_middleware.js`. -- Mail parser: `mail-parser-wasm/` (Rust WASM). -- SMTP/IMAP proxy: `smtp_proxy_server/`. -- DB schema/migrations: `db/`. -- Docs: `vitepress-docs/`. - -## Build & Dev Commands -Run inside each folder: -- Frontend: `pnpm dev`, `pnpm build`. -- Worker: `pnpm dev`, `pnpm lint`, `pnpm build`. -- Pages: `pnpm dev`. -- Docs: `pnpm dev` in `vitepress-docs/`. -- WASM: `wasm-pack build --release` in `mail-parser-wasm/`. -- SMTP proxy: `pip install -r smtp_proxy_server/requirements.txt` then `python smtp_proxy_server/main.py`. - -## Coding Style -- Follow existing module style. `worker/` uses TypeScript + ESLint; `frontend/` uses Vue SFCs. -- Keep current naming patterns: `*_api/`, `utils/`, `models/`. -- ESM imports only (`type: module`). - -## Testing -- No formal test runner. Validate with local dev servers and key flows (login, inbox, send/receive). - -## Commits & PRs -- Use Conventional Commits (`feat:`, `fix:`, `docs:`). Recent history includes PR numbers like `(#123)`. -- PRs should explain scope and add screenshots for UI changes. - -## Config Tips -- Worker settings in `worker/wrangler.toml` (see template for bindings). -- Frontend uses `VITE_*` env vars. Don’t commit secrets. diff --git a/CLAUDE.md b/CLAUDE.md index 51acb363..144ad576 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1,67 @@ -READ AGENTS.md FOR INSTRUCTIONS ON HOW TO USE THIS FILE. +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Structure + +- **Backend**: `worker/` — Cloudflare Workers API using Hono framework. Entry: `worker/src/worker.ts`, APIs under `worker/src/*_api/`. +- **Frontend**: `frontend/` — Vue 3 + Naive UI app deployed to Cloudflare Pages. Routes in `frontend/src/router/`. +- **Pages middleware**: `pages/functions/_middleware.js` — Routes API calls to Worker backend. +- **Mail parser**: `mail-parser-wasm/` — Rust WASM email parser. +- **SMTP/IMAP proxy**: `smtp_proxy_server/` — Python proxy server. +- **DB schema/migrations**: `db/` — SQLite via Cloudflare D1, dated migration patches. +- **Docs**: `vitepress-docs/` — VitePress documentation site (zh + en). +- **Changelogs**: `CHANGELOG.md` (中文) + `CHANGELOG_EN.md` (English). + +## Build & Dev Commands + +Run inside each subfolder with `pnpm`: + +| Folder | Dev | Build | Lint | Deploy | +|--------|-----|-------|------|--------| +| `worker/` | `pnpm dev` | `pnpm build` | `pnpm lint` | `pnpm deploy` | +| `frontend/` | `pnpm dev` | `pnpm build` | — | `pnpm deploy` | +| `vitepress-docs/` | `pnpm dev` | `pnpm build` | — | — | +| `mail-parser-wasm/` | — | `wasm-pack build --release` | — | — | + +SMTP proxy: `pip install -r smtp_proxy_server/requirements.txt` then `python smtp_proxy_server/main.py`. + +## Coding Style + +- `worker/` uses TypeScript + ESLint; `frontend/` uses Vue SFCs. +- Keep existing naming patterns: `*_api/` folders, `utils/`, `models/`. +- ESM imports only (`type: module`). + +## Auth Headers + +- Address JWT: `x-user-token` +- User JWT: `x-user-access-token` +- Admin: `x-admin-auth` +- Language: `x-lang` + +## Commits & PRs + +- Use Conventional Commits: `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `perf:`. +- PRs should explain scope; add screenshots for UI changes. +- Use squash merge for PRs. + +## Post-Task Checklist (IMPORTANT) + +After completing any feature, bug fix, or improvement, **always check**: + +1. **CHANGELOG.md** (中文) and **CHANGELOG_EN.md** (English) — both must be updated under the current `(main)` version section with the change entry. Follow the existing format: `- feat/fix/docs: |模块| 描述`. +2. **Documentation** — if the change involves new environment variables, new API endpoints, or configuration changes, update the corresponding docs in `vitepress-docs/docs/zh/` and `vitepress-docs/docs/en/`. Key files: + - `guide/worker-vars.md` — Worker environment variables + - `guide/ui/` — Frontend deployment docs + - `guide/feature/` — Feature-specific docs + - `api/` — API reference docs +3. **Both languages** — docs and changelogs exist in Chinese and English; always update both. + +## Testing + +No formal test runner. Validate with local dev servers and key flows (login, inbox, send/receive). + +## Config + +- Worker settings in `worker/wrangler.toml` (see `wrangler.toml.template` for bindings). +- Frontend uses `VITE_*` env vars. Don't commit secrets.