From 1297e33c6246ff5697a2c935104fbcf64b7fb465 Mon Sep 17 00:00:00 2001 From: Huang Xin Date: Sat, 14 Mar 2026 11:37:41 +0800 Subject: [PATCH] doc(agent): add rules files that are automatically loaded into context alongside CLAUDE.md (#3532) --- .github/workflows/pull-request.yml | 2 +- .gitignore | 5 ++-- README.md | 2 +- .../.claude/rules/build-constraints.md | 5 ++++ apps/readest-app/.claude/rules/test-first.md | 5 ++++ apps/readest-app/.claude/rules/typescript.md | 5 ++++ .../readest-app/.claude/rules/verification.md | 8 +++++++ apps/readest-app/.gitignore | 2 ++ apps/readest-app/AGENTS.md | 23 ++++--------------- apps/readest-app/package.json | 3 ++- package.json | 2 ++ 11 files changed, 38 insertions(+), 24 deletions(-) create mode 100644 apps/readest-app/.claude/rules/build-constraints.md create mode 100644 apps/readest-app/.claude/rules/test-first.md create mode 100644 apps/readest-app/.claude/rules/typescript.md create mode 100644 apps/readest-app/.claude/rules/verification.md diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 312a72f6..1c535822 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -35,7 +35,7 @@ jobs: run: | sudo apt-get update sudo apt-get install -y pkg-config libfontconfig-dev libglib2.0-dev libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev libsoup-3.0-dev - - name: Format + - name: Format check working-directory: apps/readest-app/src-tauri run: cargo fmt --check - name: Clippy Check diff --git a/.gitignore b/.gitignore index 4d29ec2e..c33a8de3 100644 --- a/.gitignore +++ b/.gitignore @@ -47,7 +47,8 @@ fastlane/report.xml # nix result* - .playwright-mcp/ -.claude/ + +.claude/worktrees +.claude/settings.local.json diff --git a/README.md b/README.md index 34ea2a6e..2137e732 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ | **Feature** | **Description** | **Status** | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------- | -| **Multi-Format Support** | Support EPUB, MOBI, KF8 (AZW3), FB2, CBZ, TXT, PDF (experimental) | ✅ | +| **Multi-Format Support** | Support EPUB, MOBI, KF8 (AZW3), FB2, CBZ, TXT, PDF | ✅ | | **Scroll/Page View Modes** | Switch between scrolling or paginated reading modes. | ✅ | | **Full-Text Search** | Search across the entire book to find relevant sections. | ✅ | | **Annotations and Highlighting** | Add highlights, bookmarks, and notes to enhance your reading experience and use instant mode for quicker interactions. | ✅ | diff --git a/apps/readest-app/.claude/rules/build-constraints.md b/apps/readest-app/.claude/rules/build-constraints.md new file mode 100644 index 00000000..9b2f2d9f --- /dev/null +++ b/apps/readest-app/.claude/rules/build-constraints.md @@ -0,0 +1,5 @@ +## Build Constraints + +- No optional chaining (`?.`) in build output — verified by `check:optional-chaining`. +- No lookbehind regex in build output — verified by `check:lookbehind-regex`. +- Run `pnpm build-check` (builds both targets + runs all checks) before submitting. diff --git a/apps/readest-app/.claude/rules/test-first.md b/apps/readest-app/.claude/rules/test-first.md new file mode 100644 index 00000000..722f3721 --- /dev/null +++ b/apps/readest-app/.claude/rules/test-first.md @@ -0,0 +1,5 @@ +## Test-First Development + +- Always write a failing unit test **before** implementing a fix. +- Run the test to confirm it reproduces the bug or fails as expected, then apply the fix and verify the test passes. +- Run the full test suite (`pnpm test`) after changes to ensure no regressions. diff --git a/apps/readest-app/.claude/rules/typescript.md b/apps/readest-app/.claude/rules/typescript.md new file mode 100644 index 00000000..fb666743 --- /dev/null +++ b/apps/readest-app/.claude/rules/typescript.md @@ -0,0 +1,5 @@ +## TypeScript + +- Never use the `any` type. Use `unknown`, proper types, or generics instead. +- Strict mode is enabled. Target is ES2022. +- Unused vars prefixed with `_` are allowed (ESLint configured). diff --git a/apps/readest-app/.claude/rules/verification.md b/apps/readest-app/.claude/rules/verification.md new file mode 100644 index 00000000..6d23c130 --- /dev/null +++ b/apps/readest-app/.claude/rules/verification.md @@ -0,0 +1,8 @@ +## Verification (done-conditions) + +Before marking work complete, all applicable checks must pass: + +1. `pnpm test` — unit tests +2. `pnpm lint` — ESLint +3. `pnpm fmt:check` — Rust format check (only when `src-tauri/` files changed) +4. `pnpm clippy:check` — Rust lint (only when `src-tauri/` files changed) diff --git a/apps/readest-app/.gitignore b/apps/readest-app/.gitignore index 58b27ade..838fa94c 100644 --- a/apps/readest-app/.gitignore +++ b/apps/readest-app/.gitignore @@ -64,3 +64,5 @@ src-tauri/gen /public/swe-worker-*.js /dist/ + +.claude/settings.local.json \ No newline at end of file diff --git a/apps/readest-app/AGENTS.md b/apps/readest-app/AGENTS.md index 72df3adc..9a0e65bd 100644 --- a/apps/readest-app/AGENTS.md +++ b/apps/readest-app/AGENTS.md @@ -6,7 +6,7 @@ Readest is a cross-platform ebook reader built as a **Next.js 16 + Tauri v2** hy ```bash # Development -pnpm dev-web # Web-only dev server (no Rust compilation needed) +pnpm dev-web # Web-only dev server (no Rust compilation needed) pnpm tauri dev # Desktop dev with Tauri (compiles Rust backend) # Building @@ -27,7 +27,8 @@ pnpm format # Prettier (runs from monorepo root) pnpm format:check # Check formatting without writing # Rust -pnpm clippy # Lint Rust code (src-tauri) +pnpm fmt:check # Check formatting Rust code (src-tauri) +pnpm clippy:check # Lint Rust code (src-tauri) ``` ### Source Layout @@ -57,23 +58,7 @@ Platform-specific code lives in `src-tauri/src/{macos,windows,android,ios}/`. Cu ## Project Rules -### Test-First Development - -- Always write a failing unit test **before** implementing a fix. -- Run the test to confirm it reproduces the bug or fails as expected, then apply the fix and verify the test passes. -- Run the full test suite (`pnpm test`) after changes to ensure no regressions. - -### TypeScript - -- Never use the `any` type. Use `unknown`, proper types, or generics instead. -- Strict mode is enabled. Target is ES2022. -- Unused vars prefixed with `_` are allowed (ESLint configured). - -### Build Constraints - -- No optional chaining (`?.`) in build output — verified by `check:optional-chaining`. -- No lookbehind regex in build output — verified by `check:lookbehind-regex`. -- Run `pnpm build-check` (builds both targets + runs all checks) before submitting. +Rules are in `.claude/rules/`: test-first, typescript, build-constraints, verification. ### i18n diff --git a/apps/readest-app/package.json b/apps/readest-app/package.json index b2a0eef8..0051b5e8 100644 --- a/apps/readest-app/package.json +++ b/apps/readest-app/package.json @@ -26,7 +26,8 @@ "tauri:dev:test": "dotenv -e .env.tauri -- tauri dev --features webdriver", "tauri:build:test": "dotenv -e .env.tauri -- tauri build --debug --features webdriver", "tauri": "tauri", - "clippy": "cargo clippy -p Readest --no-deps -- -D warnings", + "fmt:check": "cargo fmt -p Readest --check", + "clippy:check": "cargo clippy -p Readest --no-deps -- -D warnings", "format": "pnpm -w format", "format:check": "pnpm -w format:check", "prepare-public-vendor": "mkdirp ./public/vendor/pdfjs ./public/vendor/simplecc", diff --git a/package.json b/package.json index 55494f59..9081e4d7 100644 --- a/package.json +++ b/package.json @@ -7,6 +7,8 @@ "tauri": "pnpm --filter @readest/readest-app tauri", "dev-web": "pnpm --filter @readest/readest-app dev-web", "prepare": "husky", + "fmt:check": "pnpm --filter @readest/readest-app fmt:check", + "clippy:check": "pnpm --filter @readest/readest-app clippy:check", "format": "prettier --write \"**/*.{js,jsx,ts,tsx,css,json,md,html,yml}\"", "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,css,json,md,html,yml}\"" },